skills

Portable, reusable workflows for Codex, Claude Code, and compatible AI agents. Each skill packages trigger metadata, a focused SKILL.md workflow, and optional reference material so an agent can load only the guidance needed for the task.

Quick Start

Requirements: Git, Bash, and an installed Codex or Claude Code host.

Install one representative skill for Codex:

git clone https://github.com/r3dlex/skills.git
cd skills
./scripts/install-codex.sh --skill diagnose
test -f "$HOME/.codex/skills/diagnose/SKILL.md"

Start Codex and invoke the installed workflow:

codex

$diagnose "why does this command fail?"

Expected result: Codex discovers diagnose/SKILL.md and begins the reproduce-minimize-hypothesize-instrument-fix loop.

Install for another host

Host	Recommended command	Installed catalog
Codex	./scripts/install-codex.sh --all	~/.codex/skills/
Claude Code	./scripts/install-claude-code.sh --user	~/.claude/skills/omc-learned/
Auggie	./scripts/install-auggie.sh --all	~/.auggie/rules/
Gemini	./scripts/install-gemini.sh --all	~/.gemini/skills/
GitHub Copilot	./scripts/install-copilot.sh --repo /path/to/repo	/path/to/repo/.github/

Codex and Claude Code recursively install each selected skill directory, including references and bundled scripts. Auggie, Gemini, and GitHub Copilot receive host-specific flattened or synthesized projections suited to their instruction surfaces. tests/install_cross_host_parity_test.sh verifies both recursive-copy parity and the distinct projection shapes. The canonical README generator is available only in the recursive Claude Code and Codex installations.

How the catalog works

Skills are organized by the workflow stage they own:

1. Discover and decide — establish vocabulary and context.
2. Govern and plan — turn intent into reviewed, traceable work.
3. Configure and generate — create or modify repository artifacts.
4. Validate and hand off — verify, ship, or transfer completed work.

A skill's frontmatter description controls discovery. Its SKILL.md contains the lean execution path; deeper detail lives in referenced files and is loaded only when needed. See CONTEXT.md for the shared domain language.

Featured workflows

• northstar turns intent into a tracked, sliced plan and A-to-B handoff without implementing it.
• autobahn ships an implementation-ready handoff through TDD, review, CI, and fail-closed merge gates.
• write-a-skill creates a skill with progressive disclosure and portable host behavior.
• diagnose runs a disciplined debugging loop from reproduction through verified fix.

Complete catalog

The table below is generated from catalog.json. Preserve its marker comments when editing this README.

Skill	When to use	Lifecycle	Owner phase
ai-catapult-init	Bootstrap AI-ready governance, traceability, cascade, catalog audits, and validation. Use when setting up AI SDLC; aliases: init-ai-repo and ai-sdlc-init.	stable	03-configure-generate
ai-sdlc-init	Deprecated compatibility alias for ai-catapult-init. Use only when legacy prompts invoke "ai-sdlc-init"; otherwise use "ai-catapult-init".	compatibility	03-configure-generate
ask-ai-catapult	Ask which skill or flow fits your situation. Use when you know what you want to achieve but not which skills to combine, or which order to run them in.	stable	01-discover-decide
autobahn	Ship implementation-ready goals from a northstar handoff or evidence-complete direct record, with review, CI, fail-closed merge, and cascade closure.	stable	04-validate-handoff
code-review	Review changes since a fixed point along two axes, Standards and Spec, reported side by side. Use when reviewing a branch, a PR, or work in progress.	stable	04-validate-handoff
codebase-design	Shared vocabulary for designing deep modules. Use when shaping an interface, placing a seam, finding deepening opportunities, or when another skill needs it.	stable	02-govern-plan
design-an-api-or-interface	Design APIs/interfaces with Design It Twice: create alternatives, compare tradeoffs, choose one. Use when designing an API, module, class, or boundary.	stable	02-govern-plan
diagnose	Run a reproduce-minimize-hypothesize-instrument-fix loop. Use when debugging bugs, failures, thrown errors, or performance regressions.	stable	04-validate-handoff
diagnosing-bugs	Diagnosis loop for hard bugs and performance regressions. Use when asked to diagnose or debug, or when something is broken, throwing, failing, or slow.	stable	04-validate-handoff
domain-modeling	Build and sharpen a project domain model or ubiquitous language. Use when pinning down domain terms, recording an architectural decision, or keeping a glossary.	stable	01-discover-decide
edit-article	Edit and improve articles by restructuring sections, improving clarity, and tightening prose	stable	03-configure-generate
eval-a-skill	Scaffold a structurally valid eval triplet for a target skill under .ai/evals/. CI checks structure only; the LM-judge runs out-of-band, never in CI.	stable	04-validate-handoff
grill-me	Interview the user to stress-test a plan or design until decisions are clear. Use when the user wants to be grilled or challenge a plan.	stable	02-govern-plan
grill-with-docs	Stress-test a plan against repo docs and update decisions inline. Use when challenging a design against documented language, ADRs, or CONTEXT.md.	stable	02-govern-plan
grilling	Interview relentlessly to stress-test a plan, decision, or idea. Use when thinking needs challenging before it hardens into work.	stable	02-govern-plan
handoff	Compact the current conversation into a handoff document for another agent to pick up.	stable	04-validate-handoff
implement	Implement a piece of work from a spec or set of tickets. Use when the decisions are already made and the work just needs building.	stable	03-configure-generate
improve-codebase-architecture	Find deepening opportunities from CONTEXT.md and ADRs. Use when refactoring shallow modules, boundaries, coupling, or testability.	stable	02-govern-plan
init-ai-repo	Deprecated compatibility alias for ai-catapult-init. Use only when legacy prompts invoke "init-ai-repo"; otherwise use "ai-catapult-init".	compatibility	03-configure-generate
northstar	Planning-only intake: turn intent into a tracked, sliced plan and A→B handoff; never implement product changes. Use before autobahn execution.	stable	02-govern-plan
prototype	Build a throwaway prototype to answer a design question. Use when sanity-checking a state model or logic, or exploring what a UI should look like.	stable	03-configure-generate
publish-semver	Set up semantic or calendar versioning and package publishing across supported ecosystems. Use when configuring release automation or changelogs.	stable	04-validate-handoff
research	Investigate a question against high-trust primary sources and write the findings to a Markdown file. Use when a topic needs researching or API facts gathered.	stable	01-discover-decide
resolving-merge-conflicts	Resolve an in-progress git merge or rebase conflict hunk by hunk. Use when a merge or rebase has stopped with conflicts that need resolving.	stable	04-validate-handoff
setup-skills	Configure AGENTS/CLAUDE and docs/agents for tracker, triage labels, and domain docs. Use before issue, PRD, triage, TDD, or diagnosis skills.	stable	03-configure-generate
tdd	Run red-green-refactor with one failing test, one implementation, then cleanup. Use when building features or fixes test-first.	stable	03-configure-generate
to-issues	Break a plan, spec, or PRD into traceable implementation issues. Use when converting requirements into tickets or agent-ready work.	stable	02-govern-plan
to-prd	Turn the current conversation context into a PRD and publish it to the project issue tracker. Use when user wants to create a PRD from the current context.	stable	02-govern-plan
to-spec	Turn the current conversation into a spec and raise it as an issue. Use after a design discussion — no interview, just synthesis of what was already decided.	stable	02-govern-plan
to-tickets	Break a plan, spec, or conversation into tracer-bullet tickets, each declaring its blocking edges. Use when turning a plan into agent-grabbable slices.	stable	02-govern-plan
triage	Triage issues through canonical state labels and ownership roles. Use when creating, reviewing, prioritizing, or preparing issues for agents.	stable	02-govern-plan
ubiquitous-language	Extract and save a DDD glossary, flag ambiguities, and propose canonical terms. Use when defining domain language or a shared vocabulary.	deprecated	01-discover-decide
using-git-worktrees	Create isolated git worktrees with safety checks and setup guidance. Use when starting feature work that needs separation from the main checkout.	stable	03-configure-generate
wayfinder	Chart work too big for one agent session as a map of decision tickets, resolved one at a time. Use when the way to the destination is not yet visible.	stable	02-govern-plan
wizard	Generate an interactive bash wizard for steps only a human can do, not for steps the agent can do itself. Use when provisioning infra or capturing CI secrets.	stable	03-configure-generate
write-a-skill	Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.	stable	03-configure-generate
write-agent-docs	Write or audit agent-facing Markdown with progressive disclosure. Use when editing SKILL.md, AGENTS.md, README.md, or other agent docs.	stable	03-configure-generate
zoom-out	Explain broader code or product context around a focused area. Use when the user needs a higher-level perspective before local changes.	stable	01-discover-decide

Update

Refresh the repository and reinstall the catalog for your host:

git pull --ff-only
./scripts/install-codex.sh --all

Use the corresponding host installer from the table above when you do not use Codex. Each deprecated compatibility alias remains installable for legacy prompts, but new workflows should use the canonical skill name.

Contributing

Read AGENTS.md for repository conventions and CONTRIBUTING.md for the protected-main delivery contract. Validate catalog metadata with:

python3 scripts/validate-skill-catalog.py

Each skill follows this structure:

skill-name/
├── SKILL.md        # Trigger metadata and core workflow
├── REFERENCE.md    # Optional detail loaded on demand
└── scripts/        # Optional deterministic utilities

License

Apache-2.0 — see LICENSE.

This repository follows the AI-SDLC methodology. See AGENTS.md for the operating contract and docs/architecture/adr/ for architectural decisions.

The v3 scaffold is indexed by .ai/matrix.json; human overrides remain under .memory/human-override/.