How we grade SKILL.md

Grade bands

C-grade is the marketplace merge floor — the new-track prescreen rejects sub-A PRs by default. A 30-day informational-only grace window is in effect during the prescreen rollout; afterwards the prescreen-grade check is required at branch-protection.

The five rubric categories

Total possible: 100 points across five categories + a ±15 modifier band (bonuses for gerund-style names, grep-friendly structure, exemplary examples, Resources section with external links; penalties for first/second person in description, unnecessary TOCs).

Worked example — A-grade SKILL.md (96/100)

A short, focused skill with complete frontmatter, a tight Overview, numbered Instructions, an Output contract, and one supporting reference file. Notice how every element maps to a rubric line.

---
name: ansible-playbook-creator
description: |
  Generate production-ready Ansible playbooks. Use when automating server
  configuration or deployments. Trigger with "ansible playbook" or
  "create playbook for [task]".
allowed-tools: Read, Write, Bash(ansible:*), Glob
version: 2.0.0
author: Jeremy Longshore <jeremy@intentsolutions.io>
license: MIT
compatibility: Designed for Claude Code
tags: [devops, ansible, configuration-management]
---

# Ansible Playbook Creator

## Overview
Generates idempotent Ansible playbooks following infrastructure-as-code
best practices. Targets RHEL, Ubuntu, and Amazon Linux 2023.

## Prerequisites
- Target host SSH access
- Ansible 2.14+ installed locally
- ansible-lint for the validation step

## Instructions
1. Gather target host details and the desired state spec from the user
2. Select appropriate Ansible modules from references/module-cheatsheet.md
3. Generate playbook with proper variable templating in vars/
4. Validate syntax with `ansible-lint -p`
5. Output the playbook with a "next steps" block

## Output
- Complete playbook YAML ready for `ansible-playbook` execution
- Inline comments on any non-obvious module choice
- A "next steps" block listing dry-run + production-run commands

## Error Handling
If ansible-lint fails, surface the rule violation verbatim and propose
the smallest fix. Do not silently retry.

## Examples
**Example 1: Web server setup**
Input: "Set up nginx with Let's Encrypt on Ubuntu 24.04"
Output: playbook with system role + nginx role + certbot role.

## Resources
- references/module-cheatsheet.md — top 40 modules by frequency

Why this lands at A: body is ~80 lines (Token Economy 10/10), references/ exists with content (Layered Structure 10/10), 8 H2 sections (Navigation 5/5, Workflow 5/5), description has both "Use when" and "Trigger with" plus action verbs (Discoverability 6/6), all 8 required frontmatter fields present (Metadata 10/10, Frontmatter Validity 5/5), imperative voice, no first/second person, ≤2000 words (Writing 10/10). Modifiers: +1 grep-friendly, +1 Resources section.

Worked example — C-grade SKILL.md (74/100) and the deltas to A

A common shape we see in PRs that fail the prescreen: required fields present but description is weak, no references/, body is mostly prose with few numbered steps. Each delta below is one or more rubric points.

---
name: AnsiblePlaybookGenerator   # ⚠ not kebab-case → Name Conventions -2
description: I can generate Ansible playbooks for you.   # ⚠ first person + no "Use when" / no "Trigger with" → Discoverability -4, Desc Quality -2
allowed-tools: "*"   # ⚠ wildcard, not scoped → ignored by rubric but Tier 2 production gate will flag
version: 1.0.0
author: Anon   # ⚠ no email → Metadata -1
license: MIT
compatibility: Designed for Claude Code
tags: [ansible]
---

# Ansible Playbook Generator

You should use this skill when you want to generate Ansible playbooks.
It works by figuring out what you need and writing the YAML for you.

The skill will create the playbook and you can then run it.

You can configure it with various options.

Deltas to reach A:

• Rename to ansible-playbook-generator (kebab-case + matches folder) → Name Conventions +2, Terminology +2
• Rewrite description: Generate production-ready Ansible playbooks. Use when … Trigger with … → Discoverability +4, Description Quality +2, Metadata Quality +3
• Scope allowed-tools to Read, Write, Bash(ansible:*), Glob — Tier 2 production gate stops flagging
• Add author email — Metadata +1
• Add Overview, Prerequisites, numbered Instructions, Output, Error Handling, Examples, Resources sections (≥7 H2s) → Workflow +5, Navigation +1, Problem Solving +8, Feedback Loops +4, Examples +3
• Add a references/ directory with one supporting file → Layered Structure +10
• Rewrite body in imperative voice ("Generate playbook with …", not "You can configure it") → Voice +0 (already ok), Objectivity +2