flowmade-one/architecture
3
0
Fork 0
Code Issues 15 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:
Hugo Nijhuis
2026-01-01 11:09:26 +01:00
parent 98796ba537
commit b8ca2386fa
8 changed files with 48 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
commands/create-issue.md
View File

@@ -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.

2
commands/dashboard.md
View File

@@ -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

4
commands/groom.md
View File

@@ -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):

4
commands/plan-issues.md
View File

@@ -5,7 +5,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

2
commands/review-pr.md
View File

@@ -5,7 +5,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

2
commands/roadmap.md
View File

@@ -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

2
commands/work-issue.md
View File

@@ -5,7 +5,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>`

66
docs/writing-commands.md
View File

@@ -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