improving-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)

1. Read the skill's SKILL.md and list all files in the directory
2. Check frontmatter against the specification (Step 2 below, including the skills-ref validate run)
3. Evaluate description quality (trigger coverage, third person, specificity)
4. Scan content for anti-patterns (see anti-patterns.md)
5. 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
• Optional spec fields (if present):
  • compatibility — 1–500 chars, platform/environment requirements
  • allowed-tools — space-separated pre-approved tools (Experimental)
  • license — reasonable format
  • 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"