| name | ai-context-engineering-files |
| description | Creates, updates, or evaluates AGENTS.md and CLAUDE.md files for a repository. This skill activates when users want to create onboarding docs, update agent context files, or evaluate documentation quality. Generates docs with YAML frontmatter indexes for machine-readable progressive disclosure, system invariants, redirect-pattern gotchas (DO/NOT/BECAUSE), and validated commands. Supports incremental updates via git-based staleness detection.
|
Produce and maintain high-signal agent onboarding memory files —
AGENTS.md (cross-tool, open format) and CLAUDE.md (Claude Code context file,
symlinked to AGENTS.md).
Core Principles
- Stateless onboarding: zero prior knowledge assumed; files onboard future sessions.
- Less is more: root files under 150 lines; hard stop at ~300.
- WHY / WHAT / HOW: every file follows this structure.
- Frontmatter-first: YAML frontmatter with
id, title, description, index[] on content docs. AGENTS.md routing indexes are exempt. See resources/frontmatter-index-spec.md.
- No fast-changing specifics: no test counts, timing data, file counts, or numbers that go stale.
- Audience filter: apply the actor test — agent does it → AGENTS.md; human does it →
docs/.
- Existing docs first: read and classify before modifying. Migrate accurate content forward; keep unverifiable in place.
- Migrate then remove: no deletions until content is classified and accounted for.
- Progressive disclosure: AGENTS.md routes;
docs/ provides depth; nested AGENTS.md for modules.
- Intent-first taxonomy: classify docs by type (tutorial, how-to, explanation, reference).
- Validate what you claim: confirm commands exist; mark ✅/⚠️/⏸️.
- Deterministic validation: run
scripts/validate_frontmatter.py and scripts/verify_references.py.
- Gotchas redirect: DO X, NOT Y, BECAUSE Z.
- Invariants are high-stakes: only discoverable from code/CI. Mark unverified with
REVIEW:.
Full principles with rationale: references/principles.md
Security/ops guardrails:
- Never write secrets into generated files.
- Do not run destructive shell commands.
- Prefer offline, unit-level validation; avoid networked/E2E commands unless explicitly asked.
Inputs
RAW ARGUMENTS: $ARGUMENTS
If $ARGUMENTS contains --help or is exactly help, print a usage guide without modifying the repo.
Parsing
- Extract flags:
--help, --agents, --claude, --both (default: --both)
- Parse remaining as:
[mode] [scope...] (scope can be space/comma separated)
- Defaults: mode=
auto, scope=.
Modes
quick-start: Create from scratch. Ask if scope is ambiguous (monorepo signals). Offer CLAUDE.md consolidation if standalone CLAUDE.md exists.
update: Incremental by default. Run scripts/check_staleness.py to assess what changed. Only update affected sections. Load references/incremental-update-workflow.md for the full algorithm. Falls back to full scan if docs are severely stale or malformed.
evaluate: Everything in update, plus evaluate against principles above and propose/apply improvements.
auto (default): No docs → quick-start. Has docs → update + evaluate. Zero user input. Smart defaults for everything. Automatic CLAUDE.md consolidation, nested doc creation, docs/ generation for cross-cutting topics. Suitable for CI and background jobs.
Execution Plan
1. Determine Root and Scope
- Git root is the anchor (or provided scope directory).
- Detect monorepo signals (workspaces, multiple manifests).
- In auto mode: infer scope from
git status / git diff --name-only if not provided.
- Cross-cutting system scope: when the user provides a system name + multiple code paths (e.g., "ML Inference Pipeline" spanning
ml/training/, services/triton/, api/routes/inference.py), docs live alongside the primary module. See references/docs-structure.md Scale D for details.
- Scope guardrail: respect explicit scope — don't create docs in parent/sibling dirs.
- For update mode: run
scripts/check_staleness.py on existing AGENTS.md.
2. Discover Authoritative Context
Read (minimal, targeted): README, build/test/lint configs, package manifests, Makefile/Taskfile, CI workflows, repo layout.
2b. Discover and Classify Pre-Existing Documentation
Run this before writing any new files. Load references/existing-docs-migration-workflow.md for the full algorithm.
- Find non-standard doc directories (
ai_agent_docs/, agent-docs/, context/, llm-docs/)
- Find existing
docs/*.md files without skill-generated YAML frontmatter
- Read every file found — do not skip based on filename or apparent size
- Classify each file's content: Architectural (→
docs/), Module Operational (→ nested AGENTS.md), Fast-Changing (discard), or Unverifiable (keep in place)
- Verify accuracy of Architectural and Module Operational content (path checks, command existence)
- Build a migration manifest: source → destination for every piece of content
- Only proceed to Step 4 after the manifest is complete
Unverifiable content: if content cannot be confirmed without running E2E or networked operations, keep it at its current path. Do not delete it. Flag it in the Step 6 report with reason.
Scope boundary: This step classifies pre-existing content to inform routing tables
and AGENTS.md updates. Actual file moves, docs/ restructuring, and index creation in
docs/ are owned by the docs-workflow skill. If running both skills, defer docs/ file
operations to docs-workflow. If running context-engineering alone, execute the
migration inline.
3. Derive Commands
Typical buckets: install/bootstrap, dev server, test, lint/format, typecheck, build.
Validate each command. For test commands: attempt minimal safe fast execution.
See resources/generated-doc-spec.md for detailed validation rules.
4. Write or Update Files
Follow resources/generated-doc-spec.md for the exact output structure.
All generated docs/*.md content files get frontmatter per resources/frontmatter-index-spec.md. AGENTS.md files do not get frontmatter.
Frontmatter rule — applies to created AND updated docs/*.md content files:
- If you create a new docs/ content file: add frontmatter.
- If you update an existing docs/ content file: check if frontmatter exists. If missing, add it.
- "I didn't create it" is not an excuse — if you touched it, it gets frontmatter.
- Exception — AGENTS.md files at any level are routing indexes, not content docs. They do not get frontmatter. Agents auto-discover AGENTS.md by convention; frontmatter adds no routing value.
Intent classification: when creating docs/ files, classify each by type (tutorial, how-to, explanation, reference) using the intent classification in references/docs-structure.md. Place into intent folders per the structure rules (folders from the start → sub-indexes when a folder hits 8+).
Docs index generation: when creating or updating docs/ files, also create/update docs/README.md (human progression index) and docs/AGENTS.md (agent routing index). See references/docs-structure.md for index specs.
File strategy:
- AGENTS.md is canonical. CLAUDE.md is a symlink.
- For update mode: use diff-based editing per
references/incremental-update-workflow.md.
- Auto mode creates: nested AGENTS.md for modules with distinct workflows,
docs/ files for cross-cutting topics, docs/architecture.md for repos with 3+ modules (template in resources/architecture-doc-template.md).
- For monorepos: generate cross-module dependency map per
references/cross-module-dependency-map.md.
5. Validate
Run validation scripts, passing the git root as scope. The scripts automatically
exclude _archive/, archive/, .git, .venv, node_modules, __pycache__, and
vendored plugin docs (config/{tool}/plugins/*/docs/).
scripts/validate_frontmatter.py {git_root}
scripts/verify_references.py {git_root}
Expected false positives to ignore in the report:
_archive/ files: intentionally archived docs for a different repo/context- Files you did not create or modify in this run (pre-existing broken refs are not your responsibility)
When reporting validation results, distinguish between:
- New failures: broken refs in files you created/modified this run → fix before finishing
- Pre-existing failures: broken refs in unmodified files → report as-is, do not fix
In evaluate/auto mode: also apply rubric (conciseness, correctness, progressive disclosure quality). Specifically check that docs/AGENTS.md (if it exists) has YAML frontmatter and uses the intent-typed table format specified in resources/generated-doc-spec.md. If it predates the skill and lacks frontmatter or uses a different structure, flag it for update.
6. Report
Output in chat:
- Files created/updated (paths)
- Key changes (bullets)
- Validation log (commands + ✅/⚠️/⏸️)
- Symlink status (✅ exists / ⚠️ created / missing)
- Script results (frontmatter validation, reference checks)
- Pre-existing docs inventory (from Step 2b):
- Files read (paths + line counts)
- Migrated: source → destination for each file
- Kept in place: path + reason (unverifiable / partially verified)
- Discarded: path + reason + summary of what was in it
- Source dirs/files removed only after all content accounted for
- Remaining unknowns or follow-ups
Do NOT paste full file contents unless asked.
Scripts
Deterministic validation tools in scripts/:
| Script | When to run | What it does |
|---|
validate_frontmatter.py {path} | After generating/updating docs | Checks frontmatter fields, unique ids, heading correspondence |
check_staleness.py {agents-md} | Start of update mode | Git-based staleness assessment, outputs JSON recommendation |
verify_references.py {path} | After generating/updating docs | Confirms all backtick paths and routing table entries exist |
Bundled Content
Load only what the current step requires:
Resources (specs and templates for output):
References (guides and workflows):
Now Execute
Proceed in the parsed mode using the scope rules above.
