1 commit

Author	SHA1	Message	Date
lefarcen	13ab430b45	docs: add skills contributing guide (#1035) ... * 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.	2026-05-09 15:17:45 +08:00