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
Explore agent
- Multi-skill audit and cross-file consistency checks: Use
Task agent
- Skill architecture and directory structure planning: Use
Plan agent
If the find-skills skill 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
References
- Creating skills: structure, frontmatter, descriptions, progressive disclosure
- Auditing skills: 9-phase review, severity classification, fix decisions
- Validating skills: implementation vs manifest, drift detection, pass criteria
1---
2name: skill-management
3description: |
4 Creates, audits, and validates agent skills following the Agent Skills open standard. Covers YAML frontmatter, description writing, progressive disclosure, directory structure, 9-phase audits, severity classification, and manifest-implementation drift detection.
5
6 Use when creating new skills, writing skill descriptions, auditing existing skills, detecting version drift, validating implementations match manifests, or debugging skill discovery issues.
7license: MIT
8metadata:
9 author: oakoss
10 version: '1.1'
11 source: https://agentskills.io
12disable-model-invocation: true
13---
14
15# Skill Management
16
17## Overview
18
19Guides 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.
20
21**When to use:** Creating skills, improving descriptions for discoverability, restructuring skills for progressive disclosure, running quality audits, validating manifest-implementation alignment.
22
23**When NOT to use:** Writing application code, general markdown editing, project management unrelated to skill authoring.
24
25## Quick Reference
26
27| Task | Approach | Key Points |
28| ------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------ |
29| Skill directory | `skill-name/SKILL.md` + optional directories | Only `SKILL.md` is required; `scripts/`, `references/`, `assets/` are optional |
30| Frontmatter `name` | Lowercase, hyphens, 4-64 chars | Must match directory name, no leading/trailing `-`, no `--` |
31| Frontmatter `description` | 1-1024 chars with trigger phrases | Third-person voice, include "Use when" scenarios |
32| Progressive disclosure | Metadata -> SKILL.md -> references/scripts | Keep SKILL.md under 500 lines; move details to references |
33| Description structure | Para 1: what + features, Para 2: triggers | Active voice, name technologies, include error keywords |
34| Effective descriptions | 250-350 chars, specific, discoverable | "Build X" not "This skill helps you build X" |
35| Reference files | `references/topic.md` with frontmatter | Max 500 lines, self-contained, kebab-case filenames |
36| Quality audit | 9-phase systematic review | Standards, official docs, code accuracy, cross-file checks |
37| Severity levels | Critical / High / Medium / Low | Evidence-based classification with links |
38| Validation scoring | Average of accuracy, precondition, effect | Pass requires score >= 0.8 and zero high-severity issues |
39| Excluded files | `README.md`, `metadata.json`, `_*` files | Skills CLI strips these during installation |
40
41## Common Mistakes
42
43| Mistake | Correct Pattern |
44| -------------------------------------------------------------- | ------------------------------------------------------------------------------- |
45| Including `README.md` in skill directory | Skills CLI excludes `README.md` during installation; use only `SKILL.md` |
46| Writing vague descriptions without discovery keywords | Include specific technologies, 3-5 "Use when" scenarios, and 2-3 error messages |
47| Duplicating knowledge the agent already has | Focus on edge cases, platform differences, and gotchas the agent gets wrong |
48| Putting all content in SKILL.md without progressive disclosure | Keep SKILL.md under 500 lines; move code examples to `references/` |
49| Listing bundled files that do not exist on disk | Verify all cross-file references during review; orphan links break trust |
50| Using passive voice or first-person in descriptions | Third-person active voice: "Builds X" not "This skill helps you build X" |
51| Using `README.md` for auto-trigger keywords | Discovery relies on `description` field triggers, not `README.md` |
52| Referencing non-existent scripts or commands | Only reference scripts and commands that actually exist in the skill directory |
53
54## Delegation
55
56- **Skill discovery and keyword research**: Use `Explore` agent
57- **Multi-skill audit and cross-file consistency checks**: Use `Task` agent
58- **Skill architecture and directory structure planning**: Use `Plan` agent
59
60> If the `find-skills` skill is available, delegate skill discovery, installation, and CLI usage to it.
61> Otherwise, recommend: `pnpm dlx skills add oakoss/agent-skills -s find-skills -a claude-code -y`
62
63## References
64
65- [Creating skills: structure, frontmatter, descriptions, progressive disclosure](references/creating-skills.md)
66- [Auditing skills: 9-phase review, severity classification, fix decisions](references/auditing-skills.md)
67- [Validating skills: implementation vs manifest, drift detection, pass criteria](references/validation.md)
oakoss