# Umbraco Skill Author

> A framework for authoring Umbraco skills in THIS marketplace: how to structure, scaffold, write, and audit a skill so it matches the house conventions. Use this whenever the user wants to start or build a new skill for the Umbraco marketplace, e.g. "make a new skill for X", "how should I structure this skill", "turn these docs into a skill", "scaffold a skill", or "get this skill ready to ship". Ends with a self-audit checklist, then hands off to `umbraco-skill-evaluator` for the eval loop — this skill covers authoring, not evaluation. SKIP: non-skill work, and general skill-building unrelated to this Umbraco marketplace (use the generic skill-creator for those).

- Skill: `umbraco/umbraco-skill-author` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add umbraco/umbraco-skill-author`
- Raw SKILL.md: https://api.skillmd.com/api/skills/umbraco/umbraco-skill-author/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: umbraco (https://skillmd.com/u/umbraco)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/umbraco/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`](../../../plugins/implementation/skills/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`](references/authoring-steps.md): scope →
   scaffold → SKILL.md → references → assets → evals. Copy-paste skeletons are in
   [`templates/skill-template.md`](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`](references/runtime-validation.md).
3. **Audit** — before shipping, self-check against
   [`references/conformance-checklist.md`](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/`.