xy-agent
Agent Documentation Conventions
Authority. This skill is maintained only in ariestools/ariestools-skills; edit there, not in installed copies.
Skill identity. When you present a plan, an acknowledgement, or a completion summary, state which skills informed it as xy-agent v<version>, and list each other active skill from this pack the same way. Read the version from this file's metadata.version, never from an example.
This skill defines how a repository tells an agent what is true. It covers one entry point (AGENTS.md), thin per-tool adapters, and a documentation tree whose folders encode lifecycle rather than topic — so that a document's age, authority, and supersession are readable without opening it.
Read the repository's own AGENTS.md first. It is authoritative for that repository. This skill describes the shape those files should take; it never overrides what a specific repository says about itself.
Toolchain enforcement. The stable pnpm xy agent lint checks this convention in AGENTS.md, the adapters, and the documents under docs/, papers/ and specs/. xy check runs it only where a root AGENTS.md exists or the xy config declares commands.agentLint, and only two findings are errors by default: a missing AGENTS.md and a broken link in it. The rest — a missing required section, an adapter that does not lead with the import, a home-directory path, a docs/README.md that differs from the generated index — warn, and fail the gate only under --strict or XY_STRICT=1; --rules lists every rule and its level. The experimental pnpm xyex plan lint is an opt-in layout overlay: it is not part of xy check, it is not authoritative here, and it conflicts with agent lint on a symlinked CLAUDE.md and on docs/README.md. Never run xyex plan lint --fix without the owner's agreement: it moves product-named papers into notes/ and prepends the @AGENTS.md import to an existing CLAUDE.md. After an agreed run, re-run pnpm xy agent lint.
The rule this exists to enforce: an instruction file is only useful while it is true. Every convention below exists to make untruth detectable — by a linter, by an audit, or by an agent that reads a status column and stops.
This skill builds on the xy-development skill; the xy agent and xy work commands it relies on are documented in the xy-toolchain skill. A repository that has not adopted this pattern still passes xy check: with no AGENTS.md, agent lint is skipped. Do not convert it mid-task, and do not declare commands.agentLint in xy.config.ts to quiet it — declaring the key, even only to turn rules off, opts xy check into agent lint. With the owner's agreement, adopt the pattern (pnpm xy agent init scaffolds the missing files). Without xy agent, follow whatever convention the repository already uses.
Toolchain versions. Verified against @ariestools/toolchain 11.0.2. Agent-lint behavior remains as described below; work tracking is GitHub-only from 10.3.1 and stable as xy work from 11.0.2. --json uses the envelope described in the xy-toolchain skill. xy agent exists from 10.1.1. 10.1.5 adds --fix repairs for adapters and for front matter without a kind, and the experimental --fix-interactive; the text marks both. 10.2.0 reworks agent lint, and the rule details describe it: it reads Markdown and front matter as renderers do, skips files .gitignore excludes, keeps hand-written text in docs/README.md, and runs on the repository root from a package folder. On 10.1.2 through 10.1.5, read Toolchain 10.1.5 and earlier before trusting a result or running a fixer: rules report false findings there, and --fix can overwrite a hand-written index or erase the instructions. On 10.1.1, also read Toolchain 10.1.1: more rules fail the gate there, and two of its fixers damage files. A command the installed toolchain lacks prints Command not found, and before 10.1.2 it exits 0, which reads like a pass: check pnpm xy --help, and without xy agent run the checks by hand. The 10.1.2 and 10.2.0 rows of the xy-toolchain skill's Version notes list every change from 10.1.1 and from 10.1.5.