Skip to content
Apple Development Foundation
Esc
↑↓navigate↵open⌘Jpreview
On this page

Authoring skills

Maintain Codex skills in this repository with codex-skill-maintainer and verification scripts.

Use $codex-skill-maintainer when creating, reviewing, splitting, updating, or validating skills under .agents/skills/.
Path .agents/skills/codex-skill-maintainer/SKILL.md
Do not use for Ordinary product code in a consumer app; global install-only chores without skill content changes

Authoring rules (summary)

Full guide: Skill authoring guide.

  • One skill = one repeatable responsibility
  • Frontmatter: precise name and description (triggers and exclusions)
  • Keep operational instructions short; put durable references in references/
  • No business models, branding, secrets, user-specific paths, or hidden network behavior
  • Skills target the consumer workspace unless the skill is explicitly repository-scoped (codex-skill-maintainer)

Checklist when adding a skill

  1. Scaffold under .agents/skills/<name>/SKILL.md (template: Templates/NewSkill/SKILL.md.template if present)
  2. Add its canonical metadata to .agents/skills/manifest.json; name is the stable skill ID and must exactly match frontmatter
  3. Set router_included to control whether it appears in the master router
  4. Add at least two should_use and two should_not_use prompt cases to Evaluations/skill-routing.json, with complete routing, workspace, authorization, audit, verification, stop, and handoff expectations
  5. Regenerate and check the derived README, site inventory, and router catalog:
./Scripts/generate-skill-catalog.py
./Scripts/generate-skill-catalog.py --check
  1. Run:
./Scripts/validate-skill-evaluations.py
./Scripts/verify-skills.sh
./Scripts/test-install-skills.sh
./Scripts/install-skills.sh --dry-run
  1. Keep executable procedure in SKILL.md; the catalog generator never creates skill instructions

Installer safety

install-skills.sh never overwrites conflicting names or identical external links.

Flag / case Behavior
Default install Symlink installable skills into ${CODEX_HOME:-$HOME/.codex}/skills
--dry-run Print actions without writing
--uninstall Remove only symlinks whose destination still matches installer state (including broken links after a moved repo)
Conflict; leaving untouched Existing path not claimed — resolve manually

Details: Scripts · Troubleshooting.

Editing this Blume docs site

Blume renders frontmatter title as the page <h1>. You may keep a matching leading # Title in the MDX body for readable source and agent-facing .md / llms.txt mirrors.

Body # headings are not rendered in HTML — components.ts maps h1 to docs-components/SkipBodyH1.astro so authors are not forced to delete them. Prefer ## / ### for in-page sections.

AGENTS.md vs skills vs docs

Artifact Role
AGENTS.md Always-on rules for this repository
Skill SKILL.md Conditional, repeatable workflows
docs/ (this site) Agent playbook and onboarding
docs/skills/skill-authoring-guide.mdx Canonical live skill-maintenance guide
Evaluations/skill-routing.json Machine-readable prompt expectations and framework boundaries
docs/skills/skill-evaluation.mdx Behavioral evaluation scope, guarantees, and manual/model limits
archive/Documentation/ Historical package architecture notes

Was this page helpful?