From b8ca2386fa6881541015c4f3abc6972cb15d5ca5 Mon Sep 17 00:00:00 2001 From: Hugo Nijhuis Date: Thu, 1 Jan 2026 11:09:26 +0100 Subject: [PATCH] Use @ file references to include skills in commands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- commands/create-issue.md | 2 +- commands/dashboard.md | 2 +- commands/groom.md | 4 ++- commands/plan-issues.md | 4 ++- commands/review-pr.md | 2 +- commands/roadmap.md | 2 +- commands/work-issue.md | 2 +- docs/writing-commands.md | 66 ++++++++++++++++++++++------------------ 8 files changed, 48 insertions(+), 36 deletions(-) diff --git a/commands/create-issue.md b/commands/create-issue.md index f52a487..41103ed 100644 --- a/commands/create-issue.md +++ b/commands/create-issue.md @@ -5,7 +5,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 and ask for description. diff --git a/commands/dashboard.md b/commands/dashboard.md index 3efa708..80e9e1f 100644 --- a/commands/dashboard.md +++ b/commands/dashboard.md @@ -4,7 +4,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 diff --git a/commands/groom.md b/commands/groom.md index 59eeb04..390b5b7 100644 --- a/commands/groom.md +++ b/commands/groom.md @@ -5,7 +5,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): diff --git a/commands/plan-issues.md b/commands/plan-issues.md index 5a7663f..31e247d 100644 --- a/commands/plan-issues.md +++ b/commands/plan-issues.md @@ -5,7 +5,9 @@ argument-hint: # 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 diff --git a/commands/review-pr.md b/commands/review-pr.md index 7c83361..aeedeae 100644 --- a/commands/review-pr.md +++ b/commands/review-pr.md @@ -5,7 +5,7 @@ argument-hint: # 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 diff --git a/commands/roadmap.md b/commands/roadmap.md index 90d6efe..fc15b11 100644 --- a/commands/roadmap.md +++ b/commands/roadmap.md @@ -4,7 +4,7 @@ description: View current issues as a roadmap. Shows open issues organized by st # Roadmap View -Use the gitea skill. +@~/.claude/skills/gitea/SKILL.md 1. **Fetch all open issues** 2. **Analyze dependencies** from issue descriptions diff --git a/commands/work-issue.md b/commands/work-issue.md index da4935c..09ac81d 100644 --- a/commands/work-issue.md +++ b/commands/work-issue.md @@ -5,7 +5,7 @@ argument-hint: # 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-` diff --git a/docs/writing-commands.md b/docs/writing-commands.md index 9a0ebb7..2300bf1 100644 --- a/docs/writing-commands.md +++ b/docs/writing-commands.md @@ -72,7 +72,7 @@ argument-hint: # 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-` @@ -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: # 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-` @@ -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: # 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: # 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//SKILL.md` file references - [ ] Approval points exist before significant actions - [ ] Edge cases are handled (no data, invalid input) - [ ] Output formatting is specified