Dg Skill Authoring

Digital Garden Skill Authoring

A meta-skill: it teaches an agent how to build another Agent Skill that adds a feature to an Obsidian Digital Garden (Eleventy) site - following the upstream-safe, progressively-disclosed pattern proven by dg-floating-tray.

The output is a spec-compliant skill folder (SKILL.md + assets/ + references/), validated with skills-ref validate, ready to drop into a skills repo or serve over MCP.

When to Use This Skill

Use when a Digital Garden user wants to package a DG customization as a reusable skill - e.g. "turn this floating dock into a skill", "make a skill for my custom callout", "write a skill another DG user can install to add a guestbook widget".

Do not use to install an existing DG skill (that's the target skill's job), or to author skills for non-DG stacks (Quartz, Astro, plain Eleventy) - the DG conventions below won't apply.

The DG Skill Pattern (what "good" looks like)

Every DG feature skill this meta-skill produces must satisfy seven invariants. These are the lessons baked into dg-floating-tray (plus inspiration citations from later skills):

1. User-owned paths only. Write into paths the DG plugin treats as user territory, so

upstream git pull never overwrites them:

• Components: src/site/_includes/components/user/common//*.njk
• Styles: append to src/site/styles/custom-style.scss
• Helpers: src/site/helpers/userUtils.js
• Notes/content: src/site/notes/**

Never edit layouts/*.njk, plugin-core components/*.njk, or _data/ internals.

1. Autoload, don't wire. DG's src/site/_data/dynamics.js globs

components/user/common//*.njk, sorts alphabetically, and injects into layout slots ({% for imp in dynamics.common. %}). To control render order use a filename prefix (zzz- = last, aaa- = first). No layout edit needed.

1. Theme via tokens, not hardcoded color. Style with DG theme variables

(--background-secondary, --background-modifier-border, --text-muted, --text-accent, --link-color, --input-shadow) so light/dark works automatically. Colors are never a knob.

1. Accessibility is not optional. Real text in aria-label, aria-hidden on icons,

role="button" + tabindex="0" + Enter/Space handlers for non-` controls, visible :focus-visible, and prefers-reduced-motion` respected.

1. Consolidate tunables. Put every safe size/shape value in one `>>> TUNING KNOBS >> TUNING KNOBS /

├── SKILL.md ├── assets/ ← drop-in files the target agent copies verbatim └── references/ ← annotated docs, loaded on demand

Copy `assets/SKILL.template.md` to `dg-/SKILL.md` and fill it in.

### 3. Write the frontmatter (spec-compliant)

Only these top-level keys validate: `name`, `description`, `license`, `compatibility`,
`metadata`, `allowed-tools`. **Nest `author`, `version`, `risk-level`, `tags` under `metadata:`**;
top-level `version`/`author` fail `skills-ref validate`. See `references/dg-mechanics.md`.

`description` is the **only field the agent reads to decide activation** - write it as a trigger:
first clause = what it does, then "Use when [X]" with concrete trigger phrases, plus a "Trigger
on: …" list of literal keywords. It's discovery metadata, not marketing.

### 4. Write the body (progressive disclosure)

Keep `SKILL.md` under ~500 lines. Structure: `When to Use` → `Inspirations` (when any prior
work informed the feature) → `Prerequisites (verify first)` → `Quick Install (agent-driven)` →
step-by-step `Instructions` → `Key Design Points` → `Risk Level` → `Reference Files` / `Assets`.
Push verbose annotated source into `references/` and link each with a read-me-when note. Assets
are drop-in files, never auto-loaded.

The **Inspirations** section is required whenever the skill is inspired by, tributes, or packages
prior public work. Ground every claim in a live public URL; name what each source contributed;
exclude private provenance. See invariant 6 and `dg-dungeon-map` / `dg-summon-cats` /
`dg-obsifetch` for models.

Include a **Prerequisites** section that verifies the target repo is actually DG+Eleventy with
the autoloader present before touching anything (see `dg-floating-tray` for the model).

### 5. Populate assets + references

- `assets/` - the exact files the target agent will copy (`.njk` component, `.scss` styles) with
  generic placeholder links/URLs the installer customizes. Put the TUNING KNOBS block on top of
  any SCSS.
- `references/` - one file per concern: annotated markup/scripts, annotated styles, a `tuning.md`
  of every knob, and a `verify.md` post-build QA checklist. Mirror `dg-floating-tray`'s set.

Before moving on, make a de-slop pass over everything you wrote (invariant 7): strip narrating
comments, defensive scaffolding, and filler prose. Assets ship verbatim into user repos, so any
slop you leave is slop every installer inherits.

### 6. Label the risk level

State an L0–L3 risk level in both the description and a `Risk Level` section. DG feature skills
that only write user-owned files with no shell/secrets/network are **L1** - say so explicitly so
installers can trust it.

### 7. Validate & package

```bash
npx skills-ref validate skills/dg-/          # pass the directory, not a file
cd .. && zip -r dg-.zip dg-   # bundled resources => zip the whole dir

SKILL.md-only skills can ship as the bare .md; anything with assets//references/ ships as a zip of the whole directory. Keep it ≤100 files / ≤70 MB. Don't ship secrets or node_modules.

8. Add to the zoo + docs (this repo's pattern)

If publishing to skills-zoo:

1. Drop the folder in skills/dg-/.
2. Add a ` block to docs/index.html` and a

docs/skills/dg-/index.html detail page (copy an existing one as a template).

1. Build the target Digital Garden and capture the feature's real rendered output in both themes.

Save 900×560 screenshots as docs/skills/dg-/preview-dark.png and preview-light.png; reference them from both pages. Never substitute generated art or a hand-built mockup for product output.

1. Add a row to the README skills table.
2. Commit + push - the Pages workflow auto-deploys docs/**.

Key Design Points

• Meta, not installer - this skill produces skills; it doesn't install features itself.
• Invariants over templates - the seven invariants above are the real product; the template

is a convenience. A skill that violates invariant 1 or 2 is broken regardless of how it looks. A skill that adapts prior work without invariant-6 citations is incomplete, and one shipped without an invariant-7 de-slop pass carries its slop into every repo that installs it.

• Verified spec facts - frontmatter rules and progressive disclosure come from the

agentskills.io spec; see references/dg-mechanics.md for citations.

Risk Level

L1 (low). Scaffolds and writes skill files into a skills directory and runs the local skills-ref validate check. No other code execution, no secrets, no network calls. Reversible via git. The skills it produces carry their own risk labels - enforce step 6.

Reference Files

• references/authoring-workflow.md - full annotated walkthrough of steps 1–8 with examples.
• references/dg-mechanics.md - DG plugin internals (autoloader, slots, theme tokens, page modes)

and the verified agentskills.io frontmatter/disclosure rules with sources.

Assets

• assets/SKILL.template.md - starter frontmatter + body skeleton for a new DG feature skill.

Validate & Package

npx skills-ref validate skills/dg-skill-authoring/
zip -rq dg-skill-authoring.zip dg-skill-authoring

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: palol
• Source: palol/skills-zoo
• License: MIT
• Homepage: http://skillz.paologabriel.com/

Install and usage instructions live in the source repository linked above.