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
.grok-plugin/
  marketplace.json        # Grok marketplace catalog
plugins/
  <plugin-name>/
    .codex-plugin/
      plugin.json         # Codex plugin manifest
    .claude-plugin/
      plugin.json         # Claude Code plugin manifest
    kimi.plugin.json      # Kimi 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.

For the Grok marketplace and Kimi plugin surfaces, see the Grok and Kimi plugin install cookbook. 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 used to create it.

• Bundles are treated as build artifacts here (gitignored) and are intended to

be published via release assets / registries.

Contributing (to this repo)

• Keep the skill entrypoint in skills/<skill-name>/SKILL.md.
• Put long-form material in references/ and executable helpers in scripts/.
• Keep frontmatter minimal and spec-compatible (the validator enforces allowed keys).

License

This repository may contain skills under different licenses. Check each skill directory for license files (for example skills/vitest-dev/LICENSE) and follow the terms for that specific skill.

Public-repo guard

This repository is public. tools/policy/check_public_leaks.py blocks private-project references (it runs in CI and as the .githooks/pre-commit hook; enable locally with git config core.hooksPath .githooks). Private skills and flavored variants belong in their own private repos.