dev-skills

A versioned collection of reusable Agent Skills (per the AgentSkills specification) that I use to make coding agents more reliable, consistent, and fast.

• Spec: https://agentskills.io/specification
• Skill registry: https://skills.sh/

What Is In This Repo

This repo now contains skill packages and supporting tooling:

• reusable skills under skills/;
• retired skill source history under flat archive/skills/<name>/ leaves or optional gsap, native, and rust group containers;
• reusable local Codex plugin source under plugins/;
• repo bootstrap pack manifests and templates under bootstrap/;
• a Rust shared development contract crate, codex-dev-core, under crates/;
• a Rust development CLI, codex-dev, under crates/;
• an optional Rust terminal workbench, codex-dev-tui, under crates/;
• a Rust research CLI, codex-research, under crates/;
• Codex subagent source packs under subagents/;
• tracked documentation under docs/;
• skill, bootstrap, docs, and eval helpers under tools/.

Start with docs/index.md for the full guide set.

Key docs:

• Onboarding
• System overview
• Research architecture
• codex-dev operating layer spec
• dev-skills v0.3/v1 roadmap
• Future local app surfaces
• codex-dev core reference
• codex-dev CLI reference
• codex-dev TUI reference
• gsap-audit reference
• expo-motion-audit reference
• motion-token-audit reference
• claude-config-audit reference
• codex-research v0.2 follow-up spec
• codex-research CLI reference
• codex-research crate reference
• Global CLI workflow
• Rust skill suite
• Memory guidance proposals
• Codex prompt library
• Claude Code motion plugin install

For local live-provider testing, copy .env.example to an untracked .env and export it in your shell before running provider commands.

Each skill lives in skills/<skill-name>/ and is designed to be:

• Self-contained (instructions + optional scripts/assets)
• Discoverable (clear metadata + predictable layout)
• Packagable (can be shipped as a .skill ZIP archive)

Repository layout

skills/
  <skill-name>/
    SKILL.md              # required (YAML frontmatter + instructions)
    references/           # optional (docs to load on demand)
    scripts/              # optional (deterministic helpers)
    assets/               # optional (templates/snippets)
    templates/            # optional (scaffolds)
  dist/                   # local .skill bundles (ZIP; gitignored)
archive/
  skills/
    <skill-name>/
      archive.json        # required archive metadata
      SKILL.md            # retained source; not active
    {gsap,native,rust}/   # optional organization-only group containers
      <skill-name>/
        archive.json      # full archived_path includes the group
        SKILL.md          # leaf is the archived skill; group is not
.claude-plugin/
  marketplace.json        # Claude Code marketplace catalog
plugins/
  <plugin-name>/
    .codex-plugin/
      plugin.json         # Codex plugin manifest
    .claude-plugin/
      plugin.json         # Claude Code plugin manifest
    skills/
      <skill-name>/
        SKILL.md          # plugin-scoped skill entrypoint
crates/
  bun-platform-core/      # Shared native Bun audit, fix, validation, and reference engine
  codex-dev-core/         # Shared task capsule contracts and read-model helpers
  codex-dev/              # Rust CLI for local task capsules, policy gates, and development evidence
  codex-dev-tui/          # Optional Ratatui workbench for codex-dev capsules
  codex-research/         # Rust CLI for evidence-first research helpers
  gsap-audit-core/        # oxc-based static-analysis engine for the gsap skill
  gsap-audit/             # Rust CLI that audits GSAP usage in JS/TS/JSX/TSX
  expo-motion-audit-core/ # oxc-based static-analysis engine for the expo-motion skill
  expo-motion-audit/      # Rust CLI that audits Expo/React Native motion (Reanimated) usage
  motion-token-audit-core/ # oxc-based engine for cross-stack motion-token drift/orphan analysis
  motion-token-audit/     # Rust CLI that audits motion-token consistency across CSS/R3F/Reanimated/GSAP
  claude-config-audit/    # Rust CLI that audits a Claude Code config estate for drift
docs/
  index.md                # documentation portal
  architecture/           # system design
  guides/                 # onboarding and setup
  reference/              # CLI, crate, skill, and template references
  cookbooks/              # operator-grade workflows
  prompts/                # copy-paste Codex prompts
  runbooks/               # validation, troubleshooting, maintenance
tools/
  bootstrap/              # repo bootstrap pack renderer
  eval/                   # offline skill/subagent eval runner
  docs/                   # documentation checks
  skill/                  # skill validation and packaging helpers
subagents/
  codex/                  # tracked global roles, public overlays, and sync helpers

Research, Subagent, and Operating Stack

The main system combines research helpers, reusable subagents, and a development operating layer:

• deep-researcher: skill for deep cited research with a Focused Six subagent pack.
• codex-research: Rust CLI for planning, provider routing, Context7 REST, GitHub REST, fetch probes, Firecrawl calls, evidence ledgers, reports, closeout bundles, cache, doctor, and evals.
• codex-dev-core: shared contract/read-model crate for task capsules, validation, rendered summaries, skill inventory, task index, orchestration run projections, policy manifest data, and PR evidence snapshots.
• codex-dev: current CLI for local task capsule lifecycle, structured evidence appenders, subspawn plan/outcome/synthesis capture, orchestration run verification, repo-native policy gates, read-only local workstation readiness checks, and PR evidence capture. It depends on codex-dev-core and keeps Clap parsing plus process execution at the CLI boundary.
• codex-dev-tui: optional Ratatui workbench that reads codex-dev capsule JSON contracts through codex-dev-core, including operator panels for skill health, task index, orchestration runs, PR-agent blockers, and next actions, without owning policy logic.
• skill_subagent_eval.py: offline eval lab for the full skill catalog, skill assets, OpenAI agent metadata, subagent templates, role contracts, and planner presets.
• render_bootstrap_pack.py: manifest-backed bootstrap packs for seeding new repos with agent guidance and validation docs.
• subagent-creator: helper skill and CLI for custom Codex agent templates.
• subspawn: strict subagent delegation policy with planner-generated prompts and mandatory wait-before-next-work synthesis.

Build and install the local CLIs from a trusted checkout:

cargo build -p codex-research
cargo build -p codex-dev
cargo build -p codex-dev-tui
cargo install --path crates/codex-research --locked --force
cargo install --path crates/codex-dev --locked --force
cargo install --path crates/codex-dev-tui --locked --force
codex-research --json doctor
codex-dev --help
codex-dev-tui --help

Generate shell completions and manpages from the installed binaries:

codex-research completions zsh > /tmp/_codex-research
codex-dev completions zsh > /tmp/_codex-dev
codex-dev-tui completions zsh > /tmp/_codex-dev-tui
codex-research manpage > /tmp/codex-research.1
codex-dev manpage > /tmp/codex-dev.1
codex-dev-tui manpage > /tmp/codex-dev-tui.1

Smoke the development CLI from source:

cargo build -p codex-dev
cargo build -p codex-dev-core
cargo build -p codex-dev-tui
cargo run -q -p codex-dev -- --help
# 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
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 skills sync-kimi --dry-run --project-root "$PWD"
cargo run -q -p codex-dev -- --json skills catalog --out /tmp/agent-skills-lab.json
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 canonical task capsule fixture in Validation when changing orchestration plan/record/close/verify behavior.

For release handoff and safe updates from any directory, use the Global CLI Workflow and Local Release and Supply Chain runbooks. codex-dev-core is a library crate, not an installed binary.

Preview a repo bootstrap pack:

tmp=$(mktemp -d)
cargo run -q -p codex-dev -- --json bootstrap status
cargo run -q -p codex-dev -- --json bootstrap plan --pack codex-agent-repo --out "$tmp/codex" --repo-name codex-smoke
python3 tools/bootstrap/render_bootstrap_pack.py --list
python3 tools/bootstrap/render_bootstrap_pack.py --pack codex-agent-repo --out "$tmp/codex" --repo-name codex-smoke --dry-run

Install the deep research agents:

python3 skills/deep-researcher/scripts/install_agents.py --target global --dry-run
python3 skills/deep-researcher/scripts/install_agents.py --target global

For custom subagent template ownership, packaged fallback copies, duplicate-role validation, and skill packaging rules, see Subagent Templates.

