Click the Castor logo or press Ctrl Alt T to change theme.
# Coding agent skill This package includes a `SKILL.md` file for coding agents. Use it when an agent needs to create, review, or improve documentation for a Castor Labs PHP package. The skill exists because documentation work is not only a mechanical formatting task. Castor package docs should feel like a maintainer is guiding the reader through the package with care. They should be accurate, but they should also be pleasant to read. ## What the skill emphasizes The skill asks agents to write in an educational and conversational tone. The goal is prose that flows naturally: - explain the idea before the API surface; - introduce code examples with context; - explain what matters after the example; - use lists only when they make the page easier to scan; - avoid turning every paragraph into bullet points. A good Castor guide should feel like it has a beginning, a middle, and an end. It should not feel like release notes rearranged under headings. ## When to use it Use the skill when an agent is asked to: - create `.dev/docs` for a package; - add a new guide; - rewrite an existing page; - improve examples; - review documentation tone; - check docs conventions before publishing. The skill reminds the agent how Castor Docs routing works, how navigation is configured, how local Markdown links are rewritten, how version detection works, and how related packages are generated from Composer metadata. ## The actual skill The reusable skill lives at the repository root as `SKILL.md`. Here it is in full, so you can copy it into another Castor package or review the exact guidance without leaving this page. `````markdown # Castor Docs package documentation skill Use this skill when creating or editing documentation for a Castor Labs PHP package that uses `castor-labs/docs`. ## Mission Write documentation that feels like a good maintainer is patiently guiding the reader. Castor documentation should be educational, conversational, and easy to consume. It should read like thoughtful prose, not like a checklist pasted from an issue tracker. Avoid documentation that feels bullet-proofy: endless bullets, defensive caveats, or fragmented statements with no flow. Use lists when they genuinely help scanning, but let the main explanation breathe in paragraphs. ## Source conventions Work in `.dev/docs`: ```text .dev/docs/ config.php index.md pages/ index.md guides/ configuration.md ``` - `.dev/docs/index.md` is the package landing page. - `.dev/docs/pages/index.md` is the documentation landing page. - Nested `index.md` files become section index pages. - Other Markdown files mirror their path as generated HTML routes. - Keep `.dev/docs-dist` generated and ignored. Configure navigation in `.dev/docs/config.php`: ```php <?php use Castor\Docs\Documentation; return static function (Documentation $docs): void { $docs->addComposerJsonPath(__DIR__ . '/../../composer.json'); $docs->section('Introduction', [ 'index.md', 'getting-started.md', ]); }; ``` ## Writing style Prefer a warm, direct voice: - Explain why a concept exists before listing how to use it. - Start pages with a clear promise: what will the reader understand or be able to do? - Use short paragraphs, but connect them so the page flows naturally. - Introduce code examples with context, then explain the important lines after the example. - Prefer concrete examples over abstract claims. - Say “you” when it helps the reader feel guided. Avoid: - Huge bullet lists as the primary structure of a page. - API-dump prose that merely names classes and methods. - Marketing language without examples. - Over-warning. Use callouts only when the distinction matters. - Placeholder examples that cannot plausibly happen in a real Castor package. ## Page structure A strong guide usually follows this shape: 1. A human title and a short lede. 2. A paragraph that explains the problem or context. 3. A small working example. 4. A walkthrough of what happened. 5. A few practical variations or next steps. 6. Links to related pages. Use headings as signposts. A reader should be able to skim the headings and understand the journey. ## Markdown features Castor Docs renders Markdown in the browser, then decorates it. Use normal Markdown and let the generator do the rest. Supported patterns include paragraphs, links, lists, blockquotes, tables, fenced code blocks, and GitHub-style callouts: ```md > [!TIP] > Use tips for helpful workflow improvements, not for required information. ``` Supported callout types are `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and `DANGER`. Use fenced code blocks with a language: ````md ```php <?php echo 'Hello Castor'; ``` ```` The generated page will show a language badge and apply syntax highlighting. ## Links When linking between docs pages, link to Markdown source files, not generated HTML: ```md Read the [configuration guide](configuration.html). ``` Castor Docs rewrites local Markdown links at build time, preserving anchors: ```md [Footer configuration](configuration.html#footer) ``` Do not rewrite these by hand to `.html` unless you are linking to something outside the docs source tree. ## Package metadata Package name, description, homepage, dependencies, and version information come from Composer metadata. Prefer fixing `composer.json` over hard-coding package facts in prose. The version badge is detected in this order: 1. `composer.json` `version` field. 2. Exact Git tag on `HEAD`. 3. `latest` on `main` or `master`. 4. `dev` elsewhere. Semantic versions display as a minor series, such as `1.2.x`. ## Related packages The sidebar reads Castor package metadata from the Castor Composer repository. It groups packages as dependencies, dependants, other packages, and abandoned packages. Do not manually maintain related package lists in normal docs prose unless the relationship needs explanation. ## Before finishing Run: ```bash composer docs:check ``` If you changed generator code, also run: ```bash composer test composer ci ``` Then skim the generated page visually. Check the first screen, code blocks, callouts, tables, links, search text, and previous/next navigation. Good docs are not just correct; they feel pleasant to read. ````` When copying this library's conventions to another package, copy or reference that file for coding agents that will work on the package documentation. ## How to review agent-written docs When an agent edits docs, review more than correctness. Ask: - Does the page teach the reader why the feature exists? - Does the prose flow from one idea to the next? - Are examples small but realistic? - Are callouts used sparingly? - Are links written as Markdown source links, such as `configuration.md`, rather than generated `.html` links? - Does `composer docs:check` pass? > [!TIP] > If a page feels like a wall of bullets, ask the agent to rewrite it as prose first, then reintroduce only the bullets that genuinely help scanning.
Castor ecosystem