agent-skills: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working with this repository.

Note: CLAUDE.md is a symlink to this file.

Prerequisites

This project uses pnpm for dependency management and task execution. Use the Node.js version declared in .node-version, then install dependencies with pnpm install.

Repository Structure

skills/
  {skill-name}/
    SKILL.md
    references/ (optional)

Commands

Run tasks with pnpm.

pnpm install                     # Install dependencies
pnpm test                        # Run tests

Before completing any task, run pnpm test to ensure CI passes.

Releases

This repository uses Release Please on main.

• Merge conventional commits using feat: and fix: prefixes so Release Please can open or update the release PR.
• Release Please opens one combined release PR that bumps the root version and the version of any skill whose files were touched. Unrelated skills are not bumped. Do not bump skill versions manually.
• When the PR is merged, GitHub Actions creates one GitHub release (tag v{version}) with all skill tarballs and index.json. Per-skill packages use skip-github-release: true — no separate GitHub release is created for them, but their metadata.version in SKILL.md and their CHANGELOG.md are committed as part of the release PR.

If you change shipped skill contents under skills/, make sure the change is represented with an appropriate conventional commit so it is included in the next release.

Creating a New Skill

Skills follow the Agent Skills Open Standard.

1. Create directory: mkdir -p skills/{skill-name}/references
2. Create SKILL.md following the format below
3. Add references/_sections.md defining sections
4. Add reference files: {prefix}-{reference-name}.md
5. Register the skill in release-please-config.json as a new package and seed its version in .release-please-manifest.json:

   // release-please-config.json — add under "packages":
   "skills/{skill-name}": {
     "release-type": "simple",
     "skip-github-release": true,
     "changelog-path": "skills/{skill-name}/CHANGELOG.md",
     "extra-files": [
       {
         "type": "generic",
         "path": "skills/{skill-name}/SKILL.md",
         "expressions": ["version: \"([0-9]+\\.[0-9]+\\.[0-9]+)\""]
       }
     ]
   }
   

   // .release-please-manifest.json — add:
   "skills/{skill-name}": "0.0.0"
   

6. Run pnpm test
7. Commit the new skill with a feat: prefix so Release Please bumps it from 0.0.0 to 0.1.0 on first release. Using fix: would produce 0.0.1 instead.