agent-skills: Instructions file for Codex

AGENTS.md

Agent instructions for the agent-skills repository: a single plugin, quatico-skills, over a flat pool of 19 skills in skills/. This file is the hub; the rules that need detail live in the docs/rules/ spokes listed under Where to Find More. CLAUDE.md imports this file with @AGENTS.md, so every agent reads the same rules.

Critical Rules

1. NEVER edit version numbers by hand. The release pipeline owns metadata.version in every SKILL.md, version in .claude-plugin/plugin.json and .cursor-plugin/plugin.json, both marketplace.json files, and package.json. Hand-edits cause conflicts and drift.
2. Every change that touches a skill MUST add a changeset. Run pnpm changeset and fill in the summary, the root bump, and the bumps: block. Indent tuned-against: by exactly two spaces, or CI fails — see docs/rules/versioning.md.
3. Shell scripts MUST stay bash 3.2-compatible. macOS ships bash 3.2 and always will (bash 4 went GPLv3): no declare -A, no ${var^^}/${var,,}, no mapfile. Under set -u, expand possibly-empty arrays as ${arr[@]+"${arr[@]}"}. The bb-tests-macos CI job pins /bin/bash for cli/bb; every other script relies on this rule alone.
4. NEVER use YAML block scalars in SKILL.md frontmatter. No >-, >, |-, | — Cursor does not parse them. description is a single-line "quoted string"; metadata.version is 3-part semver.
5. Update README.md whenever skill membership changes. The skills table matches the contents of skills/, one row per skill, in alphabetical order by skill name. Add a new skill's row at its place in that order, not at the end. Nothing checks this.
6. Prefer gates over rules. A rule is prose an agent can rationalise around; a gate is a hard stop with objective verification (a hook, a CI check). Every rule on this page is currently prose — see docs/rules/skill-development.md § Gates Over Rules.

Essential Commands

pnpm changeset                                     # scaffold a changeset for a skill change
pnpm test                                          # skills parse
pnpm run validate                                  # skill frontmatter valid
(cd skills/working-with-bitbucket-api/tests && pnpm test)   # bb integration suite