Repo skills/ directory isn't invocable via Claude Code's Skill tool #48

New issue

Closed

opened 2026-07-23 23:22:58 +02:00 by cloudbot · 0 comments

cloudbot commented

2026-07-23 23:22:58 +02:00

Collaborator

Typing `/start-issue` (or asking Claude to "start issue N") fails with
`Unknown skill: start-issue`, even though `skills/start-issue/SKILL.md`
exists at the repo root and is the documented entry point in
`AGENTS.md`'s skill table.

Root cause

Claude Code's `Skill` tool only auto-registers skills it discovers in
specific locations (e.g. `.claude/skills/`) — this repo has no
`.claude/skills/` directory. The `skills/` folder here (`start-issue`,
`close-issue`, `create-issue`, `forgejo-interaction`, `design-system`)
was scaffolded by the `project-init` skill as plain markdown files meant
to be read per the AGENTS.md workflow instructions, not registered as
slash-invocable skills. That's a reasonable design, but it means a very
natural user action — typing `/start-issue 23` or "start 23" — fails
with a confusing tool error instead of working, or instead of a clear
fallback.

Fix options to weigh

Mirror or symlink `skills/*` into `.claude/skills/` so they're
directly invocable, keeping the repo-root copies as the
human-readable/portable source of truth.
Leave the two-tier design as-is, but document clearly (in AGENTS.md
and/or a top-level note) that these are not slash commands — they're
read manually as part of the start-issue/close-issue workflow — so
users don't expect `/start-issue` to work.
Update `project-init` itself to scaffold future projects with skills
living directly under `.claude/skills/` instead of a repo-root
`skills/` folder, if there's no strong reason for the split.

Discovered while starting work on #23: "start 23" failed with `Unknown
skill: start-issue`, worked around by reading and following
`skills/start-issue/SKILL.md` manually instead.

Typing \`/start-issue\` (or asking Claude to \"start issue N\") fails with \`Unknown skill: start-issue\`, even though \`skills/start-issue/SKILL.md\` exists at the repo root and is the documented entry point in \`AGENTS.md\`'s skill table. ## Root cause Claude Code's \`Skill\` tool only auto-registers skills it discovers in specific locations (e.g. \`.claude/skills/\`) — this repo has no \`.claude/skills/\` directory. The \`skills/\` folder here (\`start-issue\`, \`close-issue\`, \`create-issue\`, \`forgejo-interaction\`, \`design-system\`) was scaffolded by the \`project-init\` skill as plain markdown files meant to be *read* per the AGENTS.md workflow instructions, not registered as slash-invocable skills. That's a reasonable design, but it means a very natural user action — typing \`/start-issue 23\` or \"start 23\" — fails with a confusing tool error instead of working, or instead of a clear fallback. ## Fix options to weigh 1. Mirror or symlink \`skills/*\` into \`.claude/skills/\` so they're directly invocable, keeping the repo-root copies as the human-readable/portable source of truth. 2. Leave the two-tier design as-is, but document clearly (in AGENTS.md and/or a top-level note) that these are *not* slash commands — they're read manually as part of the start-issue/close-issue workflow — so users don't expect \`/start-issue\` to work. 3. Update \`project-init\` itself to scaffold future projects with skills living directly under \`.claude/skills/\` instead of a repo-root \`skills/\` folder, if there's no strong reason for the split. Discovered while starting work on #23: \"start 23\" failed with \`Unknown skill: start-issue\`, worked around by reading and following \`skills/start-issue/SKILL.md\` manually instead.

cloudbot added the

chore

label

2026-07-23 23:22:58 +02:00

cloudbot closed this issue

2026-07-24 12:11:22 +02:00