AI Skill Report Card

Creating Claude Skills

Packages professional expertise or methodology into Claude Code agent skill format (SKILL.md with YAML frontmatter, workflow, examples, best practices). Use when asked to create a skill file, convert a workflow/methodology into a skill, or package expertise for Claude agents.

A-86·Nov 19, 2026·Source: Extension-page

Create a Claude Code agent skill file from a description of expertise or a methodology.

13 / 15

Given input like "I'm an expert at reviewing pull requests for security issues," produce a complete SKILL.md starting with YAML frontmatter:

YAML
--- name: reviewing-pr-security description: Reviews pull requests for security vulnerabilities including injection, auth bypass, and secrets exposure. Use when reviewing a PR, auditing code changes, or asked to check code for security issues. ---

...followed by Quick Start, Workflow, Examples, Best Practices, and Common Pitfalls sections.

Recommendation▾
Add an example showing a mid-complexity input (between the rich tax example and the placeholder) to show calibration
14 / 15

Progress:

  • Step 1: Identify the core expertise/methodology being described
  • Step 2: Derive a gerund-form, kebab-case name (max 64 chars)
  • Step 3: Write a third-person description with explicit trigger phrases (max 1024 chars)
  • Step 4: Write a Quick Start with a concrete, runnable/actionable example
  • Step 5: Break the methodology into discrete workflow steps (checklist if complex)
  • Step 6: Write 1-3 concrete Example input/output pairs
  • Step 7: List Best Practices specific to this domain
  • Step 8: List Common Pitfalls to avoid
  • Step 9: Check total length (~500 lines); if longer, note splitting into reference files

Step 1 — Extract methodology: Read the input for: what the person does, what decisions they make, what order they make them in, what rules of thumb they apply, what mistakes they avoid. If the input is vague, infer a reasonable, narrow methodology rather than a generic one.

Step 2 — Name: Use verb-ing + object, e.g. analyzing-financial-statements, negotiating-contracts. Avoid vague names like helping-users or doing-tasks.

Step 3 — Description: Must read naturally in third person and pack in triggers: "Use when X, Y, or Z." Triggers should be phrases a user would actually type.

Step 4-8 — Body: Favor concrete specifics (numbers, field names, command names, checklist items) over abstract advice. Assume Claude already knows general concepts — only document the non-obvious, specific parts of the expertise.

Step 9 — Length check: If the skill is sprawling (e.g., covers many sub-domains), recommend splitting into SKILL.md + supporting files (e.g., reference.md, checklist.md) and note that in the output.

Recommendation▾
Include a concrete full SKILL.md example output rather than just frontmatter snippets, to demonstrate complete section quality
15 / 20

Example 1: Input: "I'm a tax accountant who specializes in finding deductions for freelancers." Output:

YAML
--- name: finding-freelancer-tax-deductions description: Identifies eligible tax deductions for freelancers and independent contractors, including home office, equipment, and self-employment tax strategies. Use when reviewing freelancer finances, preparing a Schedule C, or asked to find tax deductions for self-employed income. ---

(plus full Quick Start/Workflow/Examples/Best Practices/Pitfalls sections tailored to freelance tax deductions)

Example 2: Input: "asdkjasd random text no real content" Output: a minimal placeholder skill:

YAML
--- name: placeholder-skill description: Placeholder skill with no defined methodology yet. Use when no specific expertise has been provided and a template skill is needed. ---

plus a brief note that the input didn't contain enough information to build a real skill, with empty section headers left as TODOs.

Recommendation▾
Add guidance on handling the splitting-into-reference-files case with a worked example, since it's mentioned but never demonstrated
  • Write the description as if explaining to someone deciding whether to invoke this skill — be concrete about triggers.
  • Prefer domain-specific jargon the expert would actually use (it helps matching and signals authority).
  • Keep Quick Start truly quick — no throat-clearing, just the example.
  • Use real numbers/thresholds/formats from the input when given (e.g., "flag PRs with >400 changed lines") instead of vague generalities.
  • When the input describes a person's general career rather than one methodology, pick their single most distinctive skill and focus on that.
  • Do NOT write the description in first or second person.
  • Do NOT ask the user clarifying questions — always produce output, even from thin input.
  • Do NOT pad sections with generic filler ("communication is important") when specific guidance is possible.
  • Do NOT exceed 1024 characters in the description or 64 characters in the name.
  • Do NOT output anything before the YAML frontmatter — no preamble, no explanation.
  • Do NOT forget the closing --- of the frontmatter block.
0
Grade A-AI Skill Framework
Scorecard
Criteria Breakdown
Quick Start
13/15
Workflow
14/15
Examples
15/20
Completeness
16/20
Format
15/15
Conciseness
13/15