docs(skills): add user-facing skill docs at docs/skills/#773
Merged
Conversation
Move user-facing skill docs from plugins/compound-engineering/skills/ce-X/README.md to docs/skills/ce-X.md, plus a new index page grouping skills by category with the four-question ideation chain at the top. Discoverability was poor with READMEs scattered inside skill source folders. docs/skills/ matches the existing docs/specs/ precedent (documentation about plugin internals, not artifacts) and lands where the docs need to be after coding-tutor leaves and the repo collapses to single-plugin — no second migration. - 23 skill READMEs moved to docs/skills/<skill>.md (lowercase, matching skill names) - docs/skills/README.md index added with chain diagram and category groupings - Cross-links rewritten: ../ce-X/ -> ./ce-X.md for documented skills; verbose source paths for skills without docs (ce-proof, ce-commit, ce-worktree, etc.) - Plugin README skills table cells now link to the corresponding doc - Plugin AGENTS.md "Skill Documentation" section updated to reflect the new location
Adds user-facing docs for skills previously listed without dedicated pages, plus an index entry and reverse cross-links from existing docs. New docs (in docs/skills/): - ce-commit — local-commit-only sibling of ce-commit-push-pr; convention detection in priority order (project instructions > recent history > conventional-commits); explicit staging (no -A); file-level logical splits - ce-clean-gone-branches — git fetch --prune + branch -vv parsing; worktree- aware cleanup; all-or-nothing confirmation - ce-worktree — .env* propagation; branch-aware mise/direnv trust (skips direnv allow on review branches); doesn't disturb main checkout - ce-setup — single diagnostic pass; multi-select install with all pre-selected; repo-local config bootstrap with gitignore handling - ce-proof — Web API + Local Bridge surfaces; HITL review mode; mutation discipline (baseToken reuse, verify-before-retry); /ops vs /edit/v2 wire format; atomic end-sync - ce-frontend-design — authority hierarchy (existing system > user > skill); Layer 0 detection, Layer 1 visual thesis pre-build; three context modules; default-against vs always-avoid distinction; visual verification cascade - ce-release-notes — tag-prefix filtering for the right component; summary vs query modes; markdown-fence-aware truncation; confidence judgment over substring matching - ce-report-bug — six-question structured intake; automatic env gathering (privacy by design); gh issue create with manual fallback Also: - docs/skills/README.md — added Frontend Design and Collaboration sections; expanded Git Workflow and Workflow Utilities with the new entries - plugins/compound-engineering/README.md — linked the 8 newly-documented skills in their respective category tables - 7 existing skill docs (ce-doc-review, ce-optimize, ce-polish-beta, ce-commit-push-pr, ce-update, ce-ideate, ce-test-browser) — converted their source-folder See Also links (../../plugins/.../ce-X/) to sibling- file form (./ce-X.md) for the now-documented skills Remaining 8 undocumented skills are intentionally without pages: internal sub-agent skills (ce-session-extract, ce-session-inventory), beta variants (ce-agent-native-audit, ce-work-beta, lfg), and specialized framework skills (ce-agent-native-architecture, ce-dhh-rails-style, ce-gemini-imagegen).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Centralize user-facing skill documentation at
docs/skills/instead of scatteredREADME.mdfiles inside each skill's source folder. This PR adds 23 skill docs plus an index page that groups skills by category with the four-question ideation chain at the top.Why this layout
Discoverability was the issue: READMEs inside
plugins/compound-engineering/skills/ce-X/README.mdaren't where someone browsing the repo on GitHub looks.docs/skills/matches the existingdocs/specs/precedent (documentation about plugin internals, not artifacts), and lands where the docs need to be aftercoding-tutorleaves and the repo collapses to single-plugin — no second migration.Lowercase filenames (
ce-ideate.md, notCE-IDEATE.md): all-caps is conventionally reserved for top-level project-meta docs (README.md,LICENSE,CHANGELOG.md), not collections of content docs. Lowercase also matches the skill names verbatim.What changed
docs/skills/<skill>.mddocs/skills/README.mdindex — chain diagram plus skills grouped into Core Workflow, Research & Context, Review & Quality, Git Workflow, Workflow Utilities, and Beta../ce-X/→./ce-X.mdfor the 23 skills with docs../ce-Y/→../../plugins/compound-engineering/skills/ce-Y/for skills without docs (ce-proof,ce-commit,ce-worktree,ce-frontend-design,ce-setup,ce-report-bug,ce-release-notes, etc.)slack:find-discussions) replaced with plain textdocs/skills/page for the 23 documented skills; the redundantFor /ce-optimize, see...line removed (the table cell now links directly)docs/skills/README.mdwhen adding a new docNotes for reviewers
ce-optimize) is tracked as a rename by git; the other 22 are new filescoding-tutoreventually leaves and the repo becomes single-plugin,docs/skills/stays put — only the relative paths inplugins/compound-engineering/README.mdsimplifyTest plan
docs/skills/README.mdrenders correctly on GitHub with all 23 skill links resolvingplugins/compound-engineering/README.mdskills table cells link to the rightdocs/skills/pathsplugins/compound-engineering/AGENTS.md"Skill Documentation" section reads correctly with the updated location and references the index page