flowmade-one/architecture
3
0
Fork 0
Code Issues 20 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Use @ file references to include skills in commands

Browse Source 
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>
This commit is contained in:
HugoNijhuis
2026-01-01 11:09:26 +01:00
co-authored by Claude Opus 4.5
parent f4f97d6fec
commit 3a6de6f37d
8 changed files with 48 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
commands/create-issue.md
+1 -1
View File
@@ -5,7 +5,7 @@ argument-hint: [title] or "batch"
# Create Issue(s) # Create Issue(s)
Use the gitea skill. @~/.claude/skills/gitea/SKILL.md
## Single Issue (default) ## Single Issue (default)
If title provided, create an issue with that title and ask for description. If title provided, create an issue with that title and ask for description.
commands/dashboard.md
+1 -1
View File
@@ -4,7 +4,7 @@ description: Show dashboard of open issues, PRs awaiting review, and CI status.
# Repository Dashboard # Repository Dashboard
Use the gitea skill. @~/.claude/skills/gitea/SKILL.md
Fetch and display: Fetch and display:
1. All open issues 1. All open issues
commands/groom.md
+3 -1
View File
@@ -5,7 +5,9 @@ argument-hint: [issue-number]
# Groom Issues # 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): ## If issue number provided ($1):
commands/plan-issues.md
+3 -1
View File
@@ -5,7 +5,9 @@ argument-hint: <feature-description>
# Plan Feature: $1 # 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 1. **Understand the feature**: Analyze what "$1" involves
2. **Explore the codebase** if needed to understand context 2. **Explore the codebase** if needed to understand context
commands/review-pr.md
+1 -1
View File
@@ -5,7 +5,7 @@ argument-hint: <pr-number>
# Review PR #$1 # Review PR #$1
Use the gitea skill. @~/.claude/skills/gitea/SKILL.md
1. **View PR details** including description and metadata 1. **View PR details** including description and metadata
2. **Get the diff** to review the changes 2. **Get the diff** to review the changes
commands/roadmap.md
+1 -1
View File
@@ -4,7 +4,7 @@ description: View current issues as a roadmap. Shows open issues organized by st
# Roadmap View # Roadmap View
Use the gitea skill. @~/.claude/skills/gitea/SKILL.md
1. **Fetch all open issues** 1. **Fetch all open issues**
2. **Analyze dependencies** from issue descriptions 2. **Analyze dependencies** from issue descriptions
commands/work-issue.md
+1 -1
View File
@@ -5,7 +5,7 @@ argument-hint: <issue-number>
# Work on Issue #$1 # Work on Issue #$1
Use the gitea skill. @~/.claude/skills/gitea/SKILL.md
1. **View the issue** to understand requirements 1. **View the issue** to understand requirements
2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>` 2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
docs/writing-commands.md
+37 -29
View File
@@ -72,7 +72,7 @@ argument-hint: <issue-number>
# Work on Issue #$1 # Work on Issue #$1
Use the gitea skill. @~/.claude/skills/gitea/SKILL.md
1. **View the issue** to understand requirements 1. **View the issue** to understand requirements
2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>` 2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
@@ -138,7 +138,7 @@ argument-hint: [issue-number]
# Groom Issues # Groom Issues
Use the gitea skill. @~/.claude/skills/gitea/SKILL.md
## If issue number provided ($1): ## If issue number provided ($1):
1. **Fetch the issue** details 1. **Fetch the issue** details
@@ -163,7 +163,7 @@ argument-hint: [title] or "batch"
# Create Issue(s) # Create Issue(s)
Use the gitea skill. @~/.claude/skills/gitea/SKILL.md
## Single Issue (default) ## Single Issue (default)
If title provided, create an issue with that title. If title provided, create an issue with that title.
@@ -176,41 +176,45 @@ If $1 is "batch":
4. Create each issue 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 ```markdown
# Groom Issues # 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 1. **Fetch the issue** details
2. **Evaluate** against grooming checklist 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 | Pattern | Behavior |
1. **Fetch the issue** details |---------|----------|
``` | `@~/.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 | Include explicitly | Skip skill reference |
|-------------------|---------------------|
| Reference explicitly | Reference implicitly | | CLI syntax is needed | Well-known commands |
|---------------------|---------------------| | Core methodology required | Simple operations |
| Core methodology is needed | Just using a tool | | Quality standards matter | One-off actions |
| Quality standards matter | Simple operations | | Patterns should be followed | No domain knowledge needed |
| Patterns should be followed | Well-known commands |
## Invoking Agents ## Invoking Agents
@@ -313,7 +317,7 @@ argument-hint: <issue-number>
# Work on Issue #$1 # Work on Issue #$1
Use the gitea skill. @~/.claude/skills/gitea/SKILL.md
1. **View the issue** to understand requirements 1. **View the issue** to understand requirements
2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>` 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 # Repository Dashboard
Use the gitea skill. @~/.claude/skills/gitea/SKILL.md
Fetch and display: Fetch and display:
1. All open issues 1. All open issues
@@ -365,7 +369,9 @@ argument-hint: [issue-number]
# Groom Issues # 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): ## If issue number provided ($1):
1. **Fetch the issue** details 1. **Fetch the issue** details
@@ -388,7 +394,7 @@ Use the gitea, backlog-grooming, and issue-writing skills.
**Key patterns:** **Key patterns:**
- **Optional argument**: `[issue-number]` with brackets - **Optional argument**: `[issue-number]` with brackets
- **Mode switching**: Different behavior based on argument presence - **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" - **Approval workflow**: "Ask user if they want to apply changes"
- **Categorization**: Groups items for presentation - **Categorization**: Groups items for presentation
@@ -402,7 +408,9 @@ argument-hint: <feature-description>
# Plan Feature: $1 # 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 1. **Understand the feature**: Analyze what "$1" involves
2. **Explore the codebase** if needed to understand context 2. **Explore the codebase** if needed to understand context
@@ -422,7 +430,7 @@ Use the gitea, roadmap-planning, and issue-writing skills.
``` ```
**Key patterns:** **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 - **Codebase exploration**: May need to understand context
- **Structured output**: Template for presenting the plan - **Structured output**: Template for presenting the plan
- **Two-phase execution**: Plan first, then execute after approval - **Two-phase execution**: Plan first, then execute after approval
@@ -438,7 +446,7 @@ argument-hint: <pr-number>
# Review PR #$1 # Review PR #$1
Use the gitea skill. @~/.claude/skills/gitea/SKILL.md
1. **View PR details** including description and metadata 1. **View PR details** including description and metadata
2. **Get the diff** to review the changes 2. **Get the diff** to review the changes
@@ -641,7 +649,7 @@ Update references:
- [ ] Frontmatter includes argument-hint (if arguments needed) - [ ] Frontmatter includes argument-hint (if arguments needed)
- [ ] Workflow steps are clear and numbered - [ ] Workflow steps are clear and numbered
- [ ] Commands and tools are specified explicitly - [ ] 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 - [ ] Approval points exist before significant actions
- [ ] Edge cases are handled (no data, invalid input) - [ ] Edge cases are handled (no data, invalid input)
- [ ] Output formatting is specified - [ ] Output formatting is specified