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
• Progressive disclosure map: SKILL.md vs references vs scripts vs assets
• Setup requirements or config questions
• Verification strategy
• 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

6. Hand Off To Implementation

When the user wants the skill built, pass the brief into skill-creator and ask it to implement the files, generate realistic test prompts, and run validation.

If editing an existing skill, include the exact file paths and the smallest content changes needed. Do not rewrite unrelated skill behavior.

Output Format

For advisory requests, answer with:

1. Decision: create, improve, split, merge, or do not create 2. Category: one primary taxonomy category 3. Skill brief: filled from the template 4. Implementation notes: files to create/edit and validation commands 5. Risks: overbreadth, obviousness, missing setup, missing verification, or weak trigger description

For repository work, actually create or update the files, then run the repo's skill validation command.

Gotchas

• Do not make a knowledge dump. Convert article or team knowledge into decisions,

checklists, templates, and verification.

• Do not put all details in SKILL.md. Long reference material belongs in support

files.

• Do not write a description as a marketing summary. It must name concrete user

phrases and contexts that should trigger the skill.

• Do not railroad the agent with brittle instructions. Provide defaults,

decision criteria, and escape hatches.

• Do not ship a skill without at least a lightweight way to tell if it worked:

validation commands, example prompts, expected artifacts, or usage metrics.

Skill Brief

Decision

• Create / improve / split / merge / do not create:
• Reason:

Candidate Skill

• Proposed name:
• Primary category:
• Secondary category:
• Target users:
• Trigger contexts:

Description Draft

Write the frontmatter description here. Include concrete phrases and contexts that should trigger the skill.

High-Signal Knowledge

• TBD

Gotchas

• TBD

Progressive Disclosure Map

Setup

• Required tools:
• Required config:
• Missing information to ask user:
• Secrets handling:

Verification

• Commands:
• Example prompts:
• Expected artifacts:
• Failure signals:

Distribution

• Repo-local / shared plugin / marketplace / experimental:
• Promotion criteria:

Measurement

• Usage signals:
• Undertriggering signals:
• Overtriggering signals:
• Maintenance owner:

Skill Taxonomy

Use this taxonomy to place a candidate skill into one primary category. A good skill usually fits cleanly into one category. If it does not, narrow the scope or split the skill.

1. Library And API Reference

Use for libraries, CLIs, SDKs, internal APIs, or platform wrappers that agents often misuse.

Include:

• Correct invocation patterns
• Edge cases and footguns
• Required imports, auth, environment variables, and version notes
• Small reference snippets

Avoid:

• Repeating public docs without repo-specific gotchas
• Mixing unrelated libraries into one broad reference skill

2. Product Verification

Use for proving product behavior works, especially user flows, UI flows, CLI flows, and state transitions.

Include:

• Exact verification steps
• Programmatic assertions
• Test accounts, fixtures, or safe data
• Screenshots, traces, logs, or videos when useful

Avoid:

• Only saying "test it"
• Leaving verification subjective when the state can be asserted

3. Data Fetching And Analysis

Use for querying data stores, dashboards, event streams, logs, or monitoring systems.

Include:

• Canonical tables, event names, IDs, and joins
• Credential and environment setup
• Common query patterns
• Statistical or data quality checks

Avoid:

• Letting the agent invent fields, dashboards, or joins
• Hiding missing data behind fallback narratives

4. Business Process And Team Automation

Use for repeatable team workflows such as standups, ticket creation, release notes, weekly recaps, or queue processing.

Include:

• Input sources
• Output schema
• Ordering and escalation rules
• Memory or logs for previous runs when deltas matter

Avoid:

• Encoding one person's temporary preference as a global workflow
• Automating before the manual workflow is stable

5. Code Scaffolding And Templates

Use for creating repeatable code structures, services, migrations, app shells, or framework-specific boilerplate.

Include:

• File tree
• Templates
• Naming rules
• Required wiring and validation commands

Avoid:

• Scaffolding code that is not wired into startup, routing, or tests
• Treating natural-language requirements as if pure templates are enough

6. Code Quality And Review

Use for review, linting, style, testing practices, adversarial critique, or quality gates.

Include:

• Prioritized findings criteria
• Deterministic checks where possible
• Review templates
• Rules that target known agent failure modes

Avoid:

• Broad "make it better" guidance
• Weakening tests or replacing root-cause analysis with cosmetic cleanup

7. CI/CD And Deployment

Use for building, releasing, deploying, rollback, PR babysitting, or environment-specific delivery workflows.

Include:

• Exact commands and environments
• Smoke tests
• Rollback criteria
• CI status handling and flaky-test policy

Avoid:

• Destructive deployment steps without guardrails
• Claiming success without fresh command output

8. Runbooks

Use for symptom-driven investigations such as incidents, alerts, error signatures, failed jobs, or support escalations.

Include:

• Symptom-to-tool routing
• Query patterns
• Structured report format
• Stop conditions and escalation path

Avoid:

• A vague checklist that does not narrow the search space
• Letting the agent stop after the first plausible explanation

9. Infrastructure Operations

Use for routine operational work with resources, networking, secrets, accounts, quotas, storage, or cost investigations.

Include:

• Safety checks
• Dry-run behavior when possible
• Confirmation points for destructive operations
• Audit trail and rollback notes

Avoid:

• Hiding destructive actions inside convenience commands
• Combining unrelated infrastructure tasks into one large skill

Writing And Operations Playbook

Use this reference after choosing a taxonomy category.

High-Signal Content

Prefer content that changes the agent's behavior:

• Domain gotchas
• Non-obvious invariants
• Local file paths and tool names
• Validation commands
• Known bad patterns
• Setup and configuration requirements
• Output formats that must be preserved

Avoid content the model already knows, such as generic coding advice, common framework summaries, or broad "be careful" statements without concrete failure modes.

Gotchas

Every skill should have at least one gotcha if it exists because the agent has made mistakes before. Good gotchas are specific:

• Which field name is misleading
• Which API returns success before work is complete
• Which environment behaves differently
• Which file must be updated together with another file
• Which fallback is unsafe

Description Design

The description field is a trigger contract. Write it for model discovery.

Include:

• What the skill does
• Concrete user phrases and task contexts
• File types, tools, products, or domains that should trigger it
• Strong signals for when to use it even if the user does not say "skill"

Avoid:

• Human-facing marketing language
• A vague summary that could apply to many skills
• Trigger details buried only in the body

Setup

If the skill depends on user-specific context, design setup explicitly:

• Store non-secret config in a local config file when appropriate
• Ask only for missing information that cannot be inferred
• Keep secrets in env vars or the user's secret manager
• Document default behavior when config is missing

Memory

Use memory only when history changes the next run:

• Append-only logs for recurring posts, recaps, queues, or reviews
• JSON state for processed IDs or last-run timestamps
• Stable data directories when the runtime provides them

Do not use memory to hide uncertainty or replace source-of-truth systems.

Scripts

Add scripts when deterministic code is more reliable than instructions:

• Fetching or transforming structured data
• Validating generated files
• Creating templates or scaffolds
• Running repeatable checks

Keep scripts small, documented by usage examples, and covered by smoke tests.

Hooks

Use on-demand hooks for temporary guardrails that should apply only while a skill is active:

• Blocking destructive shell commands during production operations
• Restricting edits to an allowed directory during targeted debugging
• Logging usage or verification evidence during eval runs

Avoid always-on hooks for narrow workflows because they create noise outside the skill's task.

Distribution

Choose distribution by audience:

• Repo-local skill: best when knowledge is tied to one codebase or small team
• Shared plugin or marketplace: best when many teams can reuse it and choose

whether to install it

• Sandbox folder or experimental branch: best before the skill has traction

Promote a skill after real use shows that it triggers correctly and improves outcomes.

Measurement

Track lightweight signals:

• Usage count
• Tasks where the skill should have triggered but did not
• Tasks where it triggered but was not useful
• Repeated gotchas added after failures
• Verification pass rate
• Time saved or reduction in review comments

Use these signals to decide whether to improve the description, split the skill, add support files, or retire it.