From harness-docs
Analyze an existing codebase and generate an agent-first "system of record" docs/ directory following OpenAI's Harness Engineering pattern. Use this skill whenever the user asks to bootstrap documentation, scaffold a docs/ folder, set up AGENTS.md, make the repository more legible to coding agents (Claude Code, Codex, Cursor), or "document the architecture" of an existing project — even if they don't explicitly mention Harness Engineering. Also use when the user has an under-documented repo and wants agents to operate on it reliably. Reads the codebase and any existing markdown files first, then produces AGENTS.md + ARCHITECTURE.md + a structured docs/ tree with progressive-disclosure entry points.
How this skill is triggered — by the user, by Claude, or both
Slash command
/harness-docs:harness-docsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Generate an **agent-first documentation layout** for an existing repository, following the "repository knowledge as the system of record" pattern described in OpenAI's *Harness engineering: leveraging Codex in an agent-first world* (Feb 2026).
Generate an agent-first documentation layout for an existing repository, following the "repository knowledge as the system of record" pattern described in OpenAI's Harness engineering: leveraging Codex in an agent-first world (Feb 2026).
The output is a docs/ tree plus root-level AGENTS.md and ARCHITECTURE.md that together form a map, not an encyclopedia — agents start from a short entry point (~100 lines) and descend into deeper, verifiable documents only when needed.
Four ideas drive every decision in this skill. Internalize them before generating anything:
docs/, reached only when relevant.If a design decision in this skill seems to contradict these four, the four win.
Trigger on requests like:
Also trigger when the user shares a link to the harness engineering article and asks to apply it.
Do NOT trigger for:
The skill runs in five phases. Do them in order; don't skip ahead.
Build a mental model of what the codebase is before writing anything.
main.*, index.*, app.*, cmd/, bin/, src/, apps/, packages/, cli.*, server/router files. These reveal the runtime shape.src/ or similar that look like business domains (auth/, billing/, onboarding/, etc.) vs infrastructure concerns (db/, http/, telemetry/).Time-box this. For a medium repo, ~5–10 tool calls is enough. Don't read every file; sample.
Before writing anything new, harvest what's already there.
*.md, *.mdx, *.rst, AGENTS.md, CLAUDE.md, CONTRIBUTING.md, README*, docs/**, .github/, and any architecture/ADR folders.docs/design-docs/core-beliefs.md.Decide what to create before creating it. The canonical layout is in references/example-structure.md — read that file now. Adapt it to the repo:
AGENTS.md, ARCHITECTURE.md, docs/design-docs/index.md, docs/design-docs/core-beliefs.md, docs/exec-plans/tech-debt-tracker.md, docs/PLANS.md, docs/QUALITY_SCORE.md.docs/FRONTEND.md, docs/DESIGN.md.docs/generated/db-schema.md (with a note that it's auto-generated — leave content as a placeholder or extract from migrations/schema files if available).docs/product-specs/index.md + one spec per major flow you identified.docs/references/ with *-llms.txt placeholders for each major framework/SDK the project uses.Present the planned tree to the user in a single message before writing files. This is a checkpoint: the user may want to add, remove, or rename sections.
Now read references/file-templates.md for the content shape of each file. Key rules when filling them in:
docs/ and leave a pointer.Status: draft | verified | deprecated + Last reviewed: YYYY-MM-DD. This is what lets future lint jobs find stale docs.Write files one by one, not in a single batch. After each, briefly confirm with the user or proceed if they've said to go ahead.
The original article emphasizes that docs only work if CI enforces them. Offer the user, as a follow-up, to add any of:
.github/workflows/docs.yml (or equivalent CI job) that runs the mechanical lint on PRs touching docs/ or code referenced by docs. The companion doc-gardener skill ships a ready-made scripts/docs_lint.py that checks metadata validity, Last reviewed freshness, internal link resolution, code-fence path references, and index coverage. Don't reimplement it here — point the user at the doc-gardener skill.docs/design-docs/doc-gardening-prompt.md that an agent can be pointed at periodically to scan for drift and open fix PRs. (Essentially, a saved invocation of the doc-gardener skill.)Don't build these unprompted — they're scope creep for the initial run. Just mention them at the end.
<repo-root>/
├── AGENTS.md # ~100 lines — table of contents / map
├── ARCHITECTURE.md # Top-level map: domains × layers × providers
└── docs/
├── design-docs/
│ ├── index.md # List of all design docs w/ verification status
│ ├── core-beliefs.md # Agent-first operating principles
│ └── <topic>.md # One per significant design decision
├── exec-plans/
│ ├── active/ # In-progress plans (checked in)
│ ├── completed/ # Finished plans w/ decision logs
│ └── tech-debt-tracker.md # Known debt, versioned
├── generated/ # Auto-generated docs — header says DO NOT EDIT
│ └── db-schema.md # (if applicable)
├── product-specs/
│ ├── index.md
│ └── <flow>.md # One per major user-facing flow
├── references/ # External library refs, often *-llms.txt
│ └── <lib>-llms.txt # (one per major dependency)
├── DESIGN.md # Design-system / visual-design summary (if UI)
├── FRONTEND.md # Frontend conventions (if UI)
├── PLANS.md # Index into exec-plans/
├── PRODUCT_SENSE.md # Product principles (optional)
└── QUALITY_SCORE.md # Grades per domain × layer; tracks gaps
Details and full templates for each file are in references/file-templates.md. Read it before Phase 4.
references/example-structure.md — Annotated canonical tree with rationale for each node. Read during Phase 3.references/file-templates.md — Concrete templates for every file the skill produces, including front-matter conventions. Read during Phase 4.references/analysis-guide.md — Heuristics for extracting domains, layers, and providers from a codebase. Read during Phase 1 if the repo is large or unfamiliar.docs/ and leave a one-line pointer.FRONTEND.md. A prototype with no users doesn't need product-specs/. Omit what doesn't apply.Status: and Last reviewed: at the top. Without these, the docs rot invisibly.docs/exec-plans/active/ with no content is clutter. Either put a placeholder README.md explaining what goes there, or skip the directory until it's needed.Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Applies a firm's KYC/AML rules grid to parsed onboarding records: assigns risk rating, checks required documents, outputs rule outcomes with citations, and routes for escalation.
Generates daily or weekly digests of activity from connected sources (chat, email, docs, tasks, CRM), highlighting action items, decisions, mentions, and project updates.
npx claudepluginhub keito654/harness-docs --plugin harness-docs