manage-skills
Create, update, restructure, rename, merge, or retire portable agent skills. Use when changing a skill's activation contract, SKILL.md, reference cards, scripts, assets, evals, discovery metadata, or
SKILL.mdskills/workflow/manage-skills/SKILL.md
GitHubManage Skills
Create and modify skills entirely from package-relative resources. The bundled authoring contract is the operational authority when host documentation is absent; host rules are stricter overlays only.
When to Apply
Use this skill when:
- Creating or changing a portable skill package
- Renaming, merging, replacing, retiring, validating, or synchronizing skill content
How to Use
Resolve these paths relative to this SKILL.md, never the current working directory:
references/authoring-contract.md
assets/skill-template.md
assets/reference-card-template.md
scripts/init_skill.py
scripts/generate_openai_yaml.py
scripts/quick_validate.py
Read references/authoring-contract.md before any create or update. It owns detailed authoring
decisions; this file owns only execution order and resource navigation.
Workflow
- Read applicable host instructions and inventory the full existing package or target inventory.
- Define capability, activation, boundaries, inputs, outputs, and concrete requests; select create or update based on equivalence evidence.
- For create, explicitly decide optional frontmatter, categories, references, and host metadata,
then run
scripts/init_skill.py --helpand pass only applicable flags. Never initialize an existing path. - For update, classify behavior as preserved, moved, superseded, or intentionally removed. Change narrow owners and preserve unrelated content.
- Add cards, scripts, assets, README, metadata, and evals only under their contract boundaries.
- Run the bundled validator and portable scripts/tests in temporary directories. Complete the contract's mandatory manual review.
- Run applicable host formatting, linting, validators, evals, links, registry, diff, and repository checks. Synchronize host copies only after the source passes.
Optional OpenAI metadata is requested explicitly during initialization:
python <skill-root>/scripts/init_skill.py <name> \
--path <parent> \
--description <activation-contract> \
--title <display-title> \
--overview <purpose-scope-organization> \
--trigger <first-trigger> \
--trigger <second-trigger> \
--openai-metadata \
--display-name <display-name> \
--short-description <25-to-64-character-summary> \
--default-prompt <prompt-containing-$name>
Omit the four metadata flags when the host does not require agents/openai.yaml. Use
--categories, --references, --license, --allowed-tools, --author, --version, and
--compatibility only after explicitly deciding they apply.
Output Contract
Return:
status:created,updated,blocked, orfailedexecutive_summary: outcome and key design choiceartifacts: exact created, changed, removed, and synchronized pathscommands: exact validations and resultsmanual_review: semantic rules reviewed manually and unresolved findingsnext_recommended: most useful next action, ornonerisks: unresolved risks and omitted validation, ornoneskill_resolution: create/update choice, resolved name/path, and equivalence evidence