name: docs description: Use for human-facing docs (README, docs/, links from AGENTS.md to docs). Auto-apply when creating/editing user or contributor docs, splitting README into docs/, or cross-linking. Not for AGENTS.md content (handled separately).

Docs

Guidance for managing this project’s human-facing documentation (README, docs/). Apply this skill when the task touches the root README.md, files under docs/, or when adding/updating links from agent instructions to the docs. Agent-only instructions (AGENTS.md) are a separate concern.

When this skill applies

• Editing or restructuring the root README.md
• Creating, updating, or reorganizing files under docs/
• Decomposing README content into docs/ (moving long content out of README)
• Writing or updating user-facing or contributor-facing documentation
• Adding or proposing links from AGENTS.md (or other agent instructions) to the human docs so agents can read them — or noting that “documentation exists in docs/” for the agent until more specific skills exist

How to manage the documentation

Goal: move content from README into docs

The root README is currently too long. When decomposing, move content into docs/ and replace or remove it in the root README — no duplication. The root README should end up lighter; the canonical, exhaustive content lives in docs/.

Root README vs docs/

• Repository root README.md — Marketing-oriented: what the product is, why use it, where to go next. Can include direct links into the documentation and a short pointer that the full docs live in docs/. Aim for a lighter, GitHub/NPM-friendly first impression.
• docs/README.md — The real main index: exhaustive index of all docs. Canonical entry point for anyone browsing the docs folder. Root README links here for “full documentation.”

Structure: one page = one folder (kebab-case) with README inside

• Prefer one topic = one folder (name in kebab-case) with a README.md inside, e.g. docs/engines/README.md, docs/custom-commands/README.md. That way each “page” is a folder and can grow (more files in that folder later) without renaming — open-clause principle.
• Use README.md (uppercase) for index files at every level. Any other file (if not using folder+README) uses kebab-case (e.g. some-topic.md). Subfolders: kebab-case.
• Per-folder README: As a default, every folder under docs/ has a README.md — GitHub renders it automatically and it gives each level a clear entry point. It can be a short index of subfolders with brief descriptions. Exceptions allowed if the user specifies; if in doubt, add the README or ask.

AGENTS.md vs human docs

This skill covers human documentation only. AGENTS.md (and other agent instruction files) are for agents/IDE — managed separately. From AGENTS.md we may link to docs/ so the agent can read human docs, or state that “documentation exists in docs/”; until there are more specific skills, that’s enough for the agent to use the docs.

Cross-linking (navigable on GitHub)

Use relative links so the documentation is navigable when browsed on GitHub. GitHub supports standard Markdown relative links; paths are relative to the current file. Examples: [Engines](engines/README.md) (sibling folder), [Configuration](../configuration/README.md) (parent-level folder), [Back to index](../README.md). Follow this convention so users can click through the docs on the GitHub UI.

Config examples and reference

• Config examples in the repo are YAML-first. The canonical full key reference is docs/config/reference.yaml — it lists every supported config key with comments linking to the relevant doc pages. The short copy-paste example is examples/hal.config.yaml.
• When adding or changing a config key: update docs/config/reference.yaml and the relevant doc page (e.g. Context, Commands, Engines, Rate limit, Logging in docs/config/) so the reference stays the single source of truth.

External links within the documentation

When documenting a part of the system (e.g. an agenting platform: config, characteristics, how to implement a model list), do research when needed. When you find relevant external resources (official docs, model lists, etc.), propose adding those links in the relevant place in the documentation — inline or in the section that topic belongs to — so users can follow them for up-to-date details (e.g. “see the official list of available models”). Links are part of the doc content, not a separate appendix.