write-agent-context-docs_skill

Overview

This skill writes, creates, and improves AGENTS.md project memory files for coding agents. It helps bootstrap new AGENTS.md, refactor existing ones toward best practices, and generate modular indexes for progressive disclosure. Use it after codebase exploration to capture discoveries and reduce future re-crawling.

How this skill works

The skill inspects the repository layout, key files, build/test commands, non-obvious architecture patterns, and any discovered conventions that agents won't infer. It produces a concise root AGENTS.md plus optional modular .docs/ files and an index list that lets agents load details on demand. When refactoring, it eliminates redundancy, groups content by scope, and recommends splitting long documents into path-scoped indexes.

When to use it

• Bootstrapping a new AGENTS.md for a repo
• Refactoring an AGENTS.md longer than ~60 lines
• After exploring code to cache discoveries and design decisions
• When documenting non-obvious conventions or tooling quirks
• To introduce a progressive-disclosure index of project-specific docs

Best practices

• Be specific and actionable; prefer concrete rules over vague guidance
• Use progressive disclosure: keep root AGENTS.md minimal and index descriptive .docs/ files
• Avoid repeating README/package.json content or standard library knowledge
• Challenge every line for token cost — only include context agents can’t infer
• When splitting, use descriptive filenames and place an index in the root or relevant subdirectory
• Flag critical, repo-wide notes early with a clear ‘IMPORTANT’ callout

Example use cases

• Create AGENTS.md describing shell dotfiles project structure and key scripts
• Refactor a bloated AGENTS.md into a short root file plus .docs/ modules for install, testing, and conventions
• After a long debugging session, add discovered service boundaries and design decisions to AGENTS.md
• Document non-standard commands, path-scoped rules, or MCP tool names for future agent sessions
• Build an index list that points to frontend/backend scoped AGENTS.md files for targeted context loading