Skill catalog

Active skills are stored in skills/. The canonical entrypoint for each active skill is its SKILL.md. Machine-readable inventory for automation is available through codex-dev --json skills inventory; the public Agent Skills Lab artifact is generated with codex-dev --json skills catalog --source-ref main --out catalog/agent-skills-lab.json. Retired skills belong in flat archive/skills/<name>/ leaves or under the optional archive/skills/{gsap,native,rust}/<name>/ group containers. Each leaf keeps the skill's hyphen-case name and an archive.json whose archived_path is the full retained path; group containers are not skills. Archived skills must not remain linked from this active catalog. The table below remains the human-facing active catalog. For how the generated artifact reaches the public Agent Skills Lab at bjornmelin.io/agent-skills, see the Agent Skills Lab catalog pipeline.

Local Plugin Skill Bundles

Install the web-motion plugin in Claude Code:

claude plugin marketplace add BjornMelin/dev-skills --sparse .claude-plugin plugins/web-motion plugins/claude-core plugins/design-motion
claude plugin install web-motion@bjorn-dev-skills
claude plugin install claude-core@bjorn-dev-skills
claude plugin install design-motion@bjorn-dev-skills

(The former native-motion plugin was consolidated into the standalone expo-motion skill — install it with skills add BjornMelin/dev-skills -g -s expo-motion.)

The design-motion plugin bundles the design-motion-audit and r3f-scene-polish skills plus seven specialist subagents and a director output style; those two skills are also individually installable (e.g. skills add BjornMelin/dev-skills -g -s design-motion-audit). To use the seven subagents without the plugin, install them into your Claude Code agents directory:

python3 plugins/design-motion/scripts/install_agents.py --target global   # ~/.claude/agents
python3 plugins/design-motion/scripts/install_agents.py --target project  # ./.claude/agents

After installing inside an active Claude Code session, run /reload-plugins. See the Claude Code motion plugin install cookbook for local development and validation commands.

Using these skills

How you “install” a skill depends on your agent runtime. In general, you need the skill folder available on disk so the runtime can read SKILL.md and (optionally) bundled resources.

Common approaches:

• From source: copy or symlink skills/<skill-name>/ into your runtime’s skills directory.
• From a bundle: use a .skill bundle (ZIP) and install it using your runtime/registry tooling (for example via https://skills.sh/).

Validating and packaging

This repo includes lightweight validation and packaging helpers under tools/skill/.

Install the pinned Python validation dependency before running the complete skill and documentation gates:

python3 -m pip install -r requirements-ci.txt

Validate a skill directory:

python3 tools/skill/quick_validate.py skills/<skill-name>

Package a skill to skills/dist/<skill-name>.skill:

python3 tools/skill/package_skill.py skills/<skill-name> skills/dist

Build the Rust CLIs:

cargo build -p codex-dev
cargo build -p codex-dev-core
cargo build -p codex-dev-tui
cargo build -p codex-research

Pull requests run the complete Rust workspace, catalog, skill, plugin, generated-mirror, Bun, and documentation baseline in CI. The copy-ready local commands remain in the Validation runbook.

Use docs/runbooks/validation.md for the canonical validation matrix and docs/runbooks/local-release-supply-chain.md for the audited local install and release baseline. Use docs/reference/distribution-surface-gates.md before opening crates.io publication, signed-binary, cargo-vet, Tauri desktop, or Axum local-service implementation work. README intentionally stays a portal so command lists do not drift from the runbooks. Use docs/reference/subagent-templates.md for the subagent template authority model and duplicate-role expectations.

Rust skill suite validation:

node skills/rust-expert/scripts/check-reference-links.mjs skills/rust-expert skills/rust-cli-clap skills/rust-tui-ratatui skills/rust-tauri-apps skills/rust-web-services skills/rust-mega-eng
node skills/rust-expert/scripts/check-trigger-evals.mjs skills/rust-expert skills/rust-cli-clap skills/rust-tui-ratatui skills/rust-tauri-apps skills/rust-web-services skills/rust-mega-eng

Notes:

• A .skill file is a ZIP archive containing a <skill-name>/... folder. skills/<skill-name>/... is the source-tree path use