Audit and improve existing agent skills against the agentskills.io specification and current best practices. Also audits CLAUDE.md, GEMINI.md, and AGENTS.md for bloat and configuration issues. Guides migration from client-specific folders to .agents/skills/ structure. Use when reviewing skill quality, checking specification compliance, optimizing descriptions for better triggering, identifying anti-patterns, upgrading skills to follow latest standards, or auditing agent instruction files. Activates on: "audit skills", "review my skill", "improve skill", "check skill quality", "skill audit", "fix skill description", "skill compliance", "check CLAUDE.md", "audit AGENTS.md", even if the user does not explicitly mention "audit" or "best practices". For creating new skills from scratch or running trigger evals, use skill-creator instead — this skill only audits and improves existing skills.
Audit and improve existing agent skills against the agentskills.io specification and current best practices. Also audits CLAUDE.md, GEMINI.md, and AGENTS.md for bloat and configuration issues. Guides migration from client-specific folders to .agents/skills/ structure. Use when reviewing skill quality, checking specification compliance, optimizing descriptions for better triggering, identifying anti-patterns, upgrading skills to follow latest standards, or auditing agent instruction files. Activates on: "audit skills", "review my skill", "improve skill", "check skill quality", "skill audit", "fix skill description", "skill compliance", "check CLAUDE.md", "audit AGENTS.md", even if the user does not explicitly mention "audit" or "best practices". For creating new skills from scratch or running trigger evals, use skill-creator instead — this skill only audits and improves existing skills.
Improving Skills — Audit & Optimization Guide
Structured workflow for auditing and improving agent skills, instruction files
(AGENTS.md, CLAUDE.md, GEMINI.md), and cross-platform compatibility.
Quick audit (5 minutes)
Read the skill's SKILL.md and list all files in the directory
Check frontmatter against the specification (Step 2 below, including
the skills-ref validate run)
Evaluate description quality (trigger coverage, third person, specificity)
Generate a prioritized improvement report (Step 5 template)
Full audit workflow
Step 1: Inventory the skill
List every file in the skill directory, then read SKILL.md in full. Read text
references as later steps call for them (large reference files and binary
assets don't need a full read to audit). Review scripts statically — never
execute an audited skill's scripts as part of the audit.
Record:
Total files and directories
SKILL.md line count
Number of reference files and scripts
Any unusual files or structures
Step 2: Specification compliance
If skills-ref
(the spec's reference implementation) is installed, run skills-ref validate <skill-path>
first to catch mechanical violations automatically. Focus manual review on description
quality and content.
Frontmatter validation
name field:
1–64 characters, lowercase a-z/0-9/hyphens
No leading/trailing/consecutive hyphens
Matches parent directory name exactly
description field:
1–1024 characters, non-empty
Third person, imperative framing
Describes what the skill does AND when to use it
Includes trigger keywords and non-obvious activation contexts
metadata — arbitrary key-value pairs (put version here, not at root)
No fields outside the spec list — skills-ref validate rejects unknown
fields with an error (its whitelist: name, description, license,
compatibility, metadata, allowed-tools). Client extensions such as
Claude Code's argument-hint, arguments, model, effort, context,
agent, hooks, paths, shell, when_to_use,
disable-model-invocation, user-invocable, disallowed-tools are
valid only for that client — report them per profile: "valid for
, Agent Skills spec non-compliant". A skill kept in a shared
.agents/skills/ collection should pass the spec profile
Claude products additionally reject names containing the reserved
words "claude" or "anthropic"
Structure validation
SKILL.md exists at skill root
SKILL.md body under 500 lines (~5,000 tokens)
File references use relative paths with forward slashes
All referenced files actually exist
No deeply nested reference chains (A → B → C)
Flat layout preferred — supporting files (e.g. anti-patterns.md)
live next to SKILL.md by default
references/ subdirectory used only when there are many files OR
a separate scripts/ folder already justifies subdirectory structure
(note: the spec lists references/ as a standard optional directory —
both layouts are spec-valid; flat is a readability preference, not a
compliance issue)
Step 3: Description quality assessment
The description is the routing key — it determines whether the skill triggers.
Trigger coverage
Specific keywords users would say
Non-obvious trigger contexts ("even if they don't mention X")
Concrete use cases, not abstract capabilities
Distinguishes this skill from adjacent/similar skills (when overlap
exists, name the sibling skill and the boundary explicitly)
Spot-check triggering: write 3–5 phrasings a user might realistically
say and confirm the description plausibly matches each (for rigorous
eval, hand off to skill-creator)
Writing quality
Third person only ("Processes files" not "I process files")
Imperative framing ("Use when...")
Focused on user intent, not implementation details
"Pushy" enough — agents tend to under-trigger
Common description problems
Problem
Example
Fix
Too vague
"Helps with documents"
"Extracts text from PDFs, fills forms. Use when..."
First person
"I can help you..."
"Processes files and generates..."
No trigger context
"PDF text extraction"
Add "Use when... even if they don't mention..."
Too broad
"Handles all data tasks"
Narrow to specific capabilities
Missing keywords
Only mentions "CSV"
Add "tabular data", "spreadsheet", "Excel", "TSV"
Scoring (1–5)
5: Specific, pushy, great keyword coverage, clear trigger contexts
4: Good but missing one or two trigger contexts
3: Adequate but could be more specific or pushy
2: Vague or missing trigger contexts
1: Too generic, wrong person, or misleading
Step 4: Content quality review
Conciseness
No explanations of things the agent already knows
No redundant general concepts (what PDFs are, how HTTP works)
Every piece of content justifies its token cost
Instructions in imperative form ("Run X", "Check Y")
No boilerplate code the agent can write from first principles — specify
the contract (what it must do) not a 30-line implementation
Audit agent instruction files (AGENTS.md, CLAUDE.md, GEMINI.md, CODEX.md, etc.)
for quality and consistency. These rules apply universally — every instruction file
follows the same principles regardless of platform.
Universal checklist
Exists and is not empty
Under ~100 lines (move specialized content to skills if longer)
Concise — every line must pass: "Would removing this cause mistakes?" If not, cut it
No decorative project header or adapter boilerplate at the top — rules start on line 1
Contains only rules agents can't infer from code
No content that should be a skill (workflows, checklists, multi-step procedures)
Gotchas section present (highest-value content)
No stale information (outdated commands, removed tools)
No rigid ALWAYS/NEVER without reasoning
If agent ignores a rule → file is probably too long, not the rule too weak
If agent asks questions answered in the file → phrasing may be ambiguous
Emphasis (IMPORTANT, YOU MUST) used sparingly for critical rules
Should include
Bash commands the agent can't guess
Code style rules that differ from defaults
Testing instructions and preferred test runners
Repo etiquette (branch naming, PR conventions)
Architecture decisions specific to the project
Developer environment quirks (required env vars)
Common gotchas and non-obvious behaviors
Should NOT include
Anything the agent can figure out by reading code
Standard language conventions the agent already knows
Detailed API documentation (link to docs instead)
Information that changes frequently
Long explanations or tutorials
File-by-file descriptions of the codebase
Self-evident practices like "write clean code"
The one-line test
For every line: "Would removing this cause the agent to make mistakes?" If not, cut it.
If the agent ignores a rule, the file is probably too long — not the rule too weak.
If the agent asks questions answered in the file, the phrasing is ambiguous.
Platform-specific adapters
AGENTS.md is the canonical, vendor-neutral instruction file
Adapters (CLAUDE.md, GEMINI.md, etc.) import shared instructions
via @-imports (e.g., @AGENTS.md) and add only platform-specific rules
No duplicated content across files — shared rules belong in AGENTS.md
Skills vs. instruction files
Instruction files load every session. Skills load on demand.
Content only relevant sometimes → skill (not instruction file)
If instruction file grows past ~100 lines → migrate workflows to skills
Cross-agent compatibility review
Platform discovery paths
The agentskills.io spec is client-agnostic — discovery paths are not part
of the spec. The locations below are each client's own convention.
Platform
User scope
Repo scope
Claude Code
~/.claude/skills/
.claude/skills/
OpenAI Codex
~/.agents/skills/
.agents/skills/ (scanned from cwd up to repo root)
Gemini CLI
~/.gemini/skills/ or ~/.agents/skills/ (alias wins)
.gemini/skills/ or .agents/skills/ (alias wins)
Share one skill set across all three by keeping files in ~/.agents/skills/ — Codex and Gemini pick it up natively — and junction (Windows) or symlink (macOS/Linux) ~/.claude/skills/ → ~/.agents/skills/ so Claude Code sees the same files under its own path. A working pattern: a small Python or PowerShell script that calls mklink /J (Windows) or os.symlink (POSIX) per skill directory; run once per machine setup so new skills under ~/.agents/skills/ are picked up by Claude Code through the junction.
Compatibility checklist
Forward slashes in all paths
Prerequisites stated explicitly
MCP tools use fully qualified names (Server:tool_name)
Dependency versions pinned
No interactive prompts in scripts
No platform-specific assumptions without compatibility field
Description rewriting
The description is the routing key — agents load only name + description at startup, so fix this first when a skill under-triggers (writing criteria in Step 3).
For full trigger evaluation (build a query set, grade with a validation split, iterate), use the skill-creator skill — that's where the benchmark tooling lives. This skill stops at identifying that a rewrite is needed.
Gotchas
description has a hard cap of 1024 characters — count characters before saving when writing long descriptions
name must match the directory name exactly — uppercase letters, underscores, or spaces break discovery
In batch audits, ~/.agents/skills/ is the user-scope default, .agents/skills/ is repo-scope — don't mix them up
Symlinks from .claude/skills/ → .agents/skills/ can cause duplicate discovery reports
Instruction file audit (AGENTS.md/CLAUDE.md) is a separate workflow from skill audit — don't combine them into the same report
allowed-tools is marked Experimental in the spec — don't add routinely, support varies across platforms
version is not a root-level frontmatter field — to version a skill, place it under metadata: { version: "1.0" }. Free-form root-level keys may be rejected by spec validators
Client-specific frontmatter (Claude Code's argument-hint, model, context, etc.) is not in the agentskills.io spec, and skills-ref validate reports unknown fields as errors — a skill using them may work in its client but is spec non-compliant. Drop them from skills kept in a shared .agents/skills/ collection
Root skills/ breaks discovery: no client scans a bare root skills/ directory. Codex scans .agents/skills/ (repo scope, cwd up to repo root); Gemini CLI scans .gemini/skills/ and the .agents/skills/ alias; Claude Code scans only .claude/skills/ (project) and ~/.claude/skills/ (user) — it does not read .agents/skills/ natively, so sharing one collection with Claude Code requires a symlink/junction from .claude/skills/. Root skills/ only works as AGENTS.md @include context, not as a discoverable/invokable skill. To auto-load a skill every session, add @.agents/skills/<name>/SKILL.md to AGENTS.md.
Verify behavioral claims against official docs/source before editing — truncation behavior, deprecation status, experimental flags, and token budgets must come from specs, READMEs, or source code, not from inference or plausibility. When docs are silent on a behavior, preserve the original wording rather than invent it. A plausible-sounding claim that rots later is worse than no claim.
The goal is reliable triggering, specification compliance, and clear value without wasting context tokens.
