[2.15.2] Fix skill spec compliance across all skills

Fixed issues flagged by skill-creator spec:
- Reference files now use proper markdown links instead of backtick text
- Descriptions use third person ("This skill should be used when...")
- Added Skill Compliance Checklist to CLAUDE.md with validation commands

Affected skills: agent-native-architecture, andrew-kane-gem-writer,
compound-docs, create-agent-skills, dhh-rails-style, dhh-ruby-style,
dspy-ruby, every-style-editor, file-todos, frontend-design, gemini-imagegen

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.claude-plugin/marketplace.json

@@ -11,8 +11,8 @@
   "plugins": [
     {
       "name": "compound-engineering",
-      "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 27 specialized agents, 17 commands, and 13 skills.",
-      "version": "2.13.0",
+      "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 27 specialized agents, 19 commands, and 13 skills.",
+      "version": "2.15.2",
       "author": {
         "name": "Kieran Klaassen",
         "url": "https://github.com/kieranklaassen",

plugins/compound-engineering/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "compound-engineering",
-  "version": "2.15.1",
+  "version": "2.15.2",
   "description": "AI-powered development tools. 27 agents, 19 commands, 13 skills, 2 MCP servers for code review, research, design, and workflow automation.",
   "author": {
     "name": "Kieran Klaassen",

plugins/compound-engineering/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to the compound-engineering plugin will be documented in thi
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.15.2] - 2025-12-21
+
+### Fixed
+
+- **All skills** - Fixed spec compliance issues across 13 skills:
+  - Reference files now use proper markdown links (`[file.md](./references/file.md)`) instead of backtick text
+  - Descriptions now use third person ("This skill should be used when...") per skill-creator spec
+  - Affected skills: agent-native-architecture, andrew-kane-gem-writer, compound-docs, create-agent-skills, dhh-rails-style, dhh-ruby-style, dspy-ruby, every-style-editor, file-todos, frontend-design, gemini-imagegen
+
+### Added
+
+- **CLAUDE.md** - Added Skill Compliance Checklist with validation commands for ensuring new skills meet spec requirements
+
 ## [2.15.1] - 2025-12-18
 
 ### Changed

plugins/compound-engineering/CLAUDE.md

@@ -52,6 +52,39 @@ skills/
 
 **Why `workflows:`?** Claude Code has built-in `/plan` and `/review` commands. Using `name: workflows:plan` in frontmatter creates a unique `/workflows:plan` command with no collision.
 
+## Skill Compliance Checklist
+
+When adding or modifying skills, verify compliance with skill-creator spec:
+
+### YAML Frontmatter (Required)
+
+- [ ] `name:` present and matches directory name (lowercase-with-hyphens)
+- [ ] `description:` present and uses **third person** ("This skill should be used when..." NOT "Use this skill when...")
+
+### Reference Links (Required if references/ exists)
+
+- [ ] All files in `references/` are linked as `[filename.md](./references/filename.md)`
+- [ ] All files in `assets/` are linked as `[filename](./assets/filename)`
+- [ ] All files in `scripts/` are linked as `[filename](./scripts/filename)`
+- [ ] No bare backtick references like `` `references/file.md` `` - use proper markdown links
+
+### Writing Style
+
+- [ ] Use imperative/infinitive form (verb-first instructions)
+- [ ] Avoid second person ("you should") - use objective language ("To accomplish X, do Y")
+
+### Quick Validation Command
+
+```bash
+# Check for unlinked references in a skill
+grep -E '`(references|assets|scripts)/[^`]+`' skills/*/SKILL.md
+# Should return nothing if all refs are properly linked
+
+# Check description format
+grep -E '^description:' skills/*/SKILL.md | grep -v 'This skill'
+# Should return nothing if all use third person
+```
+
 ## Documentation
 
 See `docs/solutions/plugin-versioning-requirements.md` for detailed versioning workflow.

plugins/compound-engineering/skills/agent-native-architecture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-native-architecture
-description: Build AI agents using prompt-native architecture where features are defined in prompts, not code. Use when creating autonomous agents, designing MCP servers, implementing self-modifying systems, or adopting the "trust the agent's intelligence" philosophy.
+description: This skill should be used when building AI agents using prompt-native architecture where features are defined in prompts, not code. Use it when creating autonomous agents, designing MCP servers, implementing self-modifying systems, or adopting the "trust the agent's intelligence" philosophy.
 ---
 
 <essential_principles>
@@ -72,11 +72,11 @@ What aspect of agent native architecture do you need help with?
 <routing>
 | Response | Action |
 |----------|--------|
-| 1, "design", "architecture", "plan" | Read references/architecture-patterns.md |
-| 2, "tool", "mcp", "primitive" | Read references/mcp-tool-design.md |
-| 3, "prompt", "system prompt", "behavior" | Read references/system-prompt-design.md |
-| 4, "self-modify", "evolve", "git" | Read references/self-modification.md |
-| 5, "review", "refactor", "existing" | Read references/refactoring-to-prompt-native.md |
+| 1, "design", "architecture", "plan" | Read [architecture-patterns.md](./references/architecture-patterns.md) |
+| 2, "tool", "mcp", "primitive" | Read [mcp-tool-design.md](./references/mcp-tool-design.md) |
+| 3, "prompt", "system prompt", "behavior" | Read [system-prompt-design.md](./references/system-prompt-design.md) |
+| 4, "self-modify", "evolve", "git" | Read [self-modification.md](./references/self-modification.md) |
+| 5, "review", "refactor", "existing" | Read [refactoring-to-prompt-native.md](./references/refactoring-to-prompt-native.md) |
 
 **After reading the reference, apply those patterns to the user's specific context.**
 </routing>
@@ -123,11 +123,11 @@ query({
 
 All references in `references/`:
 
-**Architecture:** architecture-patterns.md
-**Tool Design:** mcp-tool-design.md
-**Prompts:** system-prompt-design.md
-**Self-Modification:** self-modification.md
-**Refactoring:** refactoring-to-prompt-native.md
+- **Architecture:** [architecture-patterns.md](./references/architecture-patterns.md)
+- **Tool Design:** [mcp-tool-design.md](./references/mcp-tool-design.md)
+- **Prompts:** [system-prompt-design.md](./references/system-prompt-design.md)
+- **Self-Modification:** [self-modification.md](./references/self-modification.md)
+- **Refactoring:** [refactoring-to-prompt-native.md](./references/refactoring-to-prompt-native.md)
 </reference_index>
 
 <anti_patterns>

plugins/compound-engineering/skills/andrew-kane-gem-writer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: andrew-kane-gem-writer
-description: Write Ruby gems following Andrew Kane's proven patterns and philosophy. Use when creating new Ruby gems, refactoring existing gems, designing gem APIs, or when the user wants clean, minimal, production-ready Ruby library code. Triggers on requests like "create a gem", "write a Ruby library", "design a gem API", or mentions of Andrew Kane's style.
+description: This skill should be used when writing Ruby gems following Andrew Kane's proven patterns and philosophy. It applies when creating new Ruby gems, refactoring existing gems, designing gem APIs, or when clean, minimal, production-ready Ruby library code is needed. Triggers on requests like "create a gem", "write a Ruby library", "design a gem API", or mentions of Andrew Kane's style.
 ---
 
 # Andrew Kane Gem Writer

plugins/compound-engineering/skills/compound-docs/SKILL.md

@@ -150,7 +150,7 @@ Format: `[sanitized-symptom]-[module]-[YYYYMMDD].md`
 <validation_gate name="yaml-schema" blocking="true">
 
 **Validate against schema:**
-Load `schema.yaml` and classify the problem against the enum values defined in `references/yaml-schema.md`. Ensure all required fields are present and match allowed values exactly.
+Load `schema.yaml` and classify the problem against the enum values defined in [yaml-schema.md](./references/yaml-schema.md). Ensure all required fields are present and match allowed values exactly.
 
 **BLOCK if validation fails:**
 
@@ -173,7 +173,7 @@ Please provide corrected values.
 <step number="6" required="true" depends_on="5">
 ### Step 6: Create Documentation
 
-**Determine category from problem_type:** Use the category mapping defined in `references/yaml-schema.md` (lines 49-61).
+**Determine category from problem_type:** Use the category mapping defined in [yaml-schema.md](./references/yaml-schema.md) (lines 49-61).
 
 **Create documentation file:**
 

plugins/compound-engineering/skills/create-agent-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-agent-skills
-description: Expert guidance for creating, writing, building, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.
+description: This skill provides expert guidance for creating, writing, building, and refining Claude Code Skills. It should be used when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.
 ---
 
 <essential_principles>
@@ -140,11 +140,11 @@ scripts/:
 
 All in `references/`:
 
-**Structure:** recommended-structure.md, skill-structure.md
-**Principles:** core-principles.md, be-clear-and-direct.md, use-xml-tags.md
-**Patterns:** common-patterns.md, workflows-and-validation.md
-**Assets:** using-templates.md, using-scripts.md
-**Advanced:** executable-code.md, api-security.md, iteration-and-testing.md
+- **Structure:** [recommended-structure.md](./references/recommended-structure.md), [skill-structure.md](./references/skill-structure.md)
+- **Principles:** [core-principles.md](./references/core-principles.md), [be-clear-and-direct.md](./references/be-clear-and-direct.md), [use-xml-tags.md](./references/use-xml-tags.md)
+- **Patterns:** [common-patterns.md](./references/common-patterns.md), [workflows-and-validation.md](./references/workflows-and-validation.md)
+- **Assets:** [using-templates.md](./references/using-templates.md), [using-scripts.md](./references/using-scripts.md)
+- **Advanced:** [executable-code.md](./references/executable-code.md), [api-security.md](./references/api-security.md), [iteration-and-testing.md](./references/iteration-and-testing.md)
 </reference_index>
 
 <workflows_index>

plugins/compound-engineering/skills/dhh-rails-style/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dhh-rails-style
-description: Write Ruby and Rails code in DHH's distinctive 37signals style. Use this skill when writing Ruby code, Rails applications, creating models, controllers, or any Ruby file. Triggers on Ruby/Rails code generation, refactoring requests, code review, or when the user mentions DHH, 37signals, Basecamp, HEY, or Campfire style. Embodies REST purity, fat models, thin controllers, Current attributes, Hotwire patterns, and the "clarity over cleverness" philosophy.
+description: This skill should be used when writing Ruby and Rails code in DHH's distinctive 37signals style. It applies when writing Ruby code, Rails applications, creating models, controllers, or any Ruby file. Triggers on Ruby/Rails code generation, refactoring requests, code review, or when the user mentions DHH, 37signals, Basecamp, HEY, or Campfire style. Embodies REST purity, fat models, thin controllers, Current attributes, Hotwire patterns, and the "clarity over cleverness" philosophy.
 ---
 
 <objective>
@@ -45,10 +45,10 @@ What are you working on?
 <routing>
 | Response | Reference to Read |
 |----------|-------------------|
-| 1, "controller" | references/controllers.md |
-| 2, "model" | references/models.md |
-| 3, "view", "frontend", "turbo", "stimulus", "css" | references/frontend.md |
-| 4, "architecture", "routing", "auth", "job" | references/architecture.md |
+| 1, "controller" | [controllers.md](./references/controllers.md) |
+| 2, "model" | [models.md](./references/models.md) |
+| 3, "view", "frontend", "turbo", "stimulus", "css" | [frontend.md](./references/frontend.md) |
+| 4, "architecture", "routing", "auth", "job" | [architecture.md](./references/architecture.md) |
 | 5, "review" | Read all references, then review code |
 | 6, general task | Read relevant references based on context |
 
@@ -89,11 +89,11 @@ All detailed patterns in `references/`:
 
 | File | Topics |
 |------|--------|
-| controllers.md | REST mapping, concerns, Turbo responses, API patterns |
-| models.md | Concerns, state records, callbacks, scopes, POROs |
-| frontend.md | Turbo, Stimulus, CSS architecture, view patterns |
-| architecture.md | Routing, auth, jobs, caching, multi-tenancy, config |
-| gems.md | What they use vs avoid, and why |
+| [controllers.md](./references/controllers.md) | REST mapping, concerns, Turbo responses, API patterns |
+| [models.md](./references/models.md) | Concerns, state records, callbacks, scopes, POROs |
+| [frontend.md](./references/frontend.md) | Turbo, Stimulus, CSS architecture, view patterns |
+| [architecture.md](./references/architecture.md) | Routing, auth, jobs, caching, multi-tenancy, config |
+| [gems.md](./references/gems.md) | What they use vs avoid, and why |
 </reference_index>
 
 <success_criteria>

plugins/compound-engineering/skills/dhh-ruby-style/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dhh-ruby-style
-description: Write Ruby and Rails code in DHH's distinctive 37signals style. Use this skill when writing Ruby code, Rails applications, creating models, controllers, or any Ruby file. Triggers on Ruby/Rails code generation, refactoring requests, code review, or when the user mentions DHH, 37signals, Basecamp, HEY, or Campfire style. Embodies REST purity, fat models, thin controllers, Current attributes, Hotwire patterns, and the "clarity over cleverness" philosophy.
+description: This skill should be used when writing Ruby and Rails code in DHH's distinctive 37signals style. It applies when writing Ruby code, Rails applications, creating models, controllers, or any Ruby file. Triggers on Ruby/Rails code generation, refactoring requests, code review, or when the user mentions DHH, 37signals, Basecamp, HEY, or Campfire style. Embodies REST purity, fat models, thin controllers, Current attributes, Hotwire patterns, and the "clarity over cleverness" philosophy.
 ---
 
 # DHH Ruby/Rails Style Guide
@@ -185,8 +185,8 @@ end
 ## Detailed References
 
 For comprehensive patterns and examples, see:
-- `references/patterns.md` - Complete code patterns with explanations
-- `references/resources.md` - Links to source material and further reading
+- [patterns.md](./references/patterns.md) - Complete code patterns with explanations
+- [resources.md](./references/resources.md) - Links to source material and further reading
 
 ## Philosophy Summary
 

plugins/compound-engineering/skills/dspy-ruby/SKILL.md

@@ -570,15 +570,15 @@ This skill includes comprehensive reference materials and templates:
 
 ### References (load as needed for detailed information)
 
-- **`references/core-concepts.md`**: Complete guide to signatures, modules, predictors, multimodal support, and best practices
-- **`references/providers.md`**: All LLM provider configurations, compatibility matrix, cost optimization, and troubleshooting
-- **`references/optimization.md`**: Testing patterns, optimization techniques, observability setup, and monitoring
+- [core-concepts.md](./references/core-concepts.md): Complete guide to signatures, modules, predictors, multimodal support, and best practices
+- [providers.md](./references/providers.md): All LLM provider configurations, compatibility matrix, cost optimization, and troubleshooting
+- [optimization.md](./references/optimization.md): Testing patterns, optimization techniques, observability setup, and monitoring
 
 ### Assets (templates for quick starts)
 
-- **`assets/signature-template.rb`**: Examples of signatures including basic, vision, sentiment analysis, and code generation
-- **`assets/module-template.rb`**: Module patterns including pipelines, agents, error handling, caching, and state management
-- **`assets/config-template.rb`**: Configuration examples for all providers, environments, observability, and production patterns
+- [signature-template.rb](./assets/signature-template.rb): Examples of signatures including basic, vision, sentiment analysis, and code generation
+- [module-template.rb](./assets/module-template.rb): Module patterns including pipelines, agents, error handling, caching, and state management
+- [config-template.rb](./assets/config-template.rb): Configuration examples for all providers, environments, observability, and production patterns
 
 ## When to Use This Skill
 

plugins/compound-engineering/skills/every-style-editor/SKILL.md

@@ -44,7 +44,7 @@ Review each paragraph systematically, checking for:
 - Word choice and usage (overused words, passive voice)
 - Adherence to Every style guide rules
 
-Reference the complete `EVERY_WRITE_STYLE.md` for specific rules when in doubt.
+Reference the complete [EVERY_WRITE_STYLE.md](./references/EVERY_WRITE_STYLE.md) for specific rules when in doubt.
 
 ### Step 3: Mechanical Review
 
@@ -99,7 +99,7 @@ FINAL RECOMMENDATIONS
 
 ## Style Guide Reference
 
-The complete Every style guide is included in `references/EVERY_WRITE_STYLE.md`. Key areas to focus on:
+The complete Every style guide is included in [EVERY_WRITE_STYLE.md](./references/EVERY_WRITE_STYLE.md). Key areas to focus on:
 
 - **Quick Rules**: Title case for headlines, sentence case elsewhere
 - **Tone**: Active voice, avoid overused words (actually, very, just), be specific

plugins/compound-engineering/skills/file-todos/SKILL.md

@@ -40,7 +40,7 @@ Todo files follow this naming pattern:
 
 ## File Structure
 
-Each todo is a markdown file with YAML frontmatter and structured sections. Use the template at `assets/todo-template.md` as a starting point when creating new todos.
+Each todo is a markdown file with YAML frontmatter and structured sections. Use the template at [todo-template.md](./assets/todo-template.md) as a starting point when creating new todos.
 
 **Required sections:**
 - **Problem Statement** - What is broken, missing, or needs improvement?

plugins/compound-engineering/skills/frontend-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontend-design
-description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+description: This skill should be used when creating distinctive, production-grade frontend interfaces with high design quality. It applies when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
 license: Complete terms in LICENSE.txt
 ---
 

plugins/compound-engineering/skills/gemini-imagegen/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gemini-imagegen
-description: Generate and edit images using the Gemini API (Nano Banana Pro). Use this skill when creating images from text prompts, editing existing images, applying style transfers, generating logos with text, creating stickers, product mockups, or any image generation/manipulation task. Supports text-to-image, image editing, multi-turn refinement, and composition from multiple reference images.
+description: This skill should be used when generating and editing images using the Gemini API (Nano Banana Pro). It applies when creating images from text prompts, editing existing images, applying style transfers, generating logos with text, creating stickers, product mockups, or any image generation/manipulation task. Supports text-to-image, image editing, multi-turn refinement, and composition from multiple reference images.
 ---
 
 # Gemini Image Generation (Nano Banana Pro)