13ab430b45
* docs: add skills contributing guide External skill PRs are coming in faster than we can write per-PR acceptance feedback, and the existing skill section in CONTRIBUTING.md gave contributors the merge bar without showing the dev loop or the patterns we routinely close on. This adds a dedicated guide that contributors land on before opening a PR. - New docs/skills-contributing.md (the how-to): quick start, anatomy, local dev loop, merge bar checklist, PR description template, and the eight rejection patterns we've actually used recently. - CONTRIBUTING.md "Adding a new Skill" shrinks from 73 lines to ~20 and points at the new guide. Skill section was the longest in the file; trimming it keeps the four i18n variants easier to maintain. - skills/README.md is new — first thing a contributor sees when they open the skills/ folder. Routes them to the contributor guide and the protocol spec. - docs/skills-protocol.md gets a cross-link at the top so readers who land on the protocol can find the contributor flow. Discovery is the point: any path a contributor takes (CONTRIBUTING.md, skills/ folder, protocol spec) now routes to the same single guide. * docs(skills-contributing): expand modes to 7, fix broken checklist link Both flagged by review on #1035: - The mode enumeration listed 4 modes (prototype | deck | template | design-system) but apps/daemon/src/skills.ts:24 actually defines 7 (adds image | video | audio), with shipped media skills under skills/{image-poster,video-shortform,audio-jingle}. Updates every enumeration in skills-contributing.md (frontmatter cheat sheet, PR template, running-locally instructions, IS-list) and skills/README.md. - The merge-bar checklist pointed at skills/dating-web/references/ checklist.md as an example, but that path doesn't exist on this branch — dating-web ships only SKILL.md + example.html. Repointed at skills/web-prototype/references/checklist.md, which is the closest prototype-mode skill that actually ships a checklist. Adds a "Media skills (image / video / audio)" line to the references section pointing at the three shipped media skills as imitate-able starting points. * docs(skills-contributing): address review — i18n bar, external skills, daemon refresh Three findings from review on #1035: P1 — i18n merge-bar mismatch (line 172 of original) e2e/tests/localized-content.test.ts:144 enforces skills.toEqual(skillIds) for every locale, so a non-featured skill PR following the previous guidance ("no edits to apps/web/src/i18n/") would fail CI on the `skills display copy` assertion. Fix: - "Single self-contained folder" item now explicitly carves out the *_SKILL_IDS_WITH_EN_FALLBACK line as a required outside edit. - New "i18n coverage (every skill, not just featured)" subsection directs contributors to add their id to all three fallback arrays (DE / FR / RU) — bare id, no TODO comment per existing convention. - "Featured skills" subsection now describes replacing the fallback with full localized copy, instead of being the only path that touches i18n. - PR template Validation list adds the fallback-arrays step as a required checkbox for every skill PR. P2 — daemon does not auto-watch skills/ (line 139 of original) apps/daemon/src/skills.ts:2 explicitly states "No watching in this MVP — re-scans on every [/api/skills call]". Previous wording about chokidar was aspirational, not current behavior. Fix: replaced with "refresh the picker — the daemon re-scans skills/ on every /api/skills request" + restart escape hatch for parse failures. P2 — missing alternative for vendor workflows (line 60 of original) Previous "No" list pointed contributors at heavier daemon/feature paths for vendor-specific workflows, ignoring that skills-protocol.md §3 supports user-global skills via ~/.claude/skills/. Concrete cases like payment-provider and regional-marketplace skills (which we've been closing as out-of-scope) actually fit the external-bundle path. Fix: added a "Third option: ship as an external skill bundle" paragraph before the discussions CTA, linking to the protocol's discovery section.
1.6 KiB
Skills
A skill is the atomic unit of design capability in Open Design — one folder, one SKILL.md, optional assets/ and references/. The daemon scans this directory at startup; drop a folder in, restart, and the picker shows it.
Adding a new skill
→ docs/skills-contributing.md — the contributor guide. Quick start, anatomy, local dev loop, merge bar, PR template, and common rejection patterns.
→ docs/skills-protocol.md — the protocol spec. Frontmatter grammar, discovery rules, mode semantics.
The fastest path is to copy the existing skill closest to your idea, edit SKILL.md and example.html, and read the contributor guide before opening the PR. We're picky about skills because they're the user-facing surface — the merge bar is real and the contributor guide makes it explicit.
Skills that already ship
The mode and featured flags in each skill's SKILL.md decide where it shows up in the picker. The list below is a quick orientation; for a curated set of "imitate this if you're starting from scratch" skills, see the References section in docs/skills-contributing.md.
# Browse the registry from the CLI:
ls skills/
# 54+ skills across prototype, deck, template, design-system, image, video, and audio modes
License
Skills in this directory are Apache-2.0 unless their own LICENSE says otherwise. The most notable exception is skills/guizang-ppt/, bundled verbatim from op7418/guizang-ppt-skill under MIT.