Skip to content

feat(skills): make skills loadable, and audit for it - #182

Merged
MCamner merged 3 commits into
mainfrom
chore/skills-discoverable
Aug 8, 2026
Merged

feat(skills): make skills loadable, and audit for it#182
MCamner merged 3 commits into
mainfrom
chore/skills-discoverable

Conversation

@MCamner

@MCamner MCamner commented Aug 8, 2026

Copy link
Copy Markdown
Owner

Two commits: wire this repo's skills up, then stop the same gap coming back.

The gap

The MQ convention keeps skills in <repo>/skills/ and indexes them in SKILLS.md. Claude Code discovers skills somewhere else: <repo>/.claude/skills/. Nothing checked those two against each other, so the entire stack carried skills no agent could load:

repo unreachable
mq-image-analyze 13
mq-mcp 12
mq-agent 8
macos-scripts 8
repo-signal 7
mq-hal 7
mq-ums 7
atlas-one 1

63 in total. mq-skills.py audit called every one of them ok, indexed.

The one that looked wired here was a false positive: .claude/commands/mqlaunch-command-surface.md is a slash command whose whole body is an instruction to go read skills/mqlaunch-command-surface/SKILL.md. That works when someone types the command; automatic triggering on the description — the thing that makes a skill worth having — never happened.

The fix

Relative symlinks from .claude/skills/ into skills/ and .agents/skills/, mirroring how .agents/skills/pdf was already wired here by hand. The other seven repos get the same treatment in their own commits.

The check

mq-skills.py audit prints a third column, and validate warns on two new states:

macos-scripts: 7 skill(s), 7 indexed, 7 discoverable
  • not-discoverable — no entry under .claude/skills
  • broken-link — an entry with no SKILL.md behind it

Fix hints name the actual remedy rather than pointing at SKILL.md again.

Step 12 of the smoke test builds a scratch repo with one skill and asserts it is reported while unlinked and not reported once linked, so the check tracks reality instead of always complaining.

Verification

The linked skills became available in this session the moment the links existed — no restart, which is the proof that matters more than the audit column.

$ ./tests/skills-repos-smoke.sh
[11/12] audit reports whether each skill is discoverable by Claude Code
[12/12] an unlinked skill is reported, and a linked one is not
OK: skills and repos command surface smoke test passed

$ python3 tools/scripts/mq-skills.py validate --ecosystem
Ecosystem validation: 8 repo(s)
Validation passed: 0 warning(s)

$ MACOS_SCRIPTS_HOME="$PWD" MQ_NO_TUI=1 ./tools/scripts/test-all.sh
[PASS] Shell lint passed at warning severity (197 files)
[PASS] All selftest checks passed.

🤖 Generated with Claude Code

MCamner and others added 3 commits August 8, 2026 19:37
The MQ convention keeps skills in <repo>/skills/, but Claude Code only
discovers them under <repo>/.claude/skills/. Every repo in the stack therefore
carried a full set of skills that no agent could load — 63 across the eight of
them. mq-skills.py reported them all "ok, indexed", because it validates the MQ
convention and knows nothing about Claude Code's search path.

Relative symlinks, so a fresh clone is wired the same way. This mirrors how
.agents/skills entries were already linked by hand in mq-agent and
macos-scripts.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
mq-skills.py reported all 63 skills in the stack as "ok, indexed" while not
one of them could be loaded. It validated the MQ convention — skills/ plus a
SKILLS.md entry — and knew nothing about Claude Code's search path, which is
.claude/skills/. Being indexed says a human can find the file; it says nothing
about whether a tool can run it.

audit now prints a third column and validate warns on two new states:
not-discoverable (no entry under .claude/skills) and broken-link (an entry
with no SKILL.md behind it). The fix hints name the actual remedy.

The smoke test builds a scratch repo with one skill, asserts it is reported
while unlinked and not reported once linked — so the check tracks reality
instead of always complaining.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Step 11 passed `--repo macos-scripts`, and a bare name resolves under $HOME.
On a CI runner the repo lives in $GITHUB_WORKSPACE, so the audit found no
repos, printed nothing, and the grep failed against a checker that was working
correctly. Step 10 already skips its listing assertions for the same reason.

Reproduced by running the suite with HOME pointed at a scratch dir, which
fails before this change and passes after.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@MCamner
MCamner merged commit e84198e into main Aug 8, 2026
3 checks passed
@MCamner
MCamner deleted the chore/skills-discoverable branch August 8, 2026 19:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant