skill-management — Claude Code skill: creation and audits
skill-management — a Claude Code skill for creating, reviewing, and validating skills against the Agent Skills standard. It comes into play during structure checks, description edits, and manifest comparisons.
MIT 105 installs ★ 29 updated 2026-08-17
npx skills add oakoss/agent-skills --skill skill-management -a claude-codeWhat skill-management does
This skill guides the creation and review of skills that follow the Agent Skills standard. It covers YAML frontmatter, descriptions, directory layout, and ways to split material so details can be loaded progressively.
Its audit process has nine phases and assigns severity levels to findings. It also compares a skill's manifest with its implementation to catch mismatches. The guidance recommends keeping SKILL.md below 500 lines and moving details into references/.
The skill is not meant for application coding or general Markdown editing. In Claude Code, automatic invocation is disabled, so the task must be requested explicitly.
What it helps with
- scaffold a new skill that follows the Agent Skills standard
- rewrite a description to clarify when an agent should trigger the skill
- find frontmatter or directory-structure problems
- compare a skill's manifest with its files and commands
- audit a skill and classify the findings by severity
Example prompts for the agent
- Create a database migration review skill that follows the Agent Skills standard.
- Run the nine-phase audit on
skills/my-skill/. - Compare this skill's manifest with its directory and report mismatches.
How to install skill-management
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill skill-management -a claude-code2Manually: put the files in place
~/.claude/skills/skill-management/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/skill-management/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill skill-management -a codex2Manually: put the files in place
.agents/skills/skill-management/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill skill-management -a cursor2Manually: put the files in place
.cursor/skills/skill-management/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/skill-management2Manually: put the files in place
.github/skills/skill-management/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill skill-management -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/skill-managementManually: put the files in place
.devin/skills/skill-management/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill skill-management -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about skill-management
How do I install skill-management in Claude Code?
Run npx skills add oakoss/agent-skills --skill skill-management -a claude-code. The skill file will be at ~/.claude/skills/skill-management/SKILL.md.
What does skill-management do?
It guides skill creation and review against the Agent Skills standard, covering frontmatter, descriptions, directory layout, and manifest-to-implementation checks.
What does the skill audit check?
The audit has nine phases and classifies findings by severity. It also looks for differences between a skill's manifest and its implementation.
Source text
SKILL.md · MIT
--- name: skill-management description: | 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. Use when creating new skills, writing skill descriptions, auditing existing skills, detecting version drift, validating implementations match manifests, or debugging skill discovery issues. license: MIT metadata: author: oakoss version: '1.1' source: https://agentskills.io disable-model-invocation: true --- # 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](references/creating-skills.md) - [Auditing skills: 9-phase review, severity classification, fix decisions](references/auditing-skills.md) - [Validating skills: implementation vs manifest, drift detection, pass criteria](references/validation.md)
© oakoss · MIT · oakoss/agent-skills