interskill

keep priority P1 effort S wave 1

What it does: A skill-authoring toolkit: two skills under skills/. skill (SKILL.md, named skill) is a two-phase creation workflow — spec-driven authoring (frontmatter, invocation control, CSO/Claude-Search-Optimization description engineering) plus TDD-adapted pressure testing (RED: run a subagent without the skill and capture rationalizations; GREEN: load skill, verify compliance; REFACTOR: plug loopholes). It ships a rich knowledge cluster: 18 reference docs (~5,900 lines incl. official-spec, anthropic-best-practices, claude-search-optimization, testing-skills-with-subagents, persuasion-principles), 2 templates (simple, router), and ~11 workflow files. audit (SKILL.md) is a standalone manual PASS/WARN/FAIL checklist over structure, frontmatter, invocation control, content quality, and anti-patterns. No commands, no hooks, no MCP server, one script (bump-version.sh), and a small pytest structural suite (asserts exactly 2 skills + frontmatter validity). Extracted from interdev’s create-agent-skills + writing-skills.

Rationale: This plugin sits squarely on a SOTA-validated foundation: multiple June-2026 findings name the SKILL.md format as Anthropic’s “second standards play after MCP,” call skills “the durable, repeatable unit of capability,” and explicitly cite progressive disclosure as the core design principle — all of which interskill teaches accurately and applies to itself (SKILL.md + references one level deep + SKILL-compact.md). The official-spec.md reference is current (2026, correct frontmatter incl. context:fork/agent/hooks, merged commands+skills, $ARGUMENTS substitutions). The CSO reference encodes the genuinely non-obvious “description = when-to-use, NOT what-it-does” insight that prevents Claude shortcutting the body — a real, hard-won quality lever. The content is mature and largely correct, so the honest verdict is keep, not modernize. But it has concrete defects to fix: (1) audit/SKILL.md line 22 tells the agent to run gen-skill-compact.sh --check, a script that does not exist anywhere in the plugin or interverse tree (only bump-version.sh ships) — this will fail every audit run; (2) testing-skills-with-subagents.md references examples/CLAUDE_MD_TESTING.md, which also does not exist (no examples/ dir at all); (3) docs drift — AGENTS.md and README describe a create/ skill dir with “14”/“17” references, but the actual dir is skill/ with 18 reference files (the create→skill rename in git history was not propagated to docs). These are real correctness bugs in a quality-tooling plugin, which is doubly embarrassing since this plugin’s own audit checklist would flag dangling references.

SOTA gap: The audit skill is a static, LLM-read manual checklist with no executable verification. SOTA on self-correction (ReVeal arXiv:2506.11442; “From Code to Courtroom” arXiv:2510.24367) is emphatic that unstructured NL critique is largely ineffective for improvement and that verification must be grounded in executable signals. interskill already has a pytest structural harness but does not wire it into the audit skill — audit should shell out to deterministic checks (frontmatter parse, line-count, dangling-link resolution, description-length, name-regex) and reserve the LLM only for judgment items (CSO quality, anti-patterns), i.e. a deterministic-skeleton + LLM-island design (interleave’s own thesis). Second, smaller gap: the SkillFlow / RAG-MCP / skill-retrieval line (skill discovery as embedding retrieval) and “Agent-as-a-Judge” trajectory evaluation suggest audit could test whether a skill’s description actually triggers via the harness’s own ToolSearch/embedding gate rather than eyeballing trigger keywords — but this is incremental polish, not a missing frontier capability.

Redundancy: Meaningful overlap with several skill/plugin-authoring tools in the roster. The harness exposes plugin-dev:skill-development, clavain:create-agent-skill / clavain:heal-skill, and the global skill-creator skill — all cover SKILL.md authoring. interplug (plugin lifecycle/structure/validate) and interpub (publishing/version) cover the plugin layer interskill explicitly defers to. The cleanest division of labor per its own docs: interplug = plugin scaffolding/lifecycle, interpub = release, interskill = skill content quality (creation + audit). The redundancy with clavain:create-agent-skill and plugin-dev:skill-development is the most worth resolving — ideally interskill is the canonical content-quality authority and the clavain/plugin-dev variants delegate to it rather than duplicating spec text, to avoid three copies of the frontmatter table drifting apart.

Actions:

Fix the two dangling references (P0 correctness): either add the missing gen-skill-compact.sh script (audit/SKILL.md:22) and examples/CLAUDE_MD_TESTING.md (testing reference:15), or remove/rewrite the lines that cite them. A skill-quality plugin must pass its own audit.
Repair docs drift: update AGENTS.md and README.md to say skill/ not create/, correct the reference count (18, not 14/17), and re-run versions consistently — the create→skill rename was only half-applied.
Wire the existing pytest structural suite into the audit skill as a deterministic pre-pass (frontmatter parse, line count, dangling-link check, name regex, description length), then have the LLM judge only CSO/anti-pattern items — grounding critique in executable signals per ReVeal / ‘Code to Courtroom’ SOTA.
Add a discovery/trigger test to audit: programmatically check whether the description would surface the skill (keyword/embedding gate) rather than relying on manual ‘includes trigger keywords’ inspection, aligning with skill-retrieval (SkillFlow/RAG-MCP) findings; and de-duplicate spec text shared with clavain:create-agent-skill / plugin-dev:skill-development by making interskill the canonical source.