agentleFS
ivklgnivklgn/ai-kit/.claude/skills/review-and-release/SKILL.md

review-and-release

Skill12 starsChanged 2 months agoMITView on GitHub

Sync README with current agents/skills, validate plugin conventions, sync the Codex plugin directory (plugins/ai-kit), bump version, and commit. Use when the user says "/review-and-release" or wants to prepare a release after adding, removing, or changing agents or skills.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 9 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Read README.md and parse its three inline lists (backtick-separated names, alphabetical):

    line 33
  2. Distinctive:

    If zero differences across agents and skills, report "README is already in sync" and skip to Step 3.

    line 45
  3. Distinctive:

    Check all agent and skill files against these rules:

    line 49
  4. Distinctive:

    If any issues found, present them as a numbered list with file paths and stop.

    line 96
  5. Very specific:

    If Step 2 found differences, update README.md using the Edit tool: rebuild each affected inline list (## Agents, ## Skills, ## Commands) …

    line 100
  6. Distinctive:

    Use the Edit tool on each file.

    line 109
  7. Distinctive:

    Before committing, show a clear summary:

    line 131
  8. Distinctive:

    Only show sections with actual changes.

    line 156
  9. Distinctive:

    Commit with message format:

    line 166
  10. Distinctive:

    Do NOT use git add -A or git add ..

    line 175

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Review and Release

Synchronize README.md with the current set of agents and skills, validate files follow plugin conventions, sync the Codex plugin directory, bump the patch version in both plugin manifests, and create a release commit.

Step 1: Inventory Agents and Skills

Scan the filesystem to build the current state.

Agents:

ls agents/*.md

For each .md file, read the YAML frontmatter and extract name and description. Condense each description into a short README-style summary (under ~90 characters), matching the style of existing entries.

Skills:

ls skills/*/SKILL.md

For each SKILL.md, read the YAML frontmatter and extract name and description. Condense each description into a short README-style summary.

Store both inventories for use in subsequent steps.

Step 2: Diff Against README

Read README.md and parse its three inline lists (backtick-separated names, alphabetical):

  1. ## Agents — `name` · `name` · …
  2. ## Skills — same format
  3. ## Commands — `/ai-kit:name` · … (one entry per commands/*.md file)

Compare the filesystem inventory against README and classify:

  • Added — in filesystem but not in the README list
  • Removed — in the README list but not in filesystem
  • Unchanged — matches

If zero differences across agents and skills, report "README is already in sync" and skip to Step 3.

Step 3: Validate Plugin Conventions

Check all agent and skill files against these rules:

Agent files (agents/*.md)

  1. Frontmatter present — starts with --- and has closing ---
  2. Required fields — name, description, tools, model all present
  3. Name matches filename — name field equals filename without .md
  4. Model value — one of: haiku, sonnet, opus, inherit
  5. Description is non-empty
  6. Meaningful markdown body after frontmatter

Codex agent manifests (agents/*.toml)

Codex discovers subagents from .toml files, so every Claude Code agent must have a matching Codex manifest.

  1. Pairing — every agents/*.md has a sibling agents/*.toml (same basename), and every agents/*.toml has a sibling agents/*.md. Report any unpaired file.
  2. Valid TOML — parses without error.
  3. Required fields — name, description, sandbox_mode, developer_instructions all present and non-empty.
  4. Name matches — name equals the filename without .toml and equals the name in the paired .md.
  5. sandbox_mode value — one of: read-only, workspace-write. Use read-only when the paired .md tools contain no Write/Edit/Bash, otherwise workspace-write.
  6. developer_instructions matches the paired .md markdown body (the prompt after frontmatter).

Skill files (skills/*/SKILL.md)

  1. Frontmatter present — starts with --- and has closing ---
  2. Required fields — name and description present. Either model or disable-model-invocation: true must exist.
  3. Name matches directory — name field equals parent directory name
  4. Model value (if present) — one of: haiku, sonnet, opus
  5. Description is non-empty
  6. Meaningful markdown body after frontmatter

Plugin manifests

Validate both .claude-plugin/plugin.json and .codex-plugin/plugin.json:

  1. Valid JSON
  2. Required fields — name, description, version present
  3. Version matches semver X.Y.Z
  4. Both manifests have the same version value

Codex interface

Validate agents/openai.yaml:

  1. File exists
  2. interface.display_name is present and non-empty

If any issues found, present them as a numbered list with file paths and stop. Do not proceed until issues are fixed.

Step 4: Apply README Updates

If Step 2 found differences, update README.md using the Edit tool: rebuild each affected inline list (## Agents, ## Skills, ## Commands) sorted alphabetically, keeping the existing `name` · `name` format.

Step 5: Bump Version

Increment the patch version (e.g., 2.0.4 → 2.0.5) in both manifests so Claude Code and Codex stay aligned:

  • .claude-plugin/plugin.json
  • .codex-plugin/plugin.json

Use the Edit tool on each file.

Step 6: Sync Codex Plugin Directory

The Codex marketplace manifest (.agents/plugins/marketplace.json) points at plugins/ai-kit/, not the repo root — Codex users get ONLY what is inside that directory. It must mirror the root on every release:

rsync -a --delete skills/ plugins/ai-kit/skills/
rsync -a --delete agents/ plugins/ai-kit/agents/
cp .codex-plugin/plugin.json plugins/ai-kit/.codex-plugin/plugin.json

Verify the sync:

diff -rq skills plugins/ai-kit/skills && diff -rq agents plugins/ai-kit/agents

Both diffs must be empty. Commands are intentionally not synced — the Codex plugin manifest declares only skills and mcpServers; commands/ is Claude-only.

Step 7: Present Summary

Before committing, show a clear summary:

## Release Summary

**Version:** X.Y.Z → X.Y.Z+1

**README changes:**
- Added agents: ...
- Removed agents: ...
- Added skills: ...
- Removed skills: ...
- Added commands: ...

**Codex sync:** plugins/ai-kit updated (N files changed) / already in sync.

**Validation:** All agents and skills pass convention checks.

**Files to commit:**
- README.md
- .claude-plugin/plugin.json
- .codex-plugin/plugin.json
- plugins/ai-kit/** (if the sync changed anything)

Only show sections with actual changes.

Step 8: Commit

Stage and commit only the modified files:

git add README.md .claude-plugin/plugin.json .codex-plugin/plugin.json plugins/ai-kit

Commit with message format:

release: vX.Y.Z

- Updated README (added N agents, removed M agents, ...)
- Bumped Claude and Codex plugin versions to X.Y.Z

Do NOT use git add -A or git add .. After committing, run git status to confirm clean state and report the commit hash.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.