Codex Skills

Reusable AI-assisted engineering workflows for Codex, written for unrestricted public use through clean-room authoring.

This repository is not a prompt gallery. It is a small operating manual library for repeatable engineering work: diagnosis, code review, architecture review, database access audit, test-driven development, specification writing, PRD-to-issue planning, delegated repository execution, durable decision traces, reviewed weekly radar ingestion, radar history analysis, external research, visual artifacts, publishing workflows, and tool-specific operations.

The goal is to make AI-assisted engineering more reliable under real project pressure. Each skill defines a workflow that an agent can follow with local repository evidence, explicit validation, and clear boundaries.

Private practice may reveal an abstract capability, engineering invariant, authorization boundary, or failure mode. Public skills must express those lessons through independently designed domains, actors, terminology, data, fixtures, workflows, and implementations. Reusable does not mean universal. Do not generalize, rename, restructure, or rewrite skills just to make the repository look more polished.

This is a personal skill library, not an official OpenAI project.

This is:

• a clean-room library of Codex engineering workflows
• a place for concrete operating procedures, guardrails, evidence rules, and validation paths
• a growing public toolkit grounded in public evidence and independently designed workflow behavior
• a repository where personal or tool-specific defaults can remain when they are publicly safe, explicit, and useful

This is not:

• a prompt gallery
• a generic framework for every possible Codex workflow
• a marketing-polished package that presents opinionated workflows as universal
• a place for secrets, credentials, private customer or project details, private URLs, raw logs, or sensitive identifiers
• a reason to normalize every skill into the same structure before the repository has evidence that the structure fits

I use Codex as an engineering partner, not only as a code generator. The work that benefits most from reusable skills is the work where consistency matters:

• turning vague requests into scoped implementation plans
• debugging with a reproduce, minimize, instrument, fix, and regression-test loop
• reviewing architecture using repository-local evidence
• auditing database access patterns without assuming a specific stack
• preserving decisions so future work does not rediscover the same constraints
• keeping TDD practical and behavior-focused
• converting product or engineering briefs into executable issue plans
• coordinating master/sub-agent repository work through ownership, handoffs, and validation gates
• ingesting reviewed systems and creation radar reports into durable agent-readable memory
• analyzing reviewed radar history for monthly, quarterly, theme, and idea-mining reports
• researching current AI engineering career signals and content opportunities
• turning sponsorship emails into prioritized brand-deal lead lists
• operating specialized tools such as Buffer, Feishu Docs, LinkedIn, Medium, Paper, Readwise, Excalidraw, and genmedia with repeatable guardrails

The skills are intentionally written as operating procedures because the target outcome is repeatable engineering behavior, not clever wording.

The repository direction is captured in a small set of docs:

• docs/repository-contract.md defines the grounded evolution contract.
• docs/skill-taxonomy.md defines category and maturity labels.
• docs/public-sanitization.md defines public repository hygiene.
• docs/clean-room-review.md defines the semantic-independence review required for public skills.
• docs/side-effect-policy.md defines read, write, publishing, and destructive-operation guardrails.
• docs/skill-authoring-guide.md explains how to turn an abstract capability into an independently designed public skill.

Use these docs to classify, contain, and validate existing behavior. Do not use them as permission for broad directory moves or cosmetic rewrites.

Copy the skill directory you want into your Codex skills directory:

mkdir -p ~/.agents/skills
cp -R skills/diagnose ~/.agents/skills/

Then review the copied SKILL.md before relying on it in another repository. Some skills include supporting notes or scripts; keep those files with the skill directory.

Optional registry-based tooling is available for listing and copying skills from skills/index.json:

python scripts/list_skills.py
python scripts/list_skills.py --category review-audit
python scripts/list_skills.py --maturity portable-candidate
python scripts/list_skills.py --show-secondary

python scripts/install_skill.py diagnose --dry-run
python scripts/install_skill.py diagnose
python scripts/install_skill.py diagnose --verify
python scripts/install_skill.py --category review-audit --target ~/.agents/skills --dry-run

install_skill.py copies selected skill directories, verifies their content, and stores source-commit and file-hash receipts outside the discovery directory. --overwrite refuses locally modified destinations. See local workflow tools for installation details and the read-only task-start snapshot and staged commit-scope checker.

