Codex Harness Skills

Three reusable Codex skills inspired by OpenAI's harness engineering ideas.

This repo packages a small, practical layer around AI-native repository setup:

• ai-repo-bootstrap: scaffold an AI-friendly repo structure.
• agent-legibility-audit: find what blocks coding agents.
• rule-to-lint: convert team rules into enforceable checks.

Social asset:

• assets/3-card-overview.png is ready to upload to X.
• assets/3-card-overview.svg is the editable source.

Why this exists

Most AI coding failures are not model failures.

They are repository failures:

• knowledge is trapped in chat, not in the repo
• rules exist, but nothing enforces them
• agents can edit code, but cannot validate or debug reliably

OpenAI's harness engineering article made that pattern explicit. This repo turns that idea into three concrete skills I can reuse in future projects.

Skills

1. AI Repo Bootstrap

Use this when a repo has no clear AI-facing structure yet.

It creates the minimum useful scaffolding:

• AGENTS.md
• ARCHITECTURE.md
• PRODUCT.md
• RULES.md
• docs/
• plans/
• tech-debt-tracker/

Example:

python3 skills/ai-repo-bootstrap/scripts/bootstrap_repo.py --repo /path/to/repo --dry-run

2. Agent Legibility Audit

Use this before an AI-heavy sprint, a hackathon, or any project where agents keep making avoidable mistakes.

It audits whether the repo is legible to coding agents across:

• discoverability
• documentation
• rule automation
• tests and validation loops
• observability
• debt tracking

Example:

python3 skills/agent-legibility-audit/scripts/audit_legibility.py --repo /path/to/repo --output /path/to/repo/docs/references/agent-legibility-report.md

3. Rule to Lint

Use this when rules only live in docs, chat, or someone's head.

It maps natural-language rules into:

• lint rules
• tests
• CI checks
• custom enforcement ideas

Example:

python3 skills/rule-to-lint/scripts/rule_to_lint_plan.py --rules-file /path/to/RULES.md --stack node --output /path/to/repo/docs/references/rule-to-lint-plan.md

Install

Clone this repo, then copy the skills into your Codex skills directory:

mkdir -p ~/.codex/skills
cp -R skills/ai-repo-bootstrap ~/.codex/skills/
cp -R skills/agent-legibility-audit ~/.codex/skills/
cp -R skills/rule-to-lint ~/.codex/skills/

If you prefer symlinks while iterating:

ln -s "$(pwd)/skills/ai-repo-bootstrap" ~/.codex/skills/ai-repo-bootstrap
ln -s "$(pwd)/skills/agent-legibility-audit" ~/.codex/skills/agent-legibility-audit
ln -s "$(pwd)/skills/rule-to-lint" ~/.codex/skills/rule-to-lint

How to trigger them

In practice, Codex can auto-trigger these skills from the description field in each SKILL.md.

For stronger first-run recall, call them explicitly once:

• $ai-repo-bootstrap
• $agent-legibility-audit
• $rule-to-lint

Repo Layout

skills/
  ai-repo-bootstrap/
  agent-legibility-audit/
  rule-to-lint/
assets/
  3-card-overview.svg

Notes

• The skills are designed to stay small and composable.
• They are not meant to replace project-specific docs, tests, or architecture rules.
• quick_validate.py from the skill creator may require PyYAML in your local Python environment.

License

MIT