AI Skill Report Card

Packaging Claude Skills

Packages professional expertise into Claude Code agent skill format, including YAML frontmatter, workflow structure, and zip/upload-ready files. Use when converting a described methodology into a SKILL.md file or preparing a skill for upload to Claude.

B+74·Nov 19, 2026·Source: Extension-page
12 / 15

Create a file named SKILL.md starting with YAML frontmatter:

YAML
--- name: writing-unit-tests description: Writes thorough unit tests for existing code following AAA pattern. Use when asked to add test coverage, write tests for a function, or review test quality. ---

Then add Quick Start, Workflow, Examples, Best Practices, and Common Pitfalls sections. Save as SKILL.md. If packaging for upload, zip it (optionally with supporting files) so the archive contains SKILL.md at the root or in a single top-level folder.

Recommendation▾
Example outputs are mostly described rather than fully shown—include a complete rendered SKILL.md example end-to-end rather than truncating with parenthetical summaries.
13 / 15

Progress:

  • Step 1: Identify the core expertise/methodology to capture
  • 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: Draft Quick Start with a concrete, runnable example
  • Step 5: Write Workflow as numbered/checklist steps
  • Step 6: Add 2+ concrete Input/Output examples
  • Step 7: Add Best Practices and Common Pitfalls
  • Step 8: Validate file starts with --- frontmatter and stays near ~500 lines
  • Step 9: If uploading as zip, bundle SKILL.md (+ assets) and confirm security scan passes
Recommendation▾
Add a third example showing a bad/incorrect skill file (e.g., wrong frontmatter placement or first-person description) alongside the fix, to reinforce the good/bad contrast.
12 / 20

Example 1: Input: "Someone who reviews legal contracts for hidden liability clauses." Output:

YAML
--- name: reviewing-contract-liability description: Identifies hidden liability, indemnification, and risk-shifting clauses in legal contracts. Use when asked to review a contract, flag risky clauses, or assess liability exposure. ---

(followed by Quick Start showing a sample clause flagged, Workflow steps for scanning sections, Examples of risky vs. safe clause language, Best Practices like "always check indemnification caps," Common Pitfalls like "don't skip exhibit/appendix sections")

Example 2: Input: "A single .md file skill upload that must start with YAML frontmatter." Output: A SKILL.md file beginning exactly with ---, containing name and description keys, followed by structured sections — validated before zipping so the upload's security scan and format check succeed.

Recommendation▾
Clarify the zip/upload mechanics further (e.g., exact CLI or UI steps) since that's a named use case in the description but only briefly covered.
  • Always lead the file with --- on line 1 — no preamble text before frontmatter.
  • Keep name descriptive but short; prefer the clearest gerund phrase over cleverness.
  • Pack trigger phrases into description ("Use when...") so the skill activates correctly.
  • Favor concrete defaults over configurable options in Workflow and Best Practices.
  • When zipping, keep the archive minimal — SKILL.md plus only essential supporting assets.
  • Don't write the description in first or second person ("I will..." / "You should...").
  • Don't exceed 64 chars for name or 1024 chars for description.
  • Don't omit the YAML frontmatter or add text before it.
  • Don't let the file balloon past ~500 lines — split supporting detail into separate reference files instead.
  • Don't forget the .zip/.skill must actually contain SKILL.md or the upload will fail validation.
0
Grade B+AI Skill Framework
Scorecard
Criteria Breakdown
Quick Start
12/15
Workflow
13/15
Examples
12/20
Completeness
15/20
Format
14/15
Conciseness
13/15