Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill skill-management -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/skill-management/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/skill-management/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set106

The whole set →
turborepo This Claude Code skill helps configure Turborepo in JavaScript and TypeScript monorepos. Use it to set up task pipelines, caching, package filters, and CI workflows. CX Codex +1 108installs realtime-sync realtime-sync guides agents through designing low-latency sync using WebTransport, CRDT conflict resolution, and batched AI token streaming. CX Codex +1 108installs plan-first-development The plan-first-development Claude Code skill structures project planning and tracks progress across sessions. It activates for new projects, major features, and work split into phases. CX Codex +1 107installs tracer-bullets The tracer-bullets Claude Code skill splits multi-layer work into end-to-end slices. Each slice is checked before work moves on. CX Codex +1 107installs expert-instruction The expert-instruction Claude Code skill helps design system instructions for AI agents. It covers agent roles, behavioral limits, response formats, and tool-use guidance. CX Codex +1 106installs codebase-packager The codebase-packager Claude Code skill prepares large repositories for AI coding tasks. It builds digests, packs source context, and traces connections across files. CX Codex +1 105installs meta-agent-creator The meta-agent-creator Claude Code skill helps define custom subagents and configure their settings. Use it to shape task delegation and control which tools an agent can access. CX Codex +1 104installs localization-engineer localization-engineer is a Claude Code skill that guides internationalization and localization architecture. It structures ICU messages, CLDR plurals, RTL layouts, and multilingual SEO. CX Codex +1 103installs

Project sponsors

Companies that keep this analytics open