Refactor skill documentation: consolidate SKILL.md, add reference docs

[devstefancho]

Summary

Restructured skill documentation across all plugins to follow a new authoring convention: keep SKILL.md concise (≤100 lines) with hard rules and core workflow, move detailed reference material into separate reference.md and template files. This improves discoverability, reduces cognitive load, and makes skills easier to maintain.

Key Changes

Documentation Structure

• SKILL.md — now strictly ≤100 lines with:

  • One-line description (active verb, no "Use when")
  • Hard Rules (bullet list, no prose)
  • Core workflow phases (numbered, minimal detail)
  • Directory layout or schema (if applicable)

• reference.md (new) — overflow detail linked one level deep from SKILL.md:

  • writing-tasks/reference.md — decomposition rules, sizing, dependency inference
  • implement-with-test/reference.md — test framework detection, report rules
  • browser-walkthrough/references/ — guide mode, screenshot resolution, example flows
  • computer-use-plugin/skills/computer-use-test/known-issues.md — past issues and workarounds

• Templates — moved into skills/{skill}/templates/ subdirectory (e.g., templates/spec-template.md, templates/report-template.md)

Skill-Specific Updates

writing-tasks-plugin

• Condensed SKILL.md from 250 → 90 lines
• Extracted decomposition rules, task schema, and dashboard format into separate files
• Clarified "Hard Rules" (task files as SSOT, mandatory depends_on, auto-sync blocks, validation, parallel-worktree safety)

writing-specs-plugin

• Reduced from 134 → 86 lines
• Moved non-interactive defaults to non-interactive.md
• Kept template-driven, search-first, one-spec-per-task as core principles

implement-with-test-plugin

• Condensed from 173 → 81 lines
• Extracted test framework detection and report rules to reference.md
• Clarified task-first, pattern-follower, test-alongside, run-to-green as hard rules

browser-walkthrough-plugin

• Reduced from 219 → 105 lines
• Moved iframe handling, guide mode, screenshot resolution, and example flows to references/
• Simplified user response table and bootstrap section

brain-storm-plugin

• Condensed from 131 → 72 lines
• Extracted design quality standard to design-standard.md
• Moved report format to report-format.md
• Clarified two modes (Brainstorm, Cleanup) and hard rules

ui-prototype-preview-plugin

• Reduced from 198 → 75 lines
• Moved design quality standard and report format to separate files
• Kept output rules and design brief workflow concise

computer-use-plugin

• Condensed from 118 → 71 lines
• Extracted known issues to known-issues.md
• Simplified workflow phases and directory rules

Other skills — minor description rewrites for consistency (active voice, no "Use when" in description field)

Validation & Metadata

• Updated scripts/validate-plugins.sh to check SKILL.md frontmatter is valid YAML (catches unquoted colons in description:)
• Added metadata: { internal: true } to hermes-runtime skill (internal-only helper)
• Updated AGENTS.md to document new skill structure: SKILL.md + reference.md + templates/

Version Bumps

• Minor version increments for all affected plugins (e.g., 1.0.2 → 1.1.0, 1.2.4 → 1.3.0)

Implementation Details

• All hard rules are now bullet-pointed and scannable (no prose paragraphs)
• Workflow phases are numbered and minimal (2–7 steps max)
• Reference files are linked one level deep from SKILL.md (e.g., `[task-

https://claude.ai/code/session_01YPKG1K27VWQWEMcS9NJK1a

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
claude-plugins	Ready	Preview, Comment	Jun 10, 2026 12:20pm