Agent File Engine

Skill Resources

• Activation and cross-agent notes: references/activation.md
• Use ultrathink or the deepest available reasoning mode before deciding AGENTS.md boundaries for large or safety-critical repos.
• Reference: references/discovery-checklist.md
• Reference: references/nested-coverage-heuristics.md
• Template: templates/root-agents.md
• Template: templates/nested-agents.md
• Example: examples/coverage-plan.md
• Helper: scripts/inventory_agent_scope.py

Task Focus for $ARGUMENTS

When this skill is invoked explicitly, treat $ARGUMENTS as the repo root or subtree that needs AGENTS.md coverage.

Purpose

Use this skill to create or update AGENTS.md files that help AI coding agents navigate a repository safely, quickly, and consistently.

The output should be specific to the target codebase. Avoid generic “best practices” prose unless it is tied directly to the repo’s structure, build system, workflows, or risk areas.

Scope Model

• A root AGENTS.md applies to the entire repository subtree beneath it.
• A nested AGENTS.md applies only to the subtree rooted at its directory.
• More deeply nested AGENTS.md files override parent instructions when they conflict.
• Nested files should add local delta rules, not restate the entire parent document.

This precedence model matters. Only add nested files when a subtree genuinely needs instructions that differ from or go beyond the parent.

Workflow

1. Resolve the target repository.

   • Use the current working directory unless $ARGUMENTS points to another repo root or subtree.
   • If the request targets a nested path, still inspect the repo root before writing a local file.

2. Inventory the repository before writing anything.

   • Run scripts/inventory_agent_scope.py <repo-path> first.
   • Read existing AGENTS.md files, top-level manifests, README/docs, CI config, and a representative sample of core code paths.

3. Build a mental model of the codebase.

   • Identify the primary languages, frameworks, package managers, and test/lint/build commands.
   • Identify the risk areas: auth, data access, AI integrations, performance-sensitive code, design systems, deployment paths, migrations, and background jobs.
   • Identify whether the repo is a library, an app, a monorepo, or a mixed workspace.

4. Decide the AGENTS.md coverage plan.

   • Always evaluate root coverage first.
   • Add nested files only when a subtree has distinct invariants, workflows, or verification steps that would otherwise clutter the root file.
   • Prefer a small number of high-signal nested files over broad recursive coverage.

5. Create or update the root AGENTS.md.

   • The root file should explain the overall architecture, golden rules, key directories, common workflows, and minimum verification commands.
   • It should also point agents to nested AGENTS.md files when they exist.

6. Create or update nested AGENTS.md files only where warranted.

   • Scope them tightly to the subtree.
   • Make them more specific than the parent.
   • Focus on local conventions, contracts, performance constraints, serialization rules, integration rules, and test commands.

7. Validate the result.

   • Ensure every referenced path or doc exists.
   • Ensure parent and child files do not contradict each other.
   • Keep the files concrete: real paths, real commands, real workflows.

Root AGENTS.md Requirements

The root file should usually contain:

• A one-paragraph mental model of the repo
• Golden rules that are non-obvious and high-signal
• Key directories and why they matter
• Common agent workflows
• Verification commands
• Notes about nested AGENTS.md files, if present

Keep it specific. “Run tests” is weak. “Run pnpm test and pnpm type-check” is useful.

Nested AGENTS.md Requirements

A nested file is justified when the subtree has at least one of these:

• Distinct serialization or API contracts
• Different build or verification commands
• Specialized architecture or domain constraints
• High-risk performance, security, or AI workflows
• Strong local patterns that agents repeatedly get wrong

Examples from your codebases:

• components/blocks/* in @opensite/ui needs block-specific serialization, registry, and design-system rules.
• src/services/orchestration/* in octane needs workflow-step, memory, and side-effect boundaries.
• app/services/ai/* in Rails repos needs webhook, vector, and processor-specific rules.

Do not create nested files for shallow folders that add no new information.

Writing Rules

• Prefer imperative, testable guidance.
• Use real file paths and command names.
• Call out forbidden changes explicitly when they matter.
• Keep parent files broad and nested files local.
• Avoid organizational lore that cannot be verified from the repo.
• If the repo already has strong AGENTS.md files, preserve the tone and structure unless they are clearly inconsistent or stale.

Quality Bar

Before finishing, confirm:

• The root file reflects the actual repo, not a template
• Nested files exist only where they improve agent outcomes
• Commands and referenced docs exist
• The file set gives agents enough context to work without reading the whole repo every time