Summary

Adds agent documentation at the repo root and two Claude Code skills. They build on the existing src/pages-chibi/AGENTS.md and don't repeat it.

• AGENTS.md (root): commands, architecture and conventions for any coding agent. CLAUDE.md imports it with @AGENTS.md, the same convention as src/pages-chibi/ and src/pages/.
• CLAUDE.md (root):
  • an index of the project skills;
  • a self-maintenance rule (below);
  • skill-authoring rules.
• .claude/skills/writing-chibi-integrations/:
  • workflows for adding, fixing and reviewing chibi pages;
  • reference on runtime semantics, lifecycle internals, page options (requestProxy, customDomains, urls.player, computedType, readerConfig, minimumVersion), engine internals, how test:headless compares each field, and the full ChibiDev API.
• .claude/skills/running-malsync-locally/:
  • setup, the dev loop (including npm run chibi and the MCP port), and reproducing each CI job locally;
  • reference for all npm scripts, build outputs, env vars, testing and troubleshooting.
• src/pages-chibi/AGENTS.md: the node/npm requirement now matches package.json (>= 24 / >= 11 instead of 22.12 / 8).

Why skills in the root .claude/skills/

src/pages-chibi/AGENTS.md is the right place for page-author rules, but it loads only when an agent works inside src/pages-chibi/, and it has to stay short. Plenty of work starts elsewhere: a user pastes a site URL, a test fails in CI, the build breaks on Windows, a reviewer looks at a chibi PR. Some knowledge also doesn't fit a rules file, such as why a chain returned 0, how trigger() resets state, or which fields the headless runner compares.

Skills in the root .claude/skills/ solve this:

• Always discoverable, cheap until used. Claude Code loads only each skill's one-line description into context and opens the skill when a task matches, from anywhere in the repo. The detailed material costs no context until it's needed.
• Progressive disclosure instead of one long file. Each SKILL.md is a short router (~40 lines). A task table lists exactly which files to read for each task, always starting with the relevant AGENTS.md, so related information isn't missed. The details live in single-topic files under 75 lines each. An agent fixing a page reads the fixing workflow, runtime semantics and lifecycle, not the CI or engine docs. This follows Anthropic's skill-authoring guidance: SKILL.md well under 500 lines, references one level deep, one topic per file. It also keeps the hub well within the first 5,000 tokens of each skill, which is what Claude Code keeps after context compaction.
• Layered, not duplicated. AGENTS.md stays authoritative for rules and conventions, and the generated src/chibiScript/FUNCTIONS.md stays the function reference. The skills route to them and add only what they don't cover. If they disagree, the code and AGENTS.md win.
• Shared with the team. Living in the repo, the skills are versioned and reviewed like code, and every contributor using Claude Code gets the same behaviour.

Self-maintenance

CLAUDE.md tells Claude to check, in every commit or PR it creates or updates (including PRs unrelated to agent docs), whether the change makes anything in CLAUDE.md, an AGENTS.md or a skill outdated. If it does, Claude fixes it in the same PR. A "Sources it documents" column maps code paths to skills, so the check is mechanical. This PR applies the rule once: the src/pages-chibi/AGENTS.md version fix.

Verification

• Every repo path, npm script, env var and ChibiScript function mentioned exists on current master. Function names were checked against a freshly generated FUNCTIONS.md. Build-only outputs (dist/…, test/dist/…) were checked against the webpack configs and CLI source.
• Behavioural claims (consumer error handling, ChibiParam resolution, and/or values, lifecycle, loader merge, headless comparison) were checked against ChibiConsumer.ts, ChibiCtx.ts, ChibiProxy.ts, ChibiListRepository.ts, test/headless/test.js and test/chibiDev/runtime.ts.
• Docs only. No runtime code changes.

🤖 Generated with Claude Code