Use @ file references to include skills in commands

Skills have only ~20% auto-activation rate when referenced by name.
Using @~/.claude/skills/*/SKILL.md guarantees skill content is loaded.

Updated all commands to use file references instead of "Use the X skill".
Updated docs/writing-commands.md with new pattern and examples.

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

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

docs/writing-commands.md

@@ -72,7 +72,7 @@ argument-hint: <issue-number>
 
 # Work on Issue #$1
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 1. **View the issue** to understand requirements
 2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
@@ -138,7 +138,7 @@ argument-hint: [issue-number]
 
 # Groom Issues
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 ## If issue number provided ($1):
 1. **Fetch the issue** details
@@ -163,7 +163,7 @@ argument-hint: [title] or "batch"
 
 # Create Issue(s)
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 ## Single Issue (default)
 If title provided, create an issue with that title.
@@ -176,41 +176,45 @@ If $1 is "batch":
 4. Create each issue
 ```
 
-## Invoking Skills
+## Including Skills
 
-Commands reference skills by name to gain domain knowledge. When a skill is referenced, Claude reads the skill file before proceeding.
+Commands include skills using the `@` file reference syntax. This automatically injects the skill content into the command context when the command is invoked.
 
-### Explicit Reference
+### File Reference Syntax
+
+Use the `@` prefix followed by the path to the skill file:
 
 ```markdown
 # Groom Issues
 
-Use the **gitea**, **backlog-grooming**, and **issue-writing** skills.
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/backlog-grooming/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
 
 1. **Fetch the issue** details
 2. **Evaluate** against grooming checklist
 ...
 ```
 
-The phrase "Use the gitea, backlog-grooming and issue-writing skills" tells Claude to read and apply knowledge from those skill files.
+When the command runs, the content of each referenced skill file is automatically loaded into context.
 
-### Skill-Based Approach
+### Why File References?
 
-Commands should reference skills rather than embedding CLI commands directly:
+**DO NOT** use phrases like "Use the gitea skill" - skills have only ~20% auto-activation rate. File references guarantee the skill content is available.
 
-```markdown
-1. **Fetch the issue** details
-```
+| Pattern | Behavior |
+|---------|----------|
+| `@~/.claude/skills/gitea/SKILL.md` | Content automatically injected |
+| "Use the gitea skill" | Relies on auto-activation (~20% success) |
 
-This relies on the `gitea` skill to provide the CLI knowledge.
+### When to Include Skills
 
-### When to Reference Skills
-
-| Reference explicitly | Reference implicitly |
-|---------------------|---------------------|
-| Core methodology is needed | Just using a tool |
-| Quality standards matter | Simple operations |
-| Patterns should be followed | Well-known commands |
+| Include explicitly | Skip skill reference |
+|-------------------|---------------------|
+| CLI syntax is needed | Well-known commands |
+| Core methodology required | Simple operations |
+| Quality standards matter | One-off actions |
+| Patterns should be followed | No domain knowledge needed |
 
 ## Invoking Agents
 
@@ -313,7 +317,7 @@ argument-hint: <issue-number>
 
 # Work on Issue #$1
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 1. **View the issue** to understand requirements
 2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
@@ -340,7 +344,7 @@ description: Show dashboard of open issues, PRs awaiting review, and CI status.
 
 # Repository Dashboard
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 Fetch and display:
 1. All open issues
@@ -365,7 +369,9 @@ argument-hint: [issue-number]
 
 # Groom Issues
 
-Use the gitea, backlog-grooming, and issue-writing skills.
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/backlog-grooming/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
 
 ## If issue number provided ($1):
 1. **Fetch the issue** details
@@ -388,7 +394,7 @@ Use the gitea, backlog-grooming, and issue-writing skills.
 **Key patterns:**
 - **Optional argument**: `[issue-number]` with brackets
 - **Mode switching**: Different behavior based on argument presence
-- **Explicit skill reference**: "Use the gitea, backlog-grooming and issue-writing skills"
+- **Skill file references**: Uses `@~/.claude/skills/` to include multiple skills
 - **Approval workflow**: "Ask user if they want to apply changes"
 - **Categorization**: Groups items for presentation
 
@@ -402,7 +408,9 @@ argument-hint: <feature-description>
 
 # Plan Feature: $1
 
-Use the gitea, roadmap-planning, and issue-writing skills.
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/roadmap-planning/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
 
 1. **Understand the feature**: Analyze what "$1" involves
 2. **Explore the codebase** if needed to understand context
@@ -422,7 +430,7 @@ Use the gitea, roadmap-planning, and issue-writing skills.
 ```
 
 **Key patterns:**
-- **Multi-skill composition**: References three skills together
+- **Multi-skill composition**: Includes three skills via `@~/.claude/skills/`
 - **Codebase exploration**: May need to understand context
 - **Structured output**: Template for presenting the plan
 - **Two-phase execution**: Plan first, then execute after approval
@@ -438,7 +446,7 @@ argument-hint: <pr-number>
 
 # Review PR #$1
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 1. **View PR details** including description and metadata
 2. **Get the diff** to review the changes
@@ -641,7 +649,7 @@ Update references:
 - [ ] Frontmatter includes argument-hint (if arguments needed)
 - [ ] Workflow steps are clear and numbered
 - [ ] Commands and tools are specified explicitly
-- [ ] Skills are referenced where methodology matters
+- [ ] Skills are included via `@~/.claude/skills/<name>/SKILL.md` file references
 - [ ] Approval points exist before significant actions
 - [ ] Edge cases are handled (no data, invalid input)
 - [ ] Output formatting is specified