Umbraco Skill Author

Umbraco Skill Author

A framework, checklist, and guide for building Umbraco skills. Follow it to go from an idea to a shippable skill that matches the house conventions, then self-audit before handing off.

The shape of every skill: a thin SKILL.md that routes, detail in references/, code templates in assets/, deterministic helpers in scripts/, and objective assertions in evals/evals.json.

Golden-standard example: umbraco-sitemap is the current reference skill. When in doubt, open it and copy its shape.

How to use this

1. Build — walk references/authoring-steps.md: scope → scaffold → SKILL.md → references → assets → evals. Copy-paste skeletons are in templates/skill-template.md.
2. Prove it runs — if the skill ships assets/*.cs, add it to the dotnet test gate: references/runtime-validation.md.
3. Audit — before shipping, self-check against references/conformance-checklist.md.
4. Hand off — pass the finished skill to umbraco-skill-evaluator to run with-skill vs. baseline and prove it earns its keep, then iterate from the results.

Steps 2 and 4 answer different questions and neither covers for the other: the gate proves the code compiles and serves, the evals grade whether Claude writes it. A skill can pass one and fail the other.

Core principles (what the checklist enforces)

• Thin SKILL.md. It routes; it doesn't teach everything. Push detail, per-approach steps, and if/else-style branching into references/ or assets/ — separate files, not inline.
• Docs are the source of truth. Don't reproduce Umbraco API code from memory; link the docs and tell the agent to fetch them first. Ship verbatim code in assets/ only when it's genuinely not in the docs (and say so).
• .md doc links. Fetch-me doc links point at the .md page (e.g. .../composing.md), or link a sibling skill instead of raw docs — the .md endpoint is what the agent can actually fetch as source, and a sibling-skill link keeps discovery progressive (lazy-loading) rather than dumping everything up front.
• Don't duplicate. A doc link in a reference file isn't repeated in SKILL.md — a fact stated in two places drifts out of sync, and the copy the agent reads is then a coin toss.
• Prefer a script over prose for deterministic work. If a step is a fixed, repeatable operation (scaffolding, validation, a lint check), bundle it in scripts/ and point at it, rather than asking the agent to re-derive it every run. This is also what lets the conformance checklist be enforced by a deterministic CI check on the PR, not just a self-audit.
• Build honesty. Never claim a verified build you didn't run.
• Right place. content-modelling → plugins/content-modelling/skills/; build-out/delivery → plugins/implementation/skills/; authoring tooling → .claude/skills/.