Skill Management
Overview
Guides creation, auditing, and validation of agent skills conforming to the Agent Skills open standard at https://agentskills.io. Covers the full lifecycle from scaffolding a new skill through production-quality review.
When to use: Creating skills, improving descriptions for discoverability, restructuring skills for progressive disclosure, running quality audits, validating manifest-implementation alignment.
When NOT to use: Writing application code, general markdown editing, project management unrelated to skill authoring.
Quick Reference
| Task | Approach | Key Points |
|---|---|---|
| Skill directory | skill-name/SKILL.md + optional directories | Only SKILL.md is required; scripts/, references/, assets/ are optional |
Frontmatter name | Lowercase, hyphens, 4-64 chars | Must match directory name, no leading/trailing -, no -- |
Frontmatter description | 1-1024 chars with trigger phrases | Third-person voice, include "Use when" scenarios |
| Progressive disclosure | Metadata -> SKILL.md -> references/scripts | Keep SKILL.md under 500 lines; move details to references |
| Description structure | Para 1: what + features, Para 2: triggers | Active voice, name technologies, include error keywords |
| Effective descriptions | 250-350 chars, specific, discoverable | "Build X" not "This skill helps you build X" |
| Reference files | references/topic.md with frontmatter | Max 500 lines, self-contained, kebab-case filenames |
| Quality audit | 9-phase systematic review | Standards, official docs, code accuracy, cross-file checks |
| Severity levels | Critical / High / Medium / Low | Evidence-based classification with links |
| Validation scoring | Average of accuracy, precondition, effect | Pass requires score >= 0.8 and zero high-severity issues |
| Excluded files | README.md, metadata.json, _* files | Skills CLI strips these during installation |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
Including README.md in skill directory | Skills CLI excludes README.md during installation; use only SKILL.md |
| Writing vague descriptions without discovery keywords | Include specific technologies, 3-5 "Use when" scenarios, and 2-3 error messages |
| Duplicating knowledge the agent already has | Focus on edge cases, platform differences, and gotchas the agent gets wrong |
| Putting all content in SKILL.md without progressive disclosure | Keep SKILL.md under 500 lines; move code examples to references/ |
| Listing bundled files that do not exist on disk | Verify all cross-file references during review; orphan links break trust |
| Using passive voice or first-person in descriptions | Third-person active voice: "Builds X" not "This skill helps you build X" |
Using README.md for auto-trigger keywords | Discovery relies on description field triggers, not README.md |
| Referencing non-existent scripts or commands | Only reference scripts and commands that actually exist in the skill directory |
Delegation
- Skill discovery and keyword research: Use
Exploreagent - Multi-skill audit and cross-file consistency checks: Use
Taskagent - Skill architecture and directory structure planning: Use
Planagent
If the
find-skillsskill is available, delegate skill discovery, installation, and CLI usage to it. Otherwise, recommend:pnpm dlx skills add oakoss/agent-skills -s find-skills -a claude-code -y