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

Improve skill descriptions and documentation

Browse Source 
Updated all skill descriptions with proper trigger terms following
the pattern: "What it does. Use when [trigger terms]."

Skills updated:
- code-review: triggers on PR review, code quality, bugs, security
- issue-writing: triggers on creating issues, bug reports, features
- backlog-grooming: triggers on grooming, reviewing issue quality
- roadmap-planning: triggers on planning features, breaking down work

Updated docs/writing-skills.md:
- Added YAML frontmatter requirements section
- Documented required and optional fields
- Added guidance on writing effective descriptions
- Updated "How Skills are Loaded" to reflect model-invoked behavior
- Added note about subagent skill access
- Updated checklist with frontmatter requirements
- Added reference to official documentation

🤖 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 10:30:04 +01:00
parent d16332e552
commit 98796ba537
5 changed files with 100 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
docs/writing-skills.md
View File

@@ -2,11 +2,77 @@
A guide to creating reusable knowledge modules for the Claude Code AI workflow system.
> **Official Documentation**: For the most up-to-date information, see https://code.claude.com/docs/en/skills
## What is a Skill?
Skills are **knowledge modules**—focused documents that teach Claude how to do something well. Unlike commands (which define workflows) or agents (which execute tasks), skills are passive: they encode domain expertise, patterns, and best practices that can be referenced when needed.
Skills are **model-invoked knowledge modules**—Claude automatically applies them when your request matches their description. Unlike commands (which require explicit `/command` invocation), skills are triggered automatically based on semantic matching.
Think of skills as the "how-to guides" that inform Claude's work. A skill doesn't act on its own—it provides the knowledge that commands and agents use to complete their tasks effectively.
## YAML Frontmatter (Required)
Every `SKILL.md` file **must** start with YAML frontmatter. This is how Claude discovers and triggers skills.
### Format Requirements
- Must start with `---` on **line 1** (no blank lines before it)
- Must end with `---` before the markdown content
- Use spaces for indentation (not tabs)
### Required Fields
| Field | Required | Description |
|-------|----------|-------------|
| `name` | **Yes** | Lowercase letters, numbers, and hyphens only (max 64 chars). Should match directory name. |
| `description` | **Yes** | What the skill does and when to use it (max 1024 chars). **This is critical for triggering.** |
### Optional Fields
| Field | Description |
|-------|-------------|
| `allowed-tools` | **Restricts** which tools Claude can use when this skill is active. If omitted, no restrictions apply. |
| `model` | Specific model to use when skill is active (e.g., `claude-sonnet-4-20250514`). |
### Writing Effective Descriptions
The `description` field determines when Claude applies the skill. A good description answers:
1. **What does this skill do?** List specific capabilities.
2. **When should Claude use it?** Include trigger terms users would mention.
**Bad (too vague):**
```yaml
description: Helps with documents
```
**Good (specific with trigger terms):**
```yaml
description: View, create, and manage Gitea issues and pull requests using tea CLI. Use when working with issues, PRs, viewing issue details, creating pull requests, adding comments, merging PRs, or when the user mentions tea, gitea, issue numbers, or PR numbers.
```
### Example Frontmatter
```yaml
---
name: gitea
description: View, create, and manage Gitea issues and pull requests using tea CLI. Use when working with issues, PRs, viewing issue details, creating pull requests, or when the user mentions tea, gitea, or issue numbers.
---
# Gitea CLI (tea)
[Rest of skill content...]
```
## Subagents and Skills
Subagents **do not automatically inherit skills** from the main conversation. To give a subagent access to skills, list them in the agent's `skills` field:
```yaml
---
name: code-reviewer
description: Review code for quality and best practices
skills: gitea, code-review
---
```
## File Structure
@@ -77,39 +143,29 @@ Quick-reference tables, checklists, or commands.
Not every skill needs all sections—include what's relevant. Some skills are primarily patterns (like `issue-writing`), others are reference-heavy (like `gitea`).
## How Skills are Loaded
## How Skills are Discovered and Triggered
Skills are loaded by **explicit reference**. When a command or agent mentions a skill by name, Claude reads the skill file to gain that knowledge.
Skills are **model-invoked**: Claude decides which skills to use based on your request.
### Referenced by Commands
### Discovery Process
Commands reference skills in their instructions:
1. **At startup**: Claude loads only the `name` and `description` of each available skill
2. **On request**: Claude matches your request against skill descriptions using semantic similarity
3. **Activation**: When a match is found, Claude asks to use the skill before loading the full content
```markdown
# Groom Issues
### Subagent Access
Use the **backlog-grooming** and **issue-writing** skills to review and improve issues.
Subagents (defined in `.claude/agents/`) must explicitly list which skills they can use:
1. Fetch open issues...
```yaml
---
name: product-manager
description: Manages backlog and roadmap
skills: gitea, issue-writing, backlog-grooming, roadmap-planning
---
```
When this command runs, Claude reads both referenced skills before proceeding.
### Referenced by Agents
Agents list their skills explicitly:
```markdown
# Product Manager Agent
## Skills
- gitea
- issue-writing
- backlog-grooming
- roadmap-planning
```
When spawned, the agent has access to all listed skills as part of its context.
**Important**: Built-in agents and the Task tool do not have access to skills. Only custom subagents with an explicit `skills` field can use them.
### Skills Can Reference Other Skills
@@ -430,14 +486,26 @@ Keep skills current:
## Checklist: Before Submitting a New Skill
### Frontmatter (Critical)
- [ ] YAML frontmatter starts on line 1 (no blank lines before `---`)
- [ ] `name` field uses lowercase letters, numbers, and hyphens only
- [ ] `name` matches the directory name
- [ ] `description` lists specific capabilities
- [ ] `description` includes "Use when..." with trigger terms
### File Structure
- [ ] File is at `skills/<name>/SKILL.md`
- [ ] Name follows kebab-case convention
### Content Quality
- [ ] Skill focuses on a single domain
- [ ] Guidelines are specific and actionable
- [ ] Examples illustrate each major point
- [ ] Templates are provided where appropriate
- [ ] Common mistakes are documented
- [ ] Skill is referenced by at least one command or agent
### Integration
- [ ] Skill is listed in relevant subagent `skills` fields if needed
## See Also

2
skills/backlog-grooming/SKILL.md
View File

@@ -1,6 +1,6 @@
---
name: backlog-grooming
description: How to review and improve existing issues for clarity and actionability
description: Review and improve existing issues for clarity and actionability. Use when grooming the backlog, reviewing issue quality, cleaning up stale issues, or when the user wants to improve existing issues.
---
# Backlog Grooming

2
skills/code-review/SKILL.md
View File

@@ -1,6 +1,6 @@
---
name: code-review
description: Guidelines and templates for reviewing code changes in pull requests
description: Review code for quality, bugs, security, and style issues. Use when reviewing pull requests, checking code quality, looking for bugs or security vulnerabilities, or when the user asks for a code review.
---
# Code Review

2
skills/issue-writing/SKILL.md
View File

@@ -1,6 +1,6 @@
---
name: issue-writing
description: How to write clear, actionable issues with proper structure and acceptance criteria
description: Write clear, actionable issues with proper structure and acceptance criteria. Use when creating issues, writing bug reports, feature requests, or when the user needs help structuring an issue.
---
# Issue Writing

2
skills/roadmap-planning/SKILL.md
View File

@@ -1,6 +1,6 @@
---
name: roadmap-planning
description: How to plan features and create issues for implementation
description: Plan features and break down work into implementable issues. Use when planning a feature, creating a roadmap, breaking down large tasks, or when the user needs help organizing work into issues.
---
# Roadmap Planning