refactor: nest skill references per agentskills.io spec

[philoserf]

Summary

• Move 62 reference/template/example files into spec-compliant subdirectories across 14 skills
• Update ~80 markdown links in SKILL.md files and cross-skill references
• Rewrite 6 documentation files to replace flat convention with nested references/ pattern
• Align all skill subdirectories with agentskills.io specification: only references/, assets/, scripts/
• Convert all 14 skills allowed-tools from YAML arrays to space-delimited strings (spec-portable)
• Rewrite 9 keyword-list descriptions to prose style (passes skill-validator)
• Remove non-standard frontmatter fields (argument-hint, version, commented-out model)
• Add word/token-count awareness and keyword-list anti-pattern checks to quality tooling
• Update README component counts (16 skills, 11 hooks, 1 agent) and remove stale output-styles references

Test plan

• No stale .md files at skill roots (only SKILL.md remains)
• No broken markdown links (](*.md) targets all resolve)
• bunx prettier --check skills/ passes
• Validation hook still skips references/ files
• /cc-lint structural validation passes (0 findings)
• /cc-check functional tests pass (38/38 links, 4/4 hook tests, 10/10 discovery)
• skill-validator check passes on all 14 skills (0 errors, 0 warnings)

🤖 Generated with Claude Code

[philoserf]

@claude Take a look at this one.

[claude]

Claude finished @philoserf's task in 2m 11s —— View job

---

PR Review: refactor/skill-nested-references

• Gather context and read key changed files
• Review structural changes (file moves/renames)
• Review SKILL.md frontmatter changes
• Review documentation updates
• Review hook and settings changes
• Summarize findings

---

Summary

Well-executed structural refactoring. The commit history is logical and atomic (10 commits, each with a clear scope), the test plan is thorough, and the migration is consistently applied across all 14 skills. A few minor issues worth noting.

---

What's Good

Structural consistency: All 62 reference files correctly moved into references/ (or assets/ for map-codebase templates). No files remain at skill roots except SKILL.md.

Frontmatter cleanup: Removing version, argument-hint, and commented-out model fields is the right call — non-standard fields add noise.

allowed-tools format: The switch from YAML arrays ([Read, Write, ...]) to space-delimited strings (Read Write ...) is cleaner and spec-portable. Applied uniformly.

Description rewrites: The prose-style rewrites are much better than keyword lists. They read naturally and still contain the trigger phrases. Compare:

# Before (cc-check)
"Runs systematic tests... Use when testing skills, checking if customizations work,
verifying agents, validating hooks, running functional tests, or when asked 'does
this work', 'try this skill', or 'verify this works'..."

# After
"Runs systematic tests on Claude Code customizations — skills, agents, hooks,
and commands. Executes sample queries and validates responses against expected
behavior. Use when testing whether a customization works correctly or when
running functional and regression tests."

Cross-skill links updated: tdd-cycle correctly updated its cross-reference to ../refactor-clean/references/analysis-rubric.md.

Hook unchanged: validate-config.py correctly still skips non-SKILL.md files — no risk of references/ files triggering frontmatter validation.

---

Issues

1. Duplicate **Updated**: line in references/plugin-structure-comparison.md

The file now ends with two **Updated**: entries — one added by this PR, one left from a prior edit:

**Created**: 2026-01-03
**Updated**: 2026-02-24 (nested skill references, agent resources)
**Official Source**: https://...
**Updated**: 2026-02-19 (corrected component counts, updated reference layout)  ← stale duplicate
**Local Context**: ~/.claude global configuration (13 skills, 1 agent, 11 hooks)

Fix this →

2. Stale skill count in references/plugin-structure-comparison.md

The document was partially updated — line 391 says "14 total" but the actual count is 16 (matching README). These still say "13":

• Line 107: Current count: 13 skills
• Line 148: 13 skills total
• Line 338: Current: 13 skills, manageable
• Line 468: 13 skills, 1 agent, 11 hooks

Fix this →

3. Lost anchor precision in tdd-cycle/SKILL.md

The old links targeted specific anchors within phase-discipline.md:

