opensite-ai/opensite-skills / agent-file-engine
agent-file-engine
VerifiedRepository-specific AGENTS.md authoring and maintenance workflow. Use when creating, refreshing, or expanding AGENTS.md coverage for a codebase, including deciding whether nested AGENTS.md files are needed for subsystems with distinct rules, workflows, or AI-sensitive constraints.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.0 KB |
| agents/openai.yaml | config | 402 B |
| examples/coverage-plan.md | markdown | 829 B |
| references/activation.md | markdown | 851 B |
| references/discovery-checklist.md | markdown | 1.3 KB |
| references/nested-coverage-heuristics.md | markdown | 1.5 KB |
| scripts/inventory_agent_scope.py | script | 6.4 KB |
| templates/nested-agents.md | markdown | 634 B |
| templates/root-agents.md | markdown | 1013 B |
references/nested-coverage-heuristics.md
View on GitHub# Nested Coverage Heuristics
Use nested `AGENTS.md` files sparingly and intentionally.
## Add a nested file when
- The subtree has rules that do not belong in the root file.
- Agents repeatedly need local context to avoid mistakes.
- The subtree has its own verification commands or generation scripts.
- The subtree has special contracts: JSON-only payloads, registry metadata, vector schema rules, performance budgets, auth boundaries, or migration safety rules.
- The subtree is a major subsystem with independent workflows.
## Do not add a nested file when
- The subtree just mirrors the parent rules.
- The directory is small and shallow.
- The only local guidance is naming or minor style preferences.
- The same guidance is already expressed clearly in the parent file.
## Good candidates
- `components/blocks/`
- `src/services/orchestration/`
- `app/services/ai/`
- `jobs/` or `workers/`
- `site_builder_manager/`
- `vectorization/`
- `packages/<name>/` in a monorepo when a package has special rules
## Bad candidates
- utility folders with no special workflows
- directories containing only a handful of thin wrappers
- folders where a local `README.md` already captures the necessary delta and the parent AGENTS can simply reference it
## Coverage strategy
1. Root file first.
2. Add nested files only for high-signal subtrees.
3. Keep nested files short and local.
4. Link to the nested files from the root AGENTS when they exist.
The goal is not maximum file count. The goal is maximum agent clarity per token.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |