Agent Harness Engineering

Bootstrap or upgrade a software repository for agent-first engineering. Use when a user wants to improve project-wide development discipline around `AGENTS.m...

Security Scan

The skill's code and instructions match its stated purpose (scaffolding agent-focused docs and checks) and it does not request secrets or network access; the only notable issue is a packaging omission (template assets referenced by the script are not present in the manifest).

Purpose & Capability

The name/description (bootstrap repo for agent-first engineering) align with the included script and documentation which create AGENTS.md, docs/agent/*, and validation scripts. The operations (read/write files under a user-specified repo, create symlink, add scripts) are consistent with the stated purpose.

Instruction Scope

SKILL.md instructs the agent to inspect AGENTS.md, docs/, CI, then run the bundled Python bootstrap script with explicit flags. The instructions only refer to repo files and generated artifacts; they do not ask to read unrelated system files, environment secrets, or send data externally.

Install Mechanism

There is no install step (instruction-only) and the script runs locally with no network calls. However, bootstrap_project.py expects template files under assets/templates which are not present in the provided file manifest — this is a packaging inconsistency that will cause the script to fail at runtime unless the missing templates are supplied.

Credentials

The skill requires no environment variables, no credentials, and the script does not access environment secrets. All requested capabilities are file operations within the user-supplied repository root, which is proportionate to the purpose.

Persistence & Privilege

The skill is user-invocable and not marked always:true. It writes files into the specified repository and can overwrite files with --force, but it does not modify other skills, system-wide settings, or persist credentials. Autonomous invocation is allowed by default but does not by itself increase privileges here.

Assessment

This skill appears to do what it says: scaffold agent-readable docs and repo validation scripts and will only modify the repository path you supply. Before running it: (1) run with --dry-run to preview changes; (2) back up or run in a disposable clone of the repo so you can review diffs before committing; (3) note the script will create or overwrite files (use --force only when you intend to replace existing files) and will create a CLAUDE.md symlink to AGENTS.md unless you pass --no-claude-link; (4) the package as provided is missing the assets/templates directory the script expects — obtain or inspect the template files before running, otherwise the script will error; (5) the script does not perform network access or request credentials, and garbage-collection logic is report-only (it does not auto-delete) per the docs. If you want higher assurance, ask the publisher to provide the missing template assets and a preview of generated files for your repo layout.

Use this skill when the goal is to make a repository easier for coding agents to understand, change, and maintain over time.

This skill turns the main ideas from OpenAI's harness-engineering article into a reusable project pattern:

• AGENTS.md stays short and acts as a router
• durable knowledge moves into docs/
• context is disclosed progressively instead of dumped all at once
• quality rules become mechanical checks instead of tribal knowledge
• optional garbage collection keeps agent-generated entropy under control

When to use it

Use this skill when the user asks to:

• create a reusable engineering skill for many repos
• bootstrap a repo for agent-first or AI-assisted development
• redesign AGENTS.md so it routes to structured docs
• add repo-readable architecture, spec, quality, reliability, or security docs
• add mechanical checks for doc freshness, structure, and agent guardrails
• add a low-friction cleanup loop for drift, stale docs, and code sprawl

Choose a rollout mode

Pick the least invasive mode that still improves the repo.

• overlay: Default for existing repos. Add docs/agent/ as an agent-readable overlay without rewriting existing docs.
• full: Use for greenfield repos or when the user explicitly wants a broader doc reorganization.

For most mature repos, start with overlay.

First-use workflow

When applying this pattern to a repo for the first time, do the following in order:

1. Inspect the repo's current AGENTS.md, docs/, CI, and lint/test commands.
2. Run the bundled bootstrap script in overlay or full mode.
3. Review the generated AGENTS.md block and adapt command names to the repo.
4. Keep existing project-specific instructions, but move durable detail from AGENTS.md into the generated docs.
5. Wire the generated validation script into the repo's native check flow.
6. If the repo moves fast or uses many agents, optionally enable garbage collection.

Bootstrap command

Run the bundled script from this skill directory:

python3 scripts/bootstrap_project.py --repo /path/to/repo --mode overlay

Optional flags:

• --mode overlay|full
• --with-gc to scaffold the garbage-collection report
• --dry-run to preview changes
• --force to overwrite generated files
• --no-claude-link to skip the CLAUDE.md -> AGENTS.md symlink

What the bootstrap adds

On first application, the scaffold normally creates or updates:

• AGENTS.md with a short agent-navigation block
• CLAUDE.md symlink to AGENTS.md unless disabled
• docs/agent/index.md
• docs/agent/architecture.md
• docs/agent/specs.md
• docs/agent/plans.md
• docs/agent/quality.md
• docs/agent/reliability.md
• docs/agent/security.md
• scripts/agent_repo_check.py
• optionally docs/agent/garbage-collection.md
• optionally scripts/agent_gc_report.py

Operating rules

1. AGENTS.md is a router

Do not turn AGENTS.md into a giant handbook.

• keep it short
• link outward to durable docs
• update links when docs move
• reserve AGENTS.md for task-routing instructions and repo-specific operational constraints

2. Durable knowledge lives in docs

Put medium- and long-lived repo knowledge in docs/agent/ or the repo's main docs tree.

Examples:

• architecture boundaries
• product or integration specs
• current plans
• quality gates and invariants
• reliability expectations
• security assumptions and trust boundaries

3. Progressive disclosure beats giant prompts

Only read the docs needed for the task.

• start at docs/agent/index.md
• open the relevant leaf docs
• avoid loading unrelated docs into context
• add new docs to the index so future agents can discover them quickly

4. Mechanical checks beat soft reminders

Prefer checks that can fail fast in CI or local validation:

• missing required docs
• missing frontmatter fields
• stale review dates
• docs not linked from the index
• AGENTS.md missing navigation links

5. Garbage collection is optional but useful

Enable the GC loop when the repo has high change velocity, many generated edits, or recurring drift.

The default GC report looks for:

• stale docs
• oversized files
• suspicious filenames like final-final or v2
• lingering TODO or FIXME clusters
• docs that are not linked from the index

References to read only when needed

• Read references/bootstrap-playbook.md when planning the first rollout for a repo.
• Read references/docs-blueprint.md when adapting the doc taxonomy or frontmatter.
• Read references/quality-gates.md when wiring checks into CI or repo-native tooling.
• Read references/garbage-collection.md when enabling scheduled cleanup or review loops.

Acceptance checklist

Before you finish a rollout, confirm:

• AGENTS.md routes to docs instead of duplicating them
• docs/agent/index.md points to every active leaf doc
• the generated docs have owners and last_reviewed dates
• scripts/agent_repo_check.py passes
• the repo's native check command includes the validation script or an equivalent wrapper
• garbage collection is either enabled intentionally or documented as deferred

Do not do this

• do not rewrite a mature doc system unless the user asks
• do not duplicate the same guidance in AGENTS.md and docs/agent/*
• do not add stack-specific CI assumptions without checking the repo
• do not enable automatic destructive cleanup; GC should surface candidates, not delete code blindly