skill-management
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.
How do I install this agent skill?
npx skills add https://github.com/oakoss/agent-skills --skill skill-managementIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a comprehensive framework and set of guidelines for managing AI agent skills, including their creation, auditing, and validation according to the Agent Skills open standard. No malicious patterns, obfuscation, or unauthorized data access were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
4/4 files flagged
What does this agent skill do?
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
References
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/oakoss/agent-skills/skill-management">View skill-management on skillZs</a>