Each skill is self-contained:

• skills/*/SKILL.md contains the main workflow.
• skills/*/agents/openai.yaml contains optional discovery metadata; see docs/agent-metadata.md.
• skills/*/*.md contains supporting references, templates, or conventions.
• skills/*/scripts/ contains helper scripts when a workflow needs one.

Use a skill when the task matches the workflow, not because the skill name sounds related. For example, use diagnose when there is a concrete bug or performance regression; use architecture-review when the question is where ownership, authority, or boundaries should live; use agent-legibility-review when the question is whether a future agent can find and safely modify the current repository; use repository-layout-refactor when the user wants to implement a behavior-preserving ownership and package migration.

skills/index.json is the machine-readable registry for skill metadata, including category, maturity, default and maximum normal side-effect levels, supporting files, validation expectations, and portability notes. The historical side_effect_level field remains the maximum normal side-effect level for backward compatibility. It is descriptive metadata for the current skill set, not a requirement to move or rewrite directories.

Run the repository validation command after skill, docs, registry, or README changes:

python scripts/validate_skills.py --require-denylist

The current category map comes from docs/skill-taxonomy.md and skills/index.json. Categories describe what skills do today; they should not be used to force restructuring. Some category memberships are secondary; the registry records those in secondary_categories.

• Workflow over prompt: a useful skill defines steps, evidence, checkpoints, and validation.
• Local evidence first: repository docs, code, tests, configs, and runtime behavior outrank generic best practices.
• Bounded scope: each skill should do one kind of engineering work well.
• Observable outcomes: a skill should produce a review, test, issue plan, decision trace, or verified fix.
• Validation before confidence: claims should be backed by tests, repro loops, source inspection, or explicit uncertainty.
• Private practice is signal, not source material: it may establish only an abstract capability, invariant, authorization boundary, or failure mode; every public expression must be independently designed.
• Reusable but not universal: these skills encode opinions and defaults; adapt them before using them in a different engineering culture.

Vague task:

"This API sometimes returns the wrong result. Can you fix it?"

Repeatable skill-driven flow:

1. Use diagnose to build a deterministic feedback loop: failing test, replay script, CLI fixture, or HTTP request.
2. Reproduce the exact symptom and capture the failure mode.
3. Generate ranked, falsifiable hypotheses before changing code.
4. Add targeted instrumentation that maps to one hypothesis at a time.
5. Convert the minimized repro into a regression test at the correct seam.
6. Fix the bug and rerun both the regression test and the original repro.
7. If the bug exposed unclear ownership or poor test seams, use architecture-review to identify the smallest boundary improvement.
8. If the user asks to implement a broader layout change, use repository-layout-refactor to migrate one concept at a time while preserving behavior.
9. If the work needs a durable issue plan, use prd-to-issues to split follow-up work into verifiable slices.
10. Use decision-trace-writer when an important tradeoff or constraint needs to be preserved.

The value is not that the agent receives a better phrase. The value is that the work becomes inspectable, repeatable, and easier to resume later.

This repository is versioned informally through Git history. When changing a skill:

• keep the skill focused on its original engineering outcome
• update supporting notes when workflow assumptions change
• prefer concrete examples over broad advice
• remove stale instructions rather than layering exceptions
• test scripts or templates locally when they are part of the workflow
• keep skills/index.json aligned when public skill metadata changes
• run python scripts/validate_skills.py --require-denylist after changes that touch skills, docs, registry metadata, or README links
• keep private employer, customer, and project identifiers in the ignored .manifest/public-hygiene-denylist.txt, one literal identifier per line; use word:<identifier> when a short identifier needs token-boundary matching instead of normalized substring matching
• enable the repository pre-push gate with git config core.hooksPath .githooks; it scans every proposed commit rather than only the final working tree
• use python scripts/setup_public_repo.py to check the local hook and private denylist setup, or add --apply to configure the repository hook explicitly
• follow AGENTS.md and the public sanitization policy when private work informs a public skill; extract capabilities and use a clean-room public implementation instead of copying, translating, or lightly renaming private material

Treat these as examples of agent operating design rather than universal best practices. Improve reuse incrementally: preserve established public behavior, keep private source material out of the repository, independently design every new public artifact, classify current maturity, and generalize only after repeated public repository evidence supports it.