/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:

  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

• 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

name

description

4.2 Structure

4.3 Writing Style

4.4 Progressive Disclosure

references/

4.5 Resource Organization

4.6 Local Conventions (erk-specific)

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

scripts/

erk exec

src/erk/cli/commands/exec/scripts/

erk exec <script-name>

Rationale: Centralizing scripts in

erk exec

• 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