agent-instructions
Agent instructions
A skill for writing the file coding agents actually read: an AGENTS.md at the repository root that tells an agent where the system's parts live, which rules apply and where each rule comes from, how to check its work, and what not to do. It links to the machine-readable files other skills produce (.ai/index/, .ai/metadata/, decision pages, token files) rather than copying them, so there is one place to keep current.
Before you begin: verify references
Confirm that every path in this skill's frontmatter references: exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example npx skills install) dropped the repo-root knowledge-notes/ directory. Tell the user to reinstall by a method in 1-INSTALL.md and run verify-install.sh from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.
Context
Agents working in a codebase read a small set of conventional files first: AGENTS.md, CLAUDE.md, .cursor/rules/, .github/copilot-instructions.md. Design system knowledge that isn't reachable from one of those is invisible at the moment it matters: the agent picks a component, types a colour, or writes a test from what it can see, and what it can see is props and values, not intent. The design system loses the argument it never got to make.
The fix is not more files in .ai/. It is one short file the agent will read, with pointers to the rest, and rules that are the team's own. Long instruction files get skimmed; unsourced rules get treated as suggestions or, worse, as policy the team never set.
Boundaries
This skill writes instructions; it doesn't build the inventory (codebase-index), the per-component metadata (metadata-schema-generator), the token docs (token-documentation) or the choosing-between pages (component-decision-tree). It links to those when they exist and names them as the next step when they don't. If the system has no components, tokens or docs to point at yet, there is nothing to instruct; say so.