dg-skill-authoring

A meta-skill: how to build a new Digital Garden skill.

L1 · low risk v1.1 MIT meta-skill digital-garden

This one doesn't add a feature to your site - it teaches your agent how to author another skill that does. Hand it a Digital Garden customization (a component, widget, style, layout tweak) and it produces a spec-compliant, upstream-safe SKILL.md package that any other DG user's agent can install - following the exact pattern behind this zoo.

It's the pattern, packaged. Everything learned building dg-floating-tray - user-owned paths, autoloading, theme tokens, accessibility, consolidated tuning knobs - encoded as reusable authoring guidance.

How to use it

Copy the skill folder into your agent's skills directory, then in your skills repo ask:

git clone https://github.com/palol/skills-zoo.git
cp -r skills-zoo/skills/dg-skill-authoring ~/.claude/skills/

(or ~/.agents/skills/)

Use the dg-skill-authoring skill to turn this custom callout box into a reusable Digital Garden skill. Scope it, scaffold the folder, write spec-compliant frontmatter, and validate it.

It walks through scoping → scaffolding → frontmatter → body → assets/references → risk label → skills-ref validate → publishing to the zoo.

The seven DG invariants

Every skill it produces must satisfy these - the real product of the meta-skill:

User-owned paths only. Write into components/user/common/<slot>/, styles/custom-style.scss, helpers/userUtils.js, notes/ - never core layouts. Survives upstream git pull.
Autoload, don't wire. DG's dynamics.js globs the slot folder and sorts alphabetically; a filename prefix (zzz-/aaa-) controls render order. No layout edit.
Theme via tokens. Style with DG variables (--background-secondary, --text-accent, …) so light/dark work automatically. Colors are never a knob.
Accessibility is not optional. Real text in aria-label, icons aria-hidden, keyboard-operable controls, visible focus, reduced-motion respected.
Consolidate tunables. One >>> TUNING KNOBS <<< :root block; derive everything from it.
Cite inspirations with real sources. Any skill informed by prior work carries an Inspirations section with public URLs stating what each source inspired or supplied. No private provenance.
Apply de-slop style. No narrating comments, defensive scaffolding, or filler prose in assets or docs - every line either does something or informs the installing agent. Slop in a skill is slop in every repo that installs it.

If a feature can't respect invariants 1–2 (needs a core/layout edit), the skill scopes it down or stops - it won't ship something that breaks on update.

Spec correctness, baked in

It enforces the agentskills.io rules that informal examples get wrong:

Only name, description, license, compatibility, metadata, allowed-tools validate at top level - version/author/risk-level nest under metadata:.
description written as a trigger condition (what it does + "Use when…" + literal trigger phrases) - it's the only field the agent reads to activate.
Progressive disclosure: lean SKILL.md body, verbose detail in references/, drop-in files in assets/.
Validate with npx skills-ref validate <dir>/; package bundled skills as a zip of the whole directory.

What's in the box

SKILL.md - the meta-skill: invariants + 8-step authoring workflow
assets/SKILL.template.md - starter frontmatter + body skeleton
references/dg-mechanics.md - DG plugin internals + verified spec rules
references/authoring-workflow.md - annotated walkthrough + ship-gate checklist

Prerequisites

An agent that supports the Agent Skills format and can run skills-ref validate.
A target Digital Garden repo (oleeskild plugin + Eleventy) the produced skill will apply to.

Scope is Digital Garden only - the invariants encode DG conventions (autoloader, theme tokens, user-owned paths), not Quartz/Astro/plain-Eleventy.

Browse the full source on GitHub →