/local:audit-skill

Audit a skill against the Anthropic skill-creator standards and provide structured recommendations for improvement.

Usage

# By skill name (looks in .claude/skills/)
/local:audit-skill dignified-python

# By file path
/local:audit-skill /path/to/skill/SKILL.md

Agent Instructions

Execute the skill audit workflow following these phases carefully.

Phase 1: Resolve Target Skill

Determine the skill to audit based on the argument provided: $ARGUMENTS

Resolution logic:

1. If the argument contains /, treat it as a file path
   • If it ends with SKILL.md, use the parent directory
   • Otherwise, assume it's the skill directory and look for SKILL.md inside
2. If the argument does not contain /, treat it as a skill name
   • Look for .claude/skills/<skill-name>/SKILL.md

Validation:

• Confirm the resolved path exists
• If not found, display an error message and stop:
  Copy

  Error: Skill not found at <resolved-path>
  

Phase 2: Fetch Standards from GitHub

Fetch the authoritative skill-creator standards from Anthropic's GitHub repository.

Step 2.1: Discover repository structure

Use WebFetch to browse the skill-creator directory and discover all available files:

1. https://github.com/anthropics/skills/tree/main/skills/skill-creator

   • Prompt: "List all files and directories in this skill-creator folder"

2. For each subdirectory found (e.g., references/, scripts/), fetch its contents:

   • https://github.com/anthropics/skills/tree/main/skills/skill-creator/<subdir>
   • Prompt: "List all files in this directory"

Step 2.2: Fetch discovered files

For each .md file discovered, fetch its contents using raw URLs:

• Base URL: https://raw.githubusercontent.com/anthropics/skills/main/skills/skill-creator/
• Example: For SKILL.md → https://raw.githubusercontent.com/anthropics/skills/main/skills/skill-creator/SKILL.md
• Example: For references/output-patterns.md → https://raw.githubusercontent.com/anthropics/skills/main/skills/skill-creator/references/output-patterns.md

Use prompts that extract the relevant guidance from each file.

Error handling:

• If directory listing fails, fall back to known files: SKILL.md, references/output-patterns.md, references/workflows.md
• If any file fetch fails, note it and continue with available standards
• At minimum, the main SKILL.md must be fetched successfully

Phase 3: Read Target Skill

3.1 Read the SKILL.md file:

• Use Read tool to get the full content of the target skill's SKILL.md

3.2 List directory contents:

• Use Bash to list the skill directory structure
• Identify what exists in scripts/, references/, assets/

3.3 Read bundled resources:

• Read files in references/ to understand what documentation is bundled
• Note scripts and assets without reading them fully (just note their presence)

Phase 4: Analyze Against Standards

Evaluate the skill against these criteria based on the fetched standards:

4.1 Frontmatter Quality

4.2 Structure

4.3 Writing Style

4.4 Progressive Disclosure

4.5 Resource Organization

4.6 Local Conventions (erk-specific)

These are project-specific conventions that differ from or extend Anthropic's standards:

Rationale: Centralizing scripts in erk exec provides:

• Single location for all executable scripts
• Consistent CLI interface (erk exec <name>)
• Easier testing and maintenance
• No need to discover/read scripts from skill directories

Phase 5: Generate Report

Present the audit findings in this structured format:

## Skill Audit: <skill-name>

### Summary

[1-2 sentence overview of skill health and main areas for improvement]

### Compliance Scorecard

| Criterion              | Status         | Notes               |
| ---------------------- | -------------- | ------------------- |
| Frontmatter            | PASS/WARN/FAIL | [Brief explanation] |
| Structure              | PASS/WARN/FAIL | [Brief explanation] |
| Writing Style          | PASS/WARN/FAIL | [Brief explanation] |
| Progressive Disclosure | PASS/WARN/FAIL | [Brief explanation] |
| Resource Organization  | PASS/WARN/FAIL | [Brief explanation] |
| Local Conventions      | PASS/WARN/FAIL | [Brief explanation] |

### Recommendations

[Numbered list of specific, actionable recommendations ordered by priority]

1. [Most critical issue and how to fix it]
2. [Second priority item]
   ...

### Detailed Findings

#### Frontmatter

[Expanded analysis]

#### Structure

[Expanded analysis]

#### Writing Style

[Specific examples of issues if any]

#### Progressive Disclosure

[Analysis of information organization]

#### Resource Organization

[Analysis of bundled resources]

#### Local Conventions

[Analysis of erk-specific patterns: no scripts/ directory, erk exec usage]

Status definitions:

• PASS: Fully compliant with standards
• WARN: Minor issues or room for improvement
• FAIL: Does not meet standards, needs correction

Key Principles

1. Be specific - Cite exact lines or sections when identifying issues
2. Be actionable - Every recommendation should be implementable
3. Prioritize - Order recommendations by impact
4. Be fair - Acknowledge what the skill does well
5. Reference standards - Connect findings back to the fetched standards