Review Skills
Review and analyze a skill against best practices for length, intent scope, and trigger patterns.
Prerequisites
Before analyzing, read these resources to understand skill writing principles:
./references/skill-creator/SKILL.md- Core principles, anatomy, and progressive disclosurereferences/spec.md- Complete Agent Skills specification (required for compliance checks)references/validate.md- Validation checklist (used in Step 2)./references/skill-creator/references/workflows.md- Workflow patterns (if relevant)./references/skill-creator/references/output-patterns.md- Output patterns (if relevant)
Reference Examples from Anthropic (REQUIRED)
You MUST read reference skills from Anthropic's repository before analyzing. This is essential for calibrating your review.
-
Ensure cache is available: Check if
./.cache/anthropics-skills/exists. If not (or if stale), run:bashpython scripts/download_anthropics_skills.py -
Read at least 3 reference skills: Before analyzing, read these SKILL.md files from
./.cache/anthropics-skills/skills/:Always read these high-quality examples:
pdf/SKILL.md- Well-structured workflow skill with clear triggersdocx/SKILL.md- Good example of document processing patternsskill-creator/SKILL.md- Meta-skill showing best practices
Then read 1-2 skills similar to the one being reviewed:
- For workflow-based skills:
xlsx/SKILL.md,pptx/SKILL.md - For tool/API skills:
mcp-builder/SKILL.md - For creative/design skills:
brand-guidelines/SKILL.md,frontend-design/SKILL.md - For testing skills:
webapp-testing/SKILL.md
-
Note patterns to compare: As you read, note:
- How descriptions are structured (trigger patterns)
- Length and depth of SKILL.md body
- How references are organized and used
- Balance between brevity and completeness
Steps
Step 1: Receive the Skill to Review
The user must provide a skill folder/path to review. If not provided, prompt:
"Please provide the path to the skill folder you want to review (e.g.,
.claude/skills/my-skill/)"
Step 2: Validate Skill Structure
Using the validation checklist (references/validate.md), verify the skill passes all basic checks:
- File Structure: SKILL.md exists
- Frontmatter Format: Valid YAML between
---delimiters - Allowed Properties: Only
name,description,license,compatibility,metadata,allowed-tools - Name Validation:
- Hyphen-case only (lowercase, digits, hyphens)
- No start/end hyphens, no consecutive hyphens (
--) - Max 64 characters
- Matches directory name
- Description Validation:
- No angle brackets (
<or>) - Max 1024 characters
- Non-empty
- No angle brackets (
If validation fails: Stop the review and report the specific validation error(s). The skill must pass basic validation before proceeding with the full review.
Step 3: Read the Skill
Read the complete skill structure:
SKILL.md(frontmatter and body)- Any files in
references/,scripts/,assets/directories
IMPORTANT: Only analyze the skill provided by the user.
Step 4: Verify Spec Compliance
Check that the skill follows the Agent Skills specification (references/spec.md). Verify:
Directory Structure
- Skill is in a directory matching the
namefield - Contains required
SKILL.mdfile - Optional directories follow conventions:
scripts/,references/,assets/
Frontmatter Compliance
| Field | Check |
|---|---|
name | 1-64 chars, lowercase alphanumeric + hyphens, no start/end hyphens, no --, matches directory name |
description | 1-1024 chars, non-empty, describes what and when |
license | If present, short (license name or file reference) |
compatibility | If present, max 500 chars |
metadata | If present, string keys to string values |
allowed-tools | If present, space-delimited tool list |
Body Content
- Markdown format after frontmatter
- Recommended: step-by-step instructions, examples, edge cases
- Under 500 lines (move detailed content to references)
Progressive Disclosure
- Metadata (~100 tokens): name + description loaded at startup
- Instructions (<5000 tokens recommended): SKILL.md body loaded on activation
- Resources (as needed): scripts/references/assets loaded on demand
File References
- Use relative paths from skill root
- Keep references one level deep (avoid deeply nested chains)
If spec violations found: Document them clearly in the review output with specific fixes.
Step 5: Analyze the Skill
Perform analysis in four areas, comparing against the reference skills you read from Anthropic's repository:
A. Length Analysis
Using the progressive disclosure guidelines from skill-creator, evaluate:
- Word count in
descriptionfield - Line/word count in SKILL.md body
- Number and size of reference files
- Duplication between SKILL.md and reference files
B. Intent Scope Analysis
Evaluate:
- All intents the skill serves
- Whether skill handles multiple distinct use cases
- Whether splitting would improve triggering accuracy
- Trade-offs: context efficiency vs. maintenance overhead
Questions to answer:
- Does this skill try to do too much?
- Are there distinct user intents that deserve separate skills?
C. Trigger Analysis (CRITICAL)
The description field is the primary triggering mechanism. Evaluate it for three types of triggers:
| Trigger Type | What to Check |
|---|---|
| User INTENT | Does it describe what the user wants to do? (e.g., "deploy", "create", "edit") |
| TECHNICAL context | Does it mention code patterns, file types, imports? (e.g., "base44.entities.*", ".jsonc files") |
| Project stack | Does it mention frameworks, tools, file structures? (e.g., "Vite", "Next.js", "base44/") |
Check:
- Does description cover both intent-based AND technical triggers?
- Is it specific enough to trigger correctly, but broad enough to not miss cases?
- Are there gaps where the skill might not trigger when it should?
- Does it clearly distinguish from similar skills?
Good trigger pattern example:
ACTIVATE when (1) INTENT - user wants to [action]; (2) TECHNICAL - code contains [patterns], uses [APIs]; (3) CONTEXT - project has [structure/files]
Step 6: Provide Recommendations
Summarize findings with actionable recommendations for:
- Spec Compliance: What needs to be fixed to follow the spec?
- Length: What should be trimmed or split?
- Intent Scope: Should it be split or combined?
- Triggers: How can the description be improved?
Output Format
## Skill Review: [Skill Name] ### Reference Skills Compared - [List the 3-5 Anthropic skills you read before this review] ### Summary [1-2 sentence overview] ### Validation Result - **Status**: [Pass/Fail] - **Details**: [Validation output or errors] ### Spec Compliance - Directory structure: [Pass/Fail - details] - Frontmatter fields: [Pass/Fail - details] - Body content: [Pass/Recommendations] - Progressive disclosure: [Pass/Recommendations] - File references: [Pass/Recommendations] - **Assessment**: [Compliant/Partially compliant/Non-compliant] - **Fixes Required**: [List of specific fixes if any] ### Length Analysis - Description: X words - SKILL.md body: X lines / X words - Reference files: X files - **Assessment**: [Pass/Needs attention] - **Recommendations**: [Specific suggestions] ### Intent Scope Analysis - Intents served: [List] - **Assessment**: [Focused/Broad/Too broad] - **Recommendations**: [Split suggestions if applicable] ### Trigger Analysis - Intent coverage: [Yes/Partial/No] - Technical coverage: [Yes/Partial/No] - Stack coverage: [Yes/Partial/No] - **Assessment**: [Strong/Adequate/Weak] - **Recommendations**: [Specific description improvements] ### Overall Recommendations 1. [Priority 1 action item - spec compliance fixes if any] 2. [Priority 2 action item] 3. [Priority 3 action item] 4. [Priority 4 action item]
