Why
A contributor following add-a-skill.md to add a private skill will be told to create hub-private/.claude/skills/<name>/SKILL.md, but hub-private/ has no .claude/ directory and scripts/setup-private.sh does not symlink one — the skill will not be discovered and the contributor will stall.
Current state
docs/playbooks/add-a-skill.md lines 152–157 say:
If the skill requires private config (endpoints, queries that reveal internal infrastructure), add it to hub-private instead: .claude/skills/ in the hub-private repo, symlinked into hub's .claude/skills/ directory. Follow the same pattern as private workflows.
The hub-private repo only contains clients/, devices/, workflows/, .env, .taplo.toml, prek.toml, and README.md. There is no .claude/skills/ directory, and scripts/setup-private.sh does not create one or symlink to it.
The same broken claim appears in two adjacent docs:
docs/architecture/private-workflows.md — "Private skills follow the same principle: skill files that reference internal endpoints or queries live in hub-private/.claude/skills/ and are symlinked individually into hub/.claude/skills/."docs/decisions/002-public-repo-private-integrations.md — diagram: hub/.claude/skills/<name>.md → symlink → hub-private/.claude/skills/<name>.md
Ideal state
- The Private skills section in
add-a-skill.md describes a location that maps to a real path in hub-private, or it is explicitly marked as "not yet supported"
docs/architecture/private-workflows.md Private skills section matches the playbookdocs/decisions/002-public-repo-private-integrations.md symlink diagram matches the playbook- A contributor following the doc cold can either complete the steps or know to skip them
Out of scope
- Actually implementing the private-skills wiring in
scripts/setup-private.sh and hub-private — that is a separate piece of work; this issue is about making the docs honest until then.
Starting points
docs/playbooks/add-a-skill.md (lines 152–157)docs/architecture/private-workflows.md (Private skills section)scripts/setup-private.sh — confirms which symlinks the script actually creates today
QA plan
- Read the updated Private skills section in
add-a-skill.md — expect either an actionable path that exists in hub-private, or an explicit "not yet supported" note pointing to this issue
- List the contents of the
hub-private repo — expect the directory layout to match what the doc claims
- Cross-read
docs/architecture/private-workflows.md Private skills section — expect identical wording on the location
- Cross-read
docs/decisions/002-public-repo-private-integrations.md symlink diagram — expect it to match the playbook (or to be marked as a planned/future state)
Done when
The Private skills section in add-a-skill.md describes a path that either exists in hub-private or is explicitly marked as not yet implemented, and the two adjacent docs say the same thing.
Why
A contributor following
add-a-skill.mdto add a private skill will be told to createhub-private/.claude/skills/<name>/SKILL.md, buthub-private/has no.claude/directory andscripts/setup-private.shdoes not symlink one — the skill will not be discovered and the contributor will stall.Current state
docs/playbooks/add-a-skill.mdlines 152–157 say:The
hub-privaterepo only containsclients/,devices/,workflows/,.env,.taplo.toml,prek.toml, andREADME.md. There is no.claude/skills/directory, andscripts/setup-private.shdoes not create one or symlink to it.The same broken claim appears in two adjacent docs:
docs/architecture/private-workflows.md— "Private skills follow the same principle: skill files that reference internal endpoints or queries live inhub-private/.claude/skills/and are symlinked individually intohub/.claude/skills/."docs/decisions/002-public-repo-private-integrations.md— diagram:hub/.claude/skills/<name>.md → symlink → hub-private/.claude/skills/<name>.mdIdeal state
add-a-skill.mddescribes a location that maps to a real path inhub-private, or it is explicitly marked as "not yet supported"docs/architecture/private-workflows.mdPrivate skills section matches the playbookdocs/decisions/002-public-repo-private-integrations.mdsymlink diagram matches the playbookOut of scope
scripts/setup-private.shandhub-private— that is a separate piece of work; this issue is about making the docs honest until then.Starting points
docs/playbooks/add-a-skill.md(lines 152–157)docs/architecture/private-workflows.md(Private skills section)scripts/setup-private.sh— confirms which symlinks the script actually creates todayQA plan
add-a-skill.md— expect either an actionable path that exists inhub-private, or an explicit "not yet supported" note pointing to this issuehub-privaterepo — expect the directory layout to match what the doc claimsdocs/architecture/private-workflows.mdPrivate skills section — expect identical wording on the locationdocs/decisions/002-public-repo-private-integrations.mdsymlink diagram — expect it to match the playbook (or to be marked as a planned/future state)Done when
The Private skills section in
add-a-skill.mddescribes a path that either exists inhub-privateor is explicitly marked as not yet implemented, and the two adjacent docs say the same thing.