Reviewing Skills

Reviewing Skills

Audit one or more Agent Skills for quality, discoverability, consistency, and adherence to the Anthropic skill-authoring best practices.

Contents

• Contents
• How to use this skill
• Related skills
• Input
• Review checklist
  • 1. Frontmatter
  • 2. Description quality
  • 3. Body structure and size
  • 4. Conciseness
  • 5. Degrees of freedom
  • 6. Progressive disclosure
  • 7. Workflows and feedback loops
  • 8. Content quality
  • 9. Cross-skill consistency
  • 10. Discoverability sections
• Output
• Reference: Anthropic best-practices summary

How to use this skill

Attach this file to your Copilot Chat context, then invoke it with the skill folder or SKILL.md file(s) to review. Examples:

Using the Reviewing Skills skill, review .github/skills/command-implementation/.

Review all skills under .github/skills/ for best-practice compliance.

Related skills

• Make Skill Template — scaffold new skills; use this reviewing skill afterward to validate quality
• PR Readiness Review — final pre-PR quality gate (broader than skill-specific review)

Input

One or more skill directories or SKILL.md files from .github/skills/.

Review checklist

Work through each section below for every skill under review.

1. Frontmatter

• name is present, 1-64 chars, lowercase letters/numbers/hyphens only
• name matches the folder name exactly
• name does not contain reserved words (anthropic, claude)
• description is present, 1-1024 chars
• description does not contain XML tags

2. Description quality

The description is the primary discovery mechanism — it determines whether the skill is selected from potentially hundreds of available skills.

• Written in third person (not "I can…" or "You can…")
• Describes what the skill does (capabilities)
• Describes when to use it (triggers, scenarios, keywords)
• Includes specific key terms users are likely to mention
• Is not vague (e.g. "Helps with documents" is too vague)

3. Body structure and size

• SKILL.md body targets under 500 lines and is reviewed carefully above 600 lines
• Exceeding the target is justified when splitting always-needed workflow or review rules would make the skill less effective
• If approaching the limit, situational content is split into separate reference files before core workflows or checklists are split
• Reference files are at most one level deep from SKILL.md (no deeply-nested chains like SKILL → A.md → B.md → actual content)
• Reference files longer than 100 lines include a table of contents
• Reference files state their purpose and when the agent should load them

4. Conciseness

Every token in a loaded skill competes with conversation history and other context. Challenge each piece of information:

• Only includes context the model does not already have
• Does not over-explain concepts the model already knows
• Avoids redundant paragraphs or verbose preambles
• Uses code examples instead of lengthy prose where possible

5. Degrees of freedom

Match instruction specificity to task fragility:

• High freedom (general text guidance) for tasks where multiple approaches are valid and context determines the best route
• Medium freedom (pseudocode / parameterized templates) for tasks with a preferred pattern but acceptable variation
• Low freedom (exact scripts, no parameters) for fragile or error-prone operations where consistency is critical
• The chosen level is appropriate for the skill's domain

6. Progressive disclosure

• SKILL.md serves as an overview / table of contents
• Detailed materials are in separate files loaded only when needed
• Mandatory workflow steps, validation loops, and review checklist items stay in SKILL.md even when detailed examples move to references
• Situational, element-specific, type-specific, or platform-specific rules are good candidates for reference files
• File names are descriptive (not doc1.md, file2.md)
• Directory structure is organized by domain or feature

7. Workflows and feedback loops

• Complex multi-step operations are broken into clear, sequential steps
• Long workflows include a progress checklist the agent can track
• Validation / feedback loops are present for quality-critical tasks (run validator → fix errors → repeat until clean)
• Decision points use conditional workflow patterns (if X → workflow A, if Y → workflow B)
• For standards and review skills, rules are mandatory unless explicitly marked Optional; advisory skills consistently distinguish requirements, recommendations, and examples