Uh oh!
There was an error while loading. Please reload this page.
feat: add cmk:write-cmk-skill - #28
Conversation
Port author-skills into the kit as a user-invoked meta skill for test-driven cmk skill authoring, and wire it into AI docs, on-ramps, and CONTRIBUTING.
Name the user-invoked authoring skill before preparing upstream PRs for generic amendments; skip for project adaptations that stay local.
harrymove-ctrl
left a comment
There was a problem hiding this comment.
Requesting changes. The content is strong and the docs work is thorough — README, conventions, the new doc page, and on-ramps all landed correctly. The cmk:sync hand-off is also written exactly right ("name/write-cmk-skill for the user to run… Do not invoke it"), which is the trap I'd have expected a commit like that to fall into. Credit where due.
Four things should be resolved before merge, plus two questions.
skill-lint is green, but it only checks frontmatter shape, the line budget, reference integrity, citations, paths, and JSON validity. None of the findings below are things it can catch.
1. The skill ships in violation of its own Iron Law — twice
NO NEW SKILL AND NO EDIT TO A SKILL SHIPS WITHOUT A FAILING TEST FIRST
For the new skill. The ship checklist requires "The RED/GREEN evidence for this edit is recorded in the skill's TESTS.md", and the description advertises TESTS.md as part of the deliverable — but the package has none. cmk:interpret, the closest analog (user-invoked, disable-model-invocation, ships an eval.json), landed its TESTS.md in the same commit that added it (0d7b298).
The tell is in the fixtures. Both entries here are derived_from: "SKILL.md § …" — assertions restated from the text that was just written. Interpret's are derived_from: "TESTS.md § S1 …", i.e. observed baseline failures. That is precisely the gap the skill itself names:
Wrote the text before running the baseline? You documented what you guess agents do wrong, not what they do wrong.
For the cmk:sync edit. The law covers edits, and the rationalization table has a row for exactly this: "'It's a tiny edit' → Edits regress skills exactly like code. Baseline against the old version first."2dc9069 adds a mandatory gate step to contribute mode with no baseline. skills/sync/ has no TESTS.md, and its eval.json (4 fixtures) wasn't touched — contribute mode has zero coverage before or after this PR.
Ask: run the RED/GREEN/REFACTOR loop on a named model roster into skills/write-cmk-skill/TESTS.md; re-derive eval.json from it; add a contribute-gate fixture to skills/sync/eval.json; and add - Pressure-test record: skills/write-cmk-skill/TESTS.md to the ## Where list in docs/ai/skills/write-cmk-skill.md (cf. interpret.md:25).
2. Slash-command form — now load-bearing, and still unverified
/write-cmk-skill (no prefix) appears in 6 files, including inside a model-invocable skill's workflow at skills/sync/SKILL.md:55 and its reference file.
README.md:17 documents the form as /cmk:requirements, and conventions.md says name is "used as the slash command". Under the plugin layout the namespace is supplied by the plugin itself (plugin:skill — e.g. hookify:writing-rules, whose frontmatter name carries no prefix), so the command comes out prefixed either way. I can't find an install path that yields the bare form:
| Install path | Resulting command |
|---|---|
Plugin, as-is (ai-devkit + name: cmk:write-cmk-skill) | ai-devkit:cmk:write-cmk-skill — two colons, likely malformed |
Plugin, with the cmk plugin name | /cmk:write-cmk-skill |
Vendored (.agents/skills/cmk-<name>/) | /cmk-write-cmk-skill |
If it is in fact prefixed, an agent running cmk:sync contribute mode will instruct the user to type a command that does not exist. The test plan already flags this as unchecked — worth settling before merge rather than after, since it is now baked into shipped skill text on a required path, not just docs.
Related, for whoever picks up the drop-the-prefix / marketplace change: this PR adds one more skill with cmk: hardcoded into name:, plus 6 new /write-cmk-skill references, all of which that refactor will have to revisit.
3. Site registry not updated — lib/skill-types.ts
Precedent: 0d7b298 touched both lib/skills.ts and lib/skill-types.ts.
Skills are filesystem-discovered (lib/skills.ts:29), so this one will render — degraded. CATEGORY_MAP has no entry, so it falls to "other". SKILL_PURPOSE has no entry, so skillPurpose() falls back to the first quoted trigger phrase — and this description contains no quoted phrases, so it returns "", giving a blank purpose line on the catalog card and the graph node. Neither build nor skill-lint catches it.
// CATEGORY_LABELSmeta: "Meta",// CATEGORY_MAP"write-cmk-skill": "meta",// SKILL_PURPOSE"write-cmk-skill": "Author or review a cmk skill",(Minor: the doc comment above SKILL_PURPOSE says "across 34 skills" — now 35.)
4. Broken markdown — SKILL.md:51 and SKILL.md:85
Backslash-escaped backticks inside a code span. CommonMark does not process escapes there. Verified through GitHub's own markdown API:
<code>REQUIRED SUB-SKILL: use \</code>cmk:learn``It renders garbled on GitHub and on the devkit site, which renders SKILL.md directly. This is the only file under skills/ containing \ + backtick. Fix with a double-backtick fence so the inner backticks are literal:
``REQUIRED SUB-SKILL: use `cmk:learn` ``
Questions
Is the cmk:sync change meant to be in this PR? The title and all three Summary bullets say "add cmk:write-cmk-skill", with no mention that cmk:sync gained a mandatory workflow step and a version bump. If it is intentional, please add it to the description and the test plan — it changes behavior in a skill already vendored into consumer repos, and a reviewer going by the description would miss it. If it was folded in incidentally, splitting 2dc9069 into its own PR would keep the two risk profiles separate.
Should contribute-mode step 3 handle the skill not being installed? It assumes write-cmk-skill is present. A repo that vendored before this PR, or that vendors selectively, won't have it, and the only escape hatch offered is "the user already completed that pass."
Not blocking, and pre-existing:skills/enclave/ has no docs/ai/skills/enclave.md and is absent from the docs README roster — which is why that file's family counts were already off by one before this change.
Summary
cmk:write-cmk-skill(v1.0.0), ported fromauthor-skills, as a user-invoked meta skill for creating/editing/reviewingcmk:*skills under a failing-baseline Iron Law.references/, frontmatter order, 150-line budget,scripts/skill-lint.sh).Test plan
bash scripts/skill-lint.shpasses/write-cmk-skilldiscovery in the host agent slash menu after install/vendordocs/ai/skills/write-cmk-skill.mdlinks resolve fromdocs/ai/skills/README.md