Portable workflow skills for Codex.
This repository helps Codex work in a more structured and useful way across many different projects.
Instead of reinventing prompts every time, you can give Codex reusable skills for:
- understanding a repository
- documenting a project
- clarifying feature requirements
- planning implementation
- reviewing code properly
- checking plans against the real codebase
- splitting large work into cleaner parallel parts
Coding-agent work usually breaks in the same places:
- the project context is unclear
- requirements are vague
- implementation starts too early
- reviews are shallow
- plans sound good but do not match the repo
This pack exists to reduce that.
The goal is not more process for its own sake.
The goal is:
- less confusion
- less rework
- better planning
- stronger review
- more reliable execution
This repository is useful for:
- beginners who want more structure
- solo developers using Codex seriously
- builders working across many unrelated repos
- anyone who wants repeatable quality instead of one-off prompting
The pack is written in plain language first, so each skill tries to answer:
- what it does
- when to use it
- why it helps
- what output you should expect
Copy any skill folder from this repository into:
~/.codex/skills/
Then call it in your prompt:
Use $project-knowledge on this repository.
Use $project-status to write a current-state snapshot.
Use $user-spec-planning to turn this feature idea into a clear spec.
Use $code-reviewing to review these changes.
Use $skeptic to check whether this plan really matches the repo.
You do not need to adopt the whole pack at once.
Start with one skill that solves the problem you have right now.
You can use prompts like these directly:
Use $project-knowledge on this repository.
Create a compact project knowledge base that explains what this project does, how it is structured, and how it runs.
Use $project-status to write a current-state snapshot for this repository.
Focus on what works, what is incomplete, what is actually true on disk, and what should happen next.
Use $user-spec-planning to turn this feature idea into a clear spec.
Ask focused questions where needed and write the result to work/<feature>/user-spec.md.
Use $tech-spec-planning on the approved user spec for this feature.
Create a technical plan with architecture decisions, risks, tests, and implementation tasks.
Use $code-reviewing to review these changes.
Find real bugs, regression risks, missing tests, and cross-file mismatches.
Use $skeptic to verify this plan against the repository.
Check whether the referenced files, functions, and dependencies are real.
If you are opening this repository for the first time, start with these three:
Use this when a repo is under-documented or hard to understand.
It helps create a small knowledge base for the project:
- what the project does
- how it is built
- how it runs
- where the important moving parts are
Typical output:
docs/project_knowledge/project.mddocs/project_knowledge/architecture.mddocs/project_knowledge/patterns.mddocs/project_knowledge/deployment.md
Use this when you need a clean snapshot of the current state of a project.
It helps answer:
- what already works
- what is broken or incomplete
- what changed recently
- what should happen next
Typical output:
docs/project_status_YYYY-MM-DD.md
Use this after code changes are made.
It helps find:
- bugs
- regressions
- weak assumptions
- missing tests
- cross-file mismatches
Typical output:
- structured findings with severity, impact, and suggested fixes
Create a durable project knowledge base.
Best for:
- new repos
- inherited repos
- messy repos with weak docs
Write a readable current-state project snapshot.
Best for:
- handoffs
- progress tracking
- “what is actually true right now?” moments
Turn a vague feature idea into a clear user-facing spec before coding starts.
Best for:
- feature planning
- scoping bugfixes
- making acceptance criteria explicit
Typical output:
work/<feature>/user-spec.md
Turn an approved feature spec into a technical implementation plan.
Best for:
- architecture decisions
- implementation planning
- test and risk planning
Typical output:
work/<feature>/tech-spec.md
Review code with a bug-first mindset.
Best for:
- PR review
- pre-merge checks
- post-implementation quality passes
Reality-check a plan, review, or spec against the actual repository.
Best for:
- catching hallucinated files or APIs
- validating plans before coding
- reducing “looks plausible” mistakes
Typical output:
- a mismatch report grounded in the repo
Split large work into cleaner local and delegated parts.
Best for:
- larger multi-step tasks
- parallel investigation and implementation
- keeping complex work from turning into one long messy run
Typical output:
- a short execution plan
- bounded work split
- clearer ownership and verification
The examples/ folder contains short prompt examples for:
- project-knowledge
- project-status
- user-spec-planning
- tech-spec-planning
- code-reviewing
- skeptic
- compound-delivery
If you are just getting started:
project-knowledgeproject-statususer-spec-planningtech-spec-planningcode-reviewingskepticcompound-delivery
Why this order:
- first understand the repo
- then understand its current state
- then plan work
- then review work
- then scale up to more complex execution
Each skill lives in its own folder:
SKILL.mdcontains the main instructionsreferences/contains optional deeper guidanceagents/openai.yamlcontains Codex UI metadata
Other repository files:
examples/contains short usage examplesCONTRIBUTING.mdexplains what kinds of additions belong here
Codex works better when quality patterns live outside one-off prompts.
This pack is built around a simple idea:
- keep skills reusable
- keep them understandable
- keep them useful across many repos
MIT