How this repo works with AI agents

The files and what they do

AGENTS.md

A “README for agents”: an open format read by many tools. It holds the commands, rules and gotchas that aren't obvious from the code. It is the only agent-context file in this repo, so there is one copy to maintain.

skills/upgrading-dependencies/SKILL.md

A skill: a step-by-step checklist for one rare, risky job. AGENTS.md points to it, so agents read it only when upgrading PyScript or text2qti. It lives in a plain skills/ folder rather than one tool's folder, so any agent can follow the link.

README.md

For humans: what the project is, how it is laid out, and how to run it. AGENTS.md links to it instead of repeating it.

CHANGELOG.md

An audit trail recording who asked for each change, what the AI built, and which decisions it made on its own.

scripts/check_examples.py

A check that any human or agent can run. It must print OK, which turns “I think it works” into a verifiable result.

Key ideas from the best-practice guides

• Be concise. An agent's context window is shared with the whole conversation. Include only what it can't work out by itself; it already knows what HTML or Git is.
• Don't duplicate. Point to the README instead of copying it. Two copies always drift apart.
• Match the freedom to the risk. Give exact rules for fragile things (license headers, pinned versions, “push only when asked”) and general direction where many approaches work.
• Give a feedback loop. A command with a clear pass/fail result lets the agent check its own work: run, fix, repeat.
• Avoid time-sensitive facts. “Use the newest version” goes stale; “pin versions, read the release notes before upgrading” doesn't.
• Use consistent terms. Pick one name for each thing (“builder page”, “guide examples”) and keep using it.
• Disclose progressively. Skills are folders of instructions an agent loads only when relevant: first just a name and description, then the body (ideally under 500 lines), then extra files on demand. This repo keeps everyday rules in AGENTS.md and puts one rare, risky workflow, dependency upgrades, in a skill that is read only when needed.
• Keep a human in charge. Agents propose and build; a person decides, reviews and publishes. The changelog makes that oversight visible.

Keeping it useful

• If an agent makes the same mistake twice, add a one-line rule.
• If a rule never matters, delete it. Shorter files get followed more reliably.
• Write rules as instructions (“Do not add npm dependencies”), not history (“we removed Tailwind”). History belongs in the changelog.

Sources: agentsmd/agents.md and Anthropic's Skill authoring best practices.