Skill Audit

Skill Audit

Use this skill to audit existing skills, turn workflow knowledge into useful agent skills, and review skill libraries at the strategy level. It complements skill-creator: use this skill to decide what a skill should be, how it should fit a library, and what needs improvement; use skill-creator when the user wants the concrete SKILL.md implementation and eval loop.

This workflow is based on Anthropic's June 3, 2026 blog post, "Lessons from building Claude Code: How we use skills": https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills

Core Principle

A good skill is not "some markdown about a topic." It is a compact extension point that gives the agent non-obvious domain knowledge, reusable files, deterministic helpers, setup rules, verification habits, and guardrails at the moment they matter.

Workflow

1. Decide Whether This Should Be A Skill

Create or improve a skill only when at least one of these is true:

• The workflow repeats often enough that users should not re-explain it.
• The agent regularly makes the same domain-specific mistake.
• The work needs local scripts, templates, examples, assets, hooks, or setup.
• The output must follow a stable structure or verification path.
• The knowledge is team-specific, product-specific, infrastructure-specific, or otherwise not inferable from general model knowledge.

Do not make a skill when the content only restates obvious coding behavior, generic best practices, or one-off instructions.

2. Classify The Skill

Read references/skill-taxonomy.md and classify the candidate into exactly one primary category. If it appears to span several categories, tighten the scope or split it.

Report:

• Primary category
• Secondary category, if truly needed
• Why this category is the cleanest fit
• What would make the skill too broad

3. Draft A Skill Brief

Use assets/skill-brief-template.md for the output. Fill it with:

• Trigger description written for the model, not as a human-facing summary
• High-signal knowledge the model would not otherwise know
• Gotchas and failure modes
• Autonomy boundaries: what the skill may do directly, and what must be escalated before acting
• Evidence-backed pushback rules: when the agent should challenge the proposed path and what evidence it must cite
• Feedback loop: where repeated corrections, false-success signals, or manual recovery steps should be promoted
• Progressive disclosure map: SKILL.md vs references vs scripts vs assets
• Setup requirements or config questions
• Verification strategy
• Reliable Skill Contract coverage for high-value workflow skills
• Distribution path
• Measurement plan

4. Design Progressive Disclosure

Keep SKILL.md focused on activation, decisions, and the main workflow. Move details into support files:

• references/ for tables, API conventions, taxonomy, playbooks, and long docs
• scripts/ for deterministic actions or repetitive checks
• assets/ for templates, report formats, starter files, or examples
• agents/ for specialized subagent prompts when the repo supports them
• evals/ for realistic prompts and objective assertions

Tell the agent exactly when to read each support file.

5. Add Operational Design

Read references/writing-and-operations.md when deciding:

• Whether a setup step or config file is needed
• Whether the skill should remember past runs
• Whether scripts or hooks would improve reliability
• Whether the skill belongs in a repo, a shared plugin, or a marketplace
• What usage signals indicate undertriggering, overtriggering, or decay