The idocs skill

The format is plain YAML with a published schema, so an agent can write it. The idocs skill teaches an agent the format, how to set idocs 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 idocs works.

Install it

This project

npx skills add The-Package-Labs/idocs --skill idocs

Every project

npx skills add The-Package-Labs/idocs --skill idocs -g

One agent

npx skills add The-Package-Labs/idocs --skill idocs -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-idocs, or from the starter template, already contain the skill in .claude/skills/idocs, so Claude Code picks it up with no further step.

Note

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

What it knows

• Directoryskills/idocs/

  • 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 idocs 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 idocs 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 idocs 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 idocs 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/idocs/SKILL.md and its references/ folder. They are plain Markdown.