The docspp skill

The format is plain YAML with a published schema, so an agent can write it. The docspp skill teaches an agent the format, how to set docspp up, how to write good scenarios, and the check-and-look loop that keeps the result honest. An agent with the skill can draw your architecture from your code without being told how docspp works.

Install it

This project

npx skills add AhmeddBasemm/docspp --skill docspp

Every project

npx skills add AhmeddBasemm/docspp --skill docspp -g

One agent

npx skills add AhmeddBasemm/docspp --skill docspp -a claude-code

This uses the skills installer, so it works with Claude Code, Cursor, GitHub Copilot, Gemini and the other agents the installer supports. Add --copy to copy the files instead of linking them.

Projects made with create-docspp, or from the starter template, already contain the skill in .claude/skills/docspp, so Claude Code picks it up with no further step.

Note

The installer reads the skill from the docspp repository on GitHub. Nothing has to be published to a registry.

What it knows

• Directoryskills/docspp/

  • SKILL.md the workflow, the format at a glance and the conventions
  • Directoryreferences/

    • format.md every field of nodes, groups, edges and views
    • scenarios.md steps, phases, lanes and the story view
    • layout.md which hint fixes which problem
    • setup.md creating or extending a site, and publishing
    • troubleshooting.md what each error means
  • assets/examples/shop.diagram.yaml a complete example, compiled in the tests

• Setting up. Creating a site, or adding docspp to an existing Astro and Starlight one, and publishing to GitHub Pages.
• The format. Nodes, groups, edges, views, kinds and icons, and every field they accept.
• Scenarios and stories. Steps, phases, parallel steps, routes, lookups, the swimlane story view, and how to write ones worth reading.
• Layout. Which hint fixes which problem, so the agent changes the model instead of fighting the picture.
• Troubleshooting. What every error from docspp check means, and the YAML mistakes that cause most of them.

It stays accurate

The skill is checked against the code. A test compiles the example diagram, resolves every link, and compares the node, edge and step kinds, the schema fields and the CLI commands the skill describes with what the code actually accepts. Change the format and the test says which part of the skill to update, so the skill cannot quietly fall behind.

The conventions it follows

The skill asks the agent to:

• Read the code first and never invent components, ports, routes or flows.
• Cite sources with refs: so readers can find the code and docspp check can warn when it moves.
• Pick a scope: one diagram answers one question, with 8 to 25 nodes. A larger system becomes a second view, not a second diagram.
• Name things the way people do, and put technical detail in sub.
• Mark unbuilt work with status: planned, never only in prose.
• Write one story per scenario, with a one-sentence summary, and show failures as their own scenarios.
• Finish with docspp check --strict and look at the rendered page.

Working with an agent shows the loop in practice.

Using another assistant

Any assistant that can read files can use the same material. Point it at skills/docspp/SKILL.md and its references/ folder. They are plain Markdown.