AI Agent Instructions

This repository is a community-shared, tool-agnostic skill library for AI coding agents.

CLAUDE.md is the tracked instruction source and AGENTS.md points to it by symlink; preserve that relationship.

Skill Authoring

Author each skill under skills/<skill-name>/:

skills/<skill-name>/
  SKILL.md
  references/   # optional
  assets/       # optional
  scripts/      # optional

• Use kebab-case for the folder and frontmatter name.
• Every SKILL.md requires YAML frontmatter with name and description; do not add author.
• Write actionable workflows for a specific problem, with references for details that do not belong in the main skill.
• Keep guidance compatible across agent tools unless the capability is inherently tool-specific.
• Keep instructions focused on non-obvious decisions, evidence, and domain constraints. Prefer adaptable workflows to fixed questionnaires, tool-call order, numerical confidence scores, or arbitrary skill-count limits.
• Reuse authorization already given and preserve explicit repository limits. Do not add routine approval pauses or broader-test offers without a material reason.
• When changing behavior guidance, align references, templates, adapter prompts, and plugin descriptions so they do not restore an obsolete rule.
• Distinguish editorial/static review from measured model behavior. Do not claim model performance gains without representative evaluations.

Neutral Skill Editing

When reviewing, creating, or updating a skill under skills/:

• Treat the target skill as an artifact; do not execute it merely because it is being edited.
• Do not load or follow sibling repository skills during the edit.
• Base changes on the user request, repository instructions, the target skill's intended behavior, relevant source files, and repository validators.
• Inspect another skill only when the user explicitly requests a comparison, without activating it.
• Repository scripts such as npm run sync and npm run validate remain authoritative.

Canonical Sources And Generated Outputs

• Author skill content only in skills/<skill-name>/.
• Use plugin-groups.json for marketplace ownership and each plugin's name, displayName, description, skill membership, and required multi-skill Codex defaultPrompts. Multi-skill prompts must route without assuming the first listed skill always applies.
• Assign every skill to exactly one plugin group; merge overlapping skills instead of duplicating membership.
• Use scripts/lib/plugin-shape.js as the sole definition of generated marketplace and manifest shapes.
• Treat .claude-plugin/marketplace.json, .agents/plugins/marketplace.json, generated README tables, and plugins/** as npm run sync outputs.
• Never edit plugins/<plugin-name>/** directly. Each generated package must contain its bundled skills plus .claude-plugin/plugin.json and .codex-plugin/plugin.json; the Codex manifest uses skills: "./skills/".
• Do not add marketplace or manifest keys until they have been validated against the oldest supported Claude Code. Claude rejects unknown keys, so preserve the shapes emitted by scripts/lib/plugin-shape.js.

Marketplace Updates

When adding, removing, regrouping, or scanning skills:

1. Scan directories under skills/ that contain SKILL.md and verify their name and description.
2. Update canonical skill files and plugin-groups.json; do not hand-edit generated outputs.
3. Run npm run sync to regenerate both marketplaces, plugin packages, manifests, and README skill tables.
4. Report added or removed skills and any missing or invalid metadata.

Generated Claude marketplace entries must point to ./plugins/<plugin-name> and use the version from package.json. Codex marketplace entries must also retain their generated installation, authentication, and category policy.

Verification And CI

After changing skills, plugins, or documentation:

1. Re-read CLAUDE.md, README.md, and affected skill documentation for synchronization needs.

2. Run the complete local suite:

   npm run sync
   npm run validate
   npm run test:agent-context
   claude plugin validate .

3. Report any command that could not run and why.

The pull-request workflow runs npm run validate. It verifies frontmatter, subagent consent gates, one-to-one plugin assignment, generated-file parity, version consistency, bundled-skill parity, and stale plugin removal. The main-branch sync workflow regenerates marketplace outputs after merge.

Every skill must run in the main conversation by default, warn that delegation can increase usage, require approval for the proposed agent count and scope, and require fresh approval before expanding that scope. Do not use context: fork or agent frontmatter.

Releasing

• Treat package.json version as the release source of truth. Bump it before npm run sync so marketplaces and every generated plugin manifest receive the new version.
• Never release skill changes without a version bump; explicit plugin versions prevent unchanged versions from reaching installed users.
• Every GitHub Release must contain a self-contained, user-facing changelog. Do not publish release notes that only list or refer readers to pull requests.
• Summarize each material change and its impact under clear sections such as Added, Changed, Fixed, Breaking Changes, and Upgrade Notes; omit empty sections.
• Pull-request links may follow a plain-language description for traceability, but must never replace it.
• Before publishing, compare the changelog with all merged changes since the previous tag and call out breaking changes, migration steps, compatibility requirements, and known limitations when applicable.

Commit And Pull Request Conventions

• Use one of these commit prefixes: feat, bug, chore, or refactor.
• When asked to open a pull request, create it with gh when available and follow the repository PR template or guidance.