* 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.
