Immutable. This exact content is served forever at /api/v1/blob/65ded3388b5edc93.
# Repository Guidelines
This repository is a catalog of **Agent Skills** (per the AgentSkills specification) plus supporting tooling for reusable Codex workflows. Contributions should keep skills spec-compliant, self-contained, easy to install, and documented in `docs/` when they change public behavior.
## Project Structure & Module Organization
- `skills/<skill-name>/SKILL.md`: canonical entrypoint (required) with YAML frontmatter + instructions.
- `skills/<skill-name>/references/`: optional long-form docs to load on demand.
- `skills/<skill-name>/scripts/`: optional helper scripts (prefer deterministic tooling here).
- `skills/<skill-name>/assets/` / `templates/`: optional reusable artifacts.
- `skills/<skill-name>/agents/`: optional agent-runtime metadata (for example OpenAI YAML).
- `skills/dist/`: prebuilt `.skill` bundles (ZIP archives) for selected skills.
- `archive/skills/<skill-name>/`: retired skill source history with required `archive.json`; archived skills are not active/installable.
- `plugins/<plugin-name>/.codex-plugin/plugin.json`: durable source for local Codex plugin bundles that package related skills.
- `plugins/<plugin-name>/skills/<skill-name>/SKILL.md`: plugin-scoped skills; keep names hyphen-case and avoid duplicate standalone skill ownership unless intentional.
- `crates/codex-dev-core/`: shared Rust contracts and read models for local task capsules.
- `crates/codex-dev/`: Rust CLI for local task capsules, policy gates, and development evidence.
- `crates/codex-dev-tui/`: optional Ratatui workbench for local `codex-dev` task capsules.
- `crates/codex-research/`: Rust CLI for evidence-first research helpers.
- `crates/bun-platform-core/`: shared Bun audit, safe-fix, validation, and reference-sync library.
- `crates/gsap-audit-core/`: oxc-based static-analysis library powering the gsap skill's audit CLI.
- `crates/gsap-audit/`: Rust CLI that audits GSAP usage in JS/TS/JSX/TSX.
- `crates/expo-motion-audit-core/`: oxc-based static-analysis library powering the expo-motion skill's audit CLI.
- `crates/expo-motion-audit/`: Rust CLI that audits Expo/React Native (Reanimated 4) motion usage in JS/TS/JSX/TSX + config.
- `crates/motion-token-audit-core/`: oxc-based engine for cross-stack motion-token drift and orphan analysis.
- `crates/motion-token-audit/`: Rust CLI that audits motion-token consistency across CSS, R3F, Reanimated, and GSAP.
- `crates/claude-config-audit/`: Rust CLI that audits a Claude Code configuration estate for drift (broken skill links, stale overrides, duplicate agents, oversized guides).
- `docs/`: tracked documentation portal, references, cookbooks, prompts, and runbooks.
Example skill path: `skills/docker-architect/SKILL.md`.
## Build, Test, and Development Commands
- Validate a skill (frontmatter/spec checks):
`python3 tools/skill/quick_validate.py skills/<skill-name>`
- Validate all skills:
`for d in skills/*; do [ -f "$d/SKILL.md" ] && python3 tools/skill/quick_validate.py "$d"; done`
- Package a `.skill` bundle:
`python3 tools/skill/package_skill.py skills/<skill-name> skills/dist`
- Optional sanity check for Python scripts:
`python3 -m compileall -q skills`
- Build/check the research CLI:
`cargo check -p codex-research`
- Build/check the development CLI:
`cargo check -p codex-dev`
- Build/check the development core crate:
`cargo check -p codex-dev-core`
- Build/check the development TUI:
`cargo check -p codex-dev-tui`
- Run the research CLI smoke checks:
`codex-research --json doctor && codex-research --json eval`
## Coding Style & Naming Conventions
- Skill names must be **hyphen-case** and match the folder name (e.g. `langgraph-multiagent`).
- `SKILL.md` frontmatter should only use allowed keys: `name`, `description`, `license`, `allowed-tools`, `metadata`, `disable-model-invocation` (set `true` to opt a skill out of implicit model invocation).
- Keep `SKILL.md` concise; put large content in `references/`. Prefer scripts over massive inline code blocks.
- When replacing or retiring a skill, move the old source to `archive/skills/<skill-name>/`, add `archive.json` with `skill_archive.v1`, remove active catalog links, and verify with `codex-dev --json skills audit`.
- Custom subagent TOML names must be **snake_case** and must not shadow Codex built-ins (`default`, `worker`, `explorer`) unless explicitly requested.
- Keep generated Rust docs and `target/` out of git; document Rust APIs by updating the relevant docs under `docs/reference/`.
## Testing Guidelines
The PR baseline lives in `.github/workflows/ci.yml` and is documented in
`docs/runbooks/validation.md#pull-request-ci-baseline`. Install
`requirements-ci.txt` before reproducing its Python-backed gates. Treat the
following as the required focused gates based on touched files:
- Any skill: `python3 tools/skill/quick_validate.py skills/<skill-name>`
- All skills: `for d in skills/*; do [ -f "$d/SKILL.md" ] && python3 tools/skill/quick_validate.py "$d"; done`
- Plugin skills: `for d in plugins/*/skills/*; do [ -f "$d/SKILL.md" ] && python3 tools/skill/quick_validate.py "$d"; done`
- Local plugins: `node plugins/web-motion/scripts/validate-atomic-skills.mjs` and `find .claude-plugin plugins -type f -name '*.json' -exec jq empty {} +`
- Python helpers: `python3 -m compileall -q skills tools subagents/codex/scripts`
- Custom agent templates: `python3 skills/subagent-creator/scripts/subagent_creator.py validate skills/deep-researcher/templates/agents skills/subagent-creator/templates/agents skills/subspawn/templates/agents subagents/codex/agents`
- Subspawn plans: run `python3 skills/subspawn/scripts/subspawn_plan.py validate-roles` and `python3 skills/subspawn/scripts/subspawn_plan.py plan --preset research --task "validation smoke" --scope "docs and template metadata" --json`
- Skill/subagent eval lab: `python3 tools/eval/skill_subagent_eval.py --json`
- Bootstrap packs: `cargo run -q -p codex-dev -- --json bootstrap status`, `python3 tools/bootstrap/render_bootstrap_pack.py --validate`, render changed packs into temp directories only, and run the Codex subagent smoke matrix in `docs/runbooks/validation.md`
- Research CLI: `cargo fmt --all --check`, `cargo clippy -p codex-research --all-targets -- -D warnings`, `cargo check -p codex-research`, `cargo test -p codex-research`, `cargo run -q -p codex-research -- completions zsh >/tmp/codex-research.zsh`, `cargo run -q -p codex-research -- manpage >/tmp/codex-research.1`
- Development core/CLI: `cargo fmt --all --check`, `cargo clippy -p codex-dev-core --all-targets -- -D warnings`, `cargo clippy -p codex-dev --all-targets -- -D warnings`, `cargo check -p codex-dev-core`, `cargo check -p codex-dev`, `cargo test -p codex-dev-core`, `cargo test -p codex-dev`, `cargo run -q -p codex-dev -- --help`, `cargo run -q -p codex-dev -- completions zsh >/tmp/codex-dev.zsh`, `cargo run -q -p codex-dev -- manpage >/tmp/codex-dev.1`, `cargo run -q -p codex-dev -- --json policy explain --profile full_local`, `cargo run -q -p codex-dev -- --json policy docs-check`, `cargo run -q -p codex-dev -- --json local doctor`, `cargo run -q -p codex-dev -- --json local status`, `cargo run -q -p codex-dev -- --json skills inventory`, `cargo run -q -p codex-dev -- --json bootstrap status`, `cargo run -q -p codex-dev -- --json task list`, `cargo run -q -p codex-dev -- --json research import-bundle --help`, `cargo run -q -p codex-dev -- --json orchestration verify --help`, `cargo run -q -p codex-dev -- --json pr plan --repo BjornMelin/dev-skills --number 25`, `cargo run -q -p codex-dev -- --json pr agent --help`, `cargo run -q -p codex-dev -- --json pr agent-action --help`, `cargo run -q -p codex-dev -- --json pr review --help`, `cargo run -q -p codex-dev -- --json pr readiness --help`, `cargo run -q -p codex-dev -- --json review --help`, `cargo run -q -p codex-dev -- --json commit plan --help`, `cargo run -q -p codex-dev -- --json commit validate --subject "fix(codex-dev): preserve review-thread closeout evidence"`; run the task capsule, orchestration, and PR fixture smoke in `docs/runbooks/validation.md` when capsule, orchestration, policy, or PR recording behavior changes.
- GSAP audit core/CLI: `cargo fmt --all --check`, `cargo clippy -p gsap-audit-core -p gsap-audit --all-targets -- -D warnings`, `cargo check -p gsap-audit-core -p gsap-audit`, `cargo test -p gsap-audit-core -p gsap-audit`, and a CLI smoke `cargo run -q -p gsap-audit -- doctor`.
- Expo-motion audit core/CLI: `cargo fmt --all --check`, `cargo clippy -p expo-motion-audit-core -p expo-motion-audit --all-targets -- -D warnings`, `cargo check -p expo-motion-audit-core -p expo-motion-audit`, `cargo test -p expo-motion-audit-core -p expo-motion-audit`, and a CLI smoke `cargo run -q -p expo-motion-audit -- doctor`.
- Motion-token audit core/CLI: `cargo fmt --all --check`, `cargo clippy -p motion-token-audit-core -p motion-token-audit --all-targets -- -D warnings`, `cargo check -p motion-token-audit-core -p motion-token-audit`, `cargo test -p motion-token-audit-core -p motion-token-audit`, and a CLI smoke `cargo run -q -p motion-token-audit -- doctor`.
- Claude config audit CLI: `cargo clippy -p claude-config-audit --all-targets -- -D warnings`, `cargo check -p claude-config-audit`, and a CLI smoke `cargo run -q -p claude-config-audit -- doctor`.
- Design-motion skill tooling: `python3 -m unittest discover -s skills/design-motion-audit/scripts/tests`, a lint smoke `node skills/r3f-scene-polish/scripts/audit.mjs doctor`, and the plugin-mirror drift guard `node plugins/design-motion/scripts/sync-skills.mjs --check` (the `plugins/design-motion/skills/` mirror is generated from the canonical `skills/` copies — regenerate with `node plugins/design-motion/scripts/sync-skills.mjs` after editing a canonical design-motion skill).
- Local release/supply-chain: run the baseline in `docs/runbooks/local-release-supply-chain.md`, including `cargo metadata --locked --no-deps --format-version 1`, `cargo tree -d --target all`, `cargo deny check bans licenses sources`, `cargo package --list` for every workspace crate, and explicit networked advisory checks (`cargo deny check advisories`, `cargo audit`) when release evidence requires them.
Machine-owned policy command smoke mirror, checked by `cargo run -q -p codex-dev -- --json policy docs-check`:
```bash
# codex-dev:policy-manifest-smoke:start
cargo run -q -p codex-dev -- --json policy manifest --profile codex_dev
cargo run -q -p codex-dev -- --json policy explain --profile codex_dev
cargo run -q -p codex-dev -- --json policy manifest --profile full_local
cargo run -q -p codex-dev -- --json policy explain --profile full_local
# codex-dev:policy-manifest-smoke:end
```
- Development TUI: `cargo fmt --all --check`, `cargo clippy -p codex-dev-tui --all-targets -- -D warnings`, `cargo check -p codex-dev-tui`, `cargo test -p codex-dev-tui`, `cargo run -q -p codex-dev-tui -- completions zsh >/tmp/codex-dev-tui.zsh`, `cargo run -q -p codex-dev-tui -- manpage >/tmp/codex-dev-tui.1`; run the render-once smoke in `docs/runbooks/validation.md` when TUI rendering or state loading changes.
- CLI smoke: `codex-research --json doctor`, `codex-research --json eval`
- Global CLI install/artifact workflow: run `docs/runbooks/global-cli-workflow.md` after binary manifest, command shape, completion, manpage, or local install workflow changes.
- Eval suite smoke: `codex-research eval --list`, `codex-research --json eval --task evidence-claims-cited --strict`, `codex-research --json eval --task evidence-bundle-closeout-shape --strict`
- Docs links: `python3 tools/docs/check_links.py docs README.md AGENTS.md`
- Final whitespace check: `git diff --check`
If you add scripts, keep them runnable without external secrets and avoid network calls unless the skill explicitly requires it. Live provider checks should be optional.
If you add a local plugin under `plugins/`, validate the plugin manifest and its contained skills, then install from a runtime mirror or local marketplace entry rather than duplicating the same skills under `~/.agents/skills`.
## Documentation Guidelines
- `docs/index.md` is the documentation portal.
- Update docs when changing CLI commands, data models, skill behavior, subagent templates, validation rules, or install workflow.
- Keep README as a portal and catalog, not a full manual.
- Keep AGENTS.md focused on contributor and agent operating rules.
- Put command references in `docs/reference/`, workflows in `docs/cookbooks/`, prompts in `docs/prompts/`, and validation/troubleshooting in `docs/runbooks/`.
- Do not track generated rustdoc, `target/`, provider dumps with private data, run-specific `.codex/research/` artifacts, or local `.codex/tasks/` capsules unless explicitly requested.
## Research/Subagent Stack Rules
- Use `skills/deep-researcher` for deep cited research workflows.
- Use `codex-research` for provider planning, Context7 REST, GitHub REST, direct fetch probes, Firecrawl calls, evidence ledgers, reports, cache, doctor, and evals.
- Use native Codex web tools for current official facts; `codex-research` records provider evidence and handles external calls it owns directly.
- Use `skills/subagent-creator/scripts/subagent_creator.py` to validate or install custom agent templates.
- Use `skills/subspawn` when spawning agents. Use `skills/subspawn/scripts/subspawn_plan.py` for nontrivial fanout plans. After spawning a planned batch, wait for every spawned subagent before substantive next work or final synthesis.
- Use `subagents/codex/ROLE_CATALOG.md` as the canonical GPT-5.6 model/effort
routing matrix. Prefer role-file pins; V2 custom or overridden spawns use a
fresh named fork.
## Commit & Pull Request Guidelines
This repo may not have established git history conventions yet. Use clear, scoped commits (recommended: Conventional Commits), e.g. `feat(dmc-py): add callbacks scaffold` or `docs: expand README catalog`. PRs should include:
- What changed + why
- Validation commands run (at minimum `python3 tools/skill/quick_validate.py skills/<skill-name>`)
- If you add or rename a skill, update the catalog table in `README.md` (keep rows sorted by skill name)
- If you add or materially change docs, update `docs/index.md`
- If you change `codex-dev-core`, `codex-dev`, `codex-dev-tui`, `codex-research`, `bun-platform-core`, `gsap-audit-core`, `gsap-audit`, `expo-motion-audit-core`, `expo-motion-audit`, `motion-token-audit-core`, or `motion-token-audit`, update the CLI/TUI and crate references under `docs/reference/`
- If you built/published bundles, say where (release assets/registry)
## Security & Configuration Tips
Do not commit credentials or private tokens (use `.env.example` patterns). Assume any `.skill` bundle is redistributable; keep sensitive material out of skill folders and packaged artifacts.