Skill quality audit

Audit whether a skill's instructions will actually make an agent perform better. A skill can be perfectly conformant and still worthless.

Run spec validation first. Use the skill-validation skill. Format errors are cheap to find and cheap to fix, and finding them first keeps this audit focused on judgment calls. Do not repeat its findings here.

The audit

Read the whole skill — SKILL.md and every bundled file — then work through the six questions below. Each one has a specific failure it detects.

1. Does it add anything the agent lacks?

The core test, from agentskills.io: for each section, ask would the agent get this wrong without this instruction?

Cut content that explains what a PDF is, how HTTP works, or what a migration does. Keep project-specific conventions, domain procedures the agent would not infer, non-obvious edge cases, and the particular tools or APIs to use.

If the agent already handles the whole task well without the skill, say so plainly. A skill that adds nothing costs startup context for every session and should be deleted, not improved. This is an uncomfortable finding to deliver and the most valuable one in this list.

2. Is it grounded in real expertise, or generated from generic knowledge?

The tell is vague imperatives: "handle errors appropriately", "follow best practices for authentication", "ensure proper validation". These are what an LLM writes when it was asked to produce a skill without domain context.

Grounded skills name things: actual API quirks, actual table names, actual failure modes, actual commands. If a section could appear verbatim in any skill about any topic, it is filler.

Reporting this well matters. Do not simply flag it — ask where the expertise lives. Incident reports, runbooks, code review comments, and the commit history of past fixes are the source material that turns a generic section into a specific one.

3. Is control calibrated to fragility?

Match specificity to how much the task tolerates variation:

Task shape	Instruction style
Multiple valid approaches, variation is fine	Describe what to achieve and why; let the agent choose
Fragile sequence, consistency required, destructive	Prescribe the exact commands and forbid deviation

Both failure directions are real. Over-prescribing a flexible task produces brittle skills that break when reality differs slightly. Under-prescribing a fragile one produces skills that fail intermittently and unreproducibly.

Most skills need both, calibrated per section — flag the sections, not the skill as a whole.

4. Does it give defaults, or a menu?

"You can use pypdf, pdfplumber, PyMuPDF, or pdf2image" makes the agent choose, which costs a decision and produces inconsistent runs. "Use pdfplumber. For scanned PDFs requiring OCR, use pdf2image with pytesseract instead" is a default with an escape hatch.

Flag every place the skill presents options as equals without naming a default.

5. Is it a procedure or an answer?

A skill should teach how to approach a class of problems, not what to produce for one instance. "Join orders to customers on customer_id and filter region = 'EMEA'" only helps for that exact question. "Read the schema from references/<schema>.yaml, join on the _id foreign key convention, apply the user's filters as WHERE clauses" generalizes.

Output templates, hard constraints ("never output PII") and tool-specific commands are legitimately specific — the approach is what must generalize.

6. Is it a coherent unit?

Scope a skill like a function.

• Too narrow — several skills must load for one task, risking overhead and conflicting instructions.
• Too broad — the description cannot trigger precisely, so it fires on the wrong tasks or not at all. "Query a database and format results" is one unit; adding database administration is two.

If the skill has more than one distinct trigger condition with no shared procedure, propose the split explicitly, with the name and description for each half.

Patterns worth adding

When a skill is missing one of these and would benefit, recommend it concretely rather than in the abstract. The full pattern list with worked examples is in references/instruction-patterns.md — read it before recommending a pattern, so the recommendation includes what the section should actually contain.

The highest-value one is almost always a gotchas section: environment facts that defy reasonable assumptions. Soft-deleted rows that need WHERE deleted_at IS NULL. An ID that is user_id in one system and accountId in another. A /health endpoint that returns 200 while the database is down. These are the corrections a user makes over and over, and they belong in SKILL.md where the agent reads them before hitting the situation.

Context economy

Everything in an activated skill competes with the conversation for attention. The mechanics of measuring and budgeting this — where the limits come from, how to split a skill, how to write a load condition that actually works — are in references/context-economy.md. Read it when a skill is over the size recommendations, when you are proposing a split, or when the user asks why length matters.

Report

Order findings by what would improve the skill most, not by section order. For each: what is wrong, why it costs the agent something, and the concrete rewrite. A finding without a specific replacement is an opinion.

Separate cut from fix. Deletion is the most common correct recommendation and the one authors resist most, so make the case explicitly — name the tokens saved and what the agent already knows.

State what is good, briefly and specifically. It tells the author which instincts to keep.

Gotchas

• Do not rewrite the skill unasked. The audit is the deliverable. Offer the rewrite; make it when the user says yes.
• Do not confuse length with bloat. A 400-line skill dense with project-specific gotchas is fine. A 100-line skill of generic advice is not. Judge content, not line count — the size warnings from skill-validation are a prompt to look, not a verdict.
• You cannot audit output quality by reading. Whether the skill produces good results needs test cases and grading — see https://agentskills.io/skill-creation/evaluating-skills. Say so rather than implying this review covers it.
• Execution traces beat final outputs. If the user has run the skill, ask for the traces. An agent that tried three approaches before finding one reveals a vague instruction; an agent that followed an irrelevant instruction reveals a scoping error. Neither is visible in the final output.