# Before
[RED phase rules](./phase-discipline.md#red-phase)
[GREEN phase rules](./phase-discipline.md#green-phase)
[REFACTOR phase rules](./phase-discipline.md#refactor-phase)

# After
[RED phase rules](./references/phase-discipline.md)  ← no anchor
[GREEN phase rules](./references/phase-discipline.md)
[REFACTOR phase rules](./references/phase-discipline.md)

The headings in phase-discipline.md are ## RED Phase, ## GREEN Phase, ## REFACTOR Phase — so the anchors (#red-phase, #green-phase, #refactor-phase) remain valid. The links still work, but drop users at the top of the file instead of the relevant section. Minor regression.

4. file-organization.md example includes non-spec templates/ directory

The skill directory example now shows:

skill-name/
├── SKILL.md
├── references/
├── templates/    ← not in agentskills.io spec
└── assets/

The agentskills.io spec only allows references/, assets/, and scripts/. If templates/ isn't spec-compliant, it shouldn't appear in the canonical example. The note in the body ("Other subdirectories... remain as siblings") softens this but the diagram is misleading for a spec-alignment PR.

---

Verdict

The core refactoring is solid and the test plan confirms structural correctness. Issues 1 and 2 are documentation inconsistencies worth cleaning up before merge; issues 3 and 4 are minor.
| Branch

[Copilot]

Pull request overview

This PR refactors the skill content layout to be agentskills.io–spec compliant by moving supporting docs into per-skill references/ subdirectories, updating SKILL frontmatter, and expanding/rewriting several reference docs and quality tooling documentation.

Changes:

• Standardize skills to SKILL.md + nested references/ (and assets/ where applicable), updating internal markdown links accordingly.
• Convert allowed-tools frontmatter from YAML arrays to space-delimited strings and simplify/normalize skill descriptions to prose.
• Add/refresh reference documentation across multiple skills (workflow examples/protocols, scoring/report templates, test strategy templates, CLAUDE.md improver guidance).

Reviewed changes

Copilot reviewed 30 out of 84 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
skills/vc-ship/SKILL.md	Update frontmatter + repoint all reference links to references/
skills/vc-ship/references/simple-feature.md	Add example workflow reference
skills/vc-ship/references/rebase-guide.md	Add rebase safety guidance reference
skills/vc-ship/references/protected-branch-protocol.md	Add push-time protected branch protocol reference
skills/vc-ship/references/pr-creation.md	Add multi-commit PR creation example
skills/vc-ship/references/phase-4.5-protocol.md	Add pre-push quality gate protocol reference
skills/vc-ship/references/phase-0-protocol.md	Add start-of-work protected branch protocol reference
skills/vc-ship/references/patterns.md	Add key workflow patterns reference
skills/vc-ship/references/messy-history.md	Add messy history cleanup example
skills/vc-ship/references/large-refactor.md	Add large refactor commit-plan example
skills/vc-ship/references/examples-README.md	Add index of vc-ship reference scenarios
skills/vc-ship/references/eval-simple-feature.md	Add evaluation scenario reference
skills/vc-ship/references/eval-messy-history.md	Add evaluation scenario reference
skills/vc-ship/references/eval-large-refactor.md	Add evaluation scenario reference
skills/vc-ship/references/commit-format.md	Add commit message format guide reference
skills/vc-ship/references/bug-fix.md	Add mixed-change bugfix example reference
skills/tech-debt/SKILL.md	Normalize frontmatter + update reference paths
skills/tech-debt/references/roi-framework.md	Add ROI scoring framework reference
skills/tech-debt/references/debt-categories.md	Add debt taxonomy reference
skills/tdd-cycle/SKILL.md	Normalize frontmatter + update reference paths
skills/tdd-cycle/references/thresholds.md	Add coverage/metrics thresholds reference
skills/tdd-cycle/references/phase-discipline.md	Fix refactor-clean rubric link path
skills/skill-quality/SKILL.md	Normalize allowed-tools + update reference paths
skills/skill-quality/references/scoring-rubric.md	Extend rubric with word-count thresholds
skills/skill-quality/references/report-template.md	Add standardized quality report template
skills/skill-quality/references/quality-dimensions.md	Add word-count guidance to dimensions
skills/skill-quality/references/examples.md	Add sample assessments reference
skills/skill-improve/SKILL.md	Normalize allowed-tools + update reference paths
skills/skill-improve/references/report-template.md	Add standardized improvement report template
skills/skill-improve/references/prioritization-guide.md	Add prioritization guide reference
skills/skill-improve/references/improvement-categories.md	Add keyword-list anti-pattern + word-count guidance
skills/skill-improve/references/examples.md	Update examples to new references/ layout + allowed-tools style
skills/session-review/SKILL.md	Normalize frontmatter + update reference paths
skills/session-review/references/output-template.md	Add reflection output template reference
skills/session-review/references/framework.md	Add analysis framework reference
skills/refactor-clean/SKILL.md	Normalize frontmatter + update reference paths
skills/refactor-clean/references/quality-checklist.md	Add refactor verification checklist reference
skills/refactor-clean/references/analysis-rubric.md	Add smell/severity analysis rubric reference
skills/map-codebase/SKILL.md	Switch template references to assets/ + normalize frontmatter
skills/map-codebase/references/workflow.md	Update workflow instruction to use assets/ templates
skills/map-codebase/assets/structure.md	Add STRUCTURE template asset
skills/map-codebase/assets/stack.md	Add STACK template asset
skills/map-codebase/assets/integrations.md	Add INTEGRATIONS template asset
skills/map-codebase/assets/conventions.md	Add CONVENTIONS template asset
skills/map-codebase/assets/concerns.md	Add CONCERNS template asset
skills/map-codebase/assets/architecture.md	Add ARCHITECTURE template asset
skills/improve-instructions/SKILL.md	Normalize frontmatter + update reference paths
skills/improve-instructions/references/examples.md	Add CLAUDE.md improvement examples reference
skills/improve-instructions/references/analysis-guide.md	Add conversation-pattern analysis guide reference
skills/claude-md-improver/SKILL.md	Normalize frontmatter + add/point to new references
skills/claude-md-improver/references/update-guidelines.md	Add CLAUDE.md update rules reference
skills/claude-md-improver/references/templates.md	Add CLAUDE.md template library reference
skills/claude-md-improver/references/quality-criteria.md	Add CLAUDE.md scoring criteria reference
skills/claude-automation-recommender/SKILL.md	Normalize allowed-tools + update reference paths
skills/claude-automation-recommender/references/subagent-templates.md	Add subagent recommendation templates reference
skills/claude-automation-recommender/references/plugins-reference.md	Add plugin catalog reference
skills/claude-automation-recommender/references/output-template.md	Add recommendations report template reference
skills/claude-automation-recommender/references/mcp-servers.md	Add MCP server recommendation reference
skills/claude-automation-recommender/references/hooks-patterns.md	Add hook patterns reference
skills/claude-automation-recommender/references/decision-framework.md	Add decision framework reference
skills/cc-plan/SKILL.md	Normalize frontmatter + update reference path
skills/cc-plan/references/example-prd.md	Add PRD example reference
skills/cc-lint/SKILL.md	Normalize allowed-tools + update reference paths
skills/cc-lint/references/report-format.md	Add standardized evaluation report format reference
skills/cc-lint/references/examples.md	Update examples’ allowed-tools style
skills/cc-lint/references/evaluation-process.md	Add evaluation process reference
skills/cc-lint/references/evaluation-criteria.md	Add prose-description requirement + word-count guidance
skills/cc-lint/references/common-issues.md	Add keyword-list anti-pattern + word-count guidance
skills/cc-check/SKILL.md	Normalize frontmatter + update reference paths
skills/cc-check/references/test-strategies.md	Add test execution strategies reference
skills/cc-check/references/report-template.md	Add test report template reference
skills/cc-check/references/examples.md	Add test case examples reference
skills/cc-check/references/common-failures.md	Add common test failure catalog reference
settings.json	Add gitup to allowed Bash commands
references/plugin-structure-comparison.md	Update docs to reflect nested references/ convention
references/file-organization.md	Update skill directory guidance to nested references/ convention
references/agent-vs-skill-structure.md	Update docs to reflect nested references/ convention
hooks/validate-config.py	Clarify skip behavior comment for references paths
README.md	Update component counts + remove stale output-style references
.gitignore	Ignore reflections/ and MCP auth cache file
.claude/CLAUDE.md	Update architecture notes and skill structure guidance

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.