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

Add new frontmatter fields from Claude Code 2.1.0

Browse Source 
Update documentation and apply new frontmatter capabilities:

Documentation:
- Add user-invocable, context, agent, hooks fields to writing-skills.md
- Add disallowedTools, permissionMode, hooks fields to writing-agents.md
- Add model, context, hooks, allowed-tools fields to writing-commands.md
- Document skill hot-reload, built-in agents, background execution

Skills:
- Add user-invocable: false to gitea (CLI reference)
- Add user-invocable: false to repo-conventions (standards reference)

Commands:
- Add context: fork to heavy exploration commands (improve, plan-issues,
  create-repo, update-claude-md)
- Add missing argument-hint to roadmap, manifesto, improve

Agents:
- Add disallowedTools: [Edit, Write] to code-reviewer for safety

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Hugo Nijhuis
2026-01-08 14:19:56 +01:00
parent 1f1d9961fc
commit d980a0d0bc
12 changed files with 273 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
docs/writing-skills.md
View File

@@ -29,8 +29,12 @@ Every `SKILL.md` file **must** start with YAML frontmatter. This is how Claude d
| 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`). |
| `allowed-tools` | **Restricts** which tools Claude can use when this skill is active. If omitted, no restrictions apply. Supports YAML-style lists. |
| `model` | Specific model to use when skill is active (e.g., `sonnet`, `opus`, `haiku`). |
| `user-invocable` | Whether the skill appears in the `/` command menu. Defaults to `true`. Set to `false` for reference-only skills. |
| `context` | Execution context. Use `fork` to run skill in an isolated sub-agent context, preventing context pollution. |
| `agent` | Agent type to use for execution. Allows skills to specify which agent handles them. |
| `hooks` | Define PreToolUse, PostToolUse, or Stop hooks scoped to this skill's lifecycle. |
### Writing Effective Descriptions
@@ -55,6 +59,7 @@ description: View, create, and manage Gitea issues and pull requests using tea C
---
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.
user-invocable: false
---
# Gitea CLI (tea)
@@ -62,6 +67,51 @@ description: View, create, and manage Gitea issues and pull requests using tea C
[Rest of skill content...]
```
### Advanced Frontmatter Examples
**Reference skill (not directly invocable):**
```yaml
---
name: gitea
description: CLI reference for Gitea operations.
user-invocable: false
---
```
**Skill with isolated context:**
```yaml
---
name: codebase-analysis
description: Deep codebase exploration and analysis.
context: fork
model: haiku
---
```
**Skill with tool restrictions (YAML-style list):**
```yaml
---
name: read-only-review
description: Code review without modifications.
allowed-tools:
- Read
- Glob
- Grep
---
```
**Skill with hooks:**
```yaml
---
name: database-operations
description: Database schema and migration operations.
hooks:
- type: PreToolUse
matcher: Bash
command: echo "Validating database command..."
---
```
## 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:
@@ -153,6 +203,14 @@ Skills are **model-invoked**: Claude decides which skills to use based on your r
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
### Hot Reload
Skills support **automatic hot-reload**. When you create or modify a skill file in `~/.claude/skills/` or `.claude/skills/`, the changes are immediately available without restarting Claude Code. This enables rapid iteration when developing skills.
### Visibility in Command Menu
By default, skills in `/skills/` directories appear in the `/` slash command menu. Users can invoke them directly like commands. To hide a skill from the menu (e.g., for reference-only skills), add `user-invocable: false` to the frontmatter.
### Subagent Access
Subagents (defined in `.claude/agents/`) must explicitly list which skills they can use:
@@ -493,6 +551,13 @@ Keep skills current:
- [ ] `description` lists specific capabilities
- [ ] `description` includes "Use when..." with trigger terms
### Optional Frontmatter (Consider)
- [ ] `user-invocable: false` if skill is reference-only (e.g., CLI docs)
- [ ] `context: fork` if skill does heavy exploration that would pollute context
- [ ] `model` if skill benefits from a specific model (e.g., `haiku` for speed)
- [ ] `allowed-tools` if skill should be restricted to certain tools
- [ ] `hooks` if skill needs validation or logging
### File Structure
- [ ] File is at `skills/<name>/SKILL.md`
- [ ] Name follows kebab-case convention