Add new frontmatter fields from Claude Code 2.1.0

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>

agents/code-reviewer/AGENT.md

@@ -5,6 +5,9 @@ description: Automated code review of pull requests. Reviews PRs for quality, bu
 # The structured output format doesn't require opus-level reasoning.
 model: sonnet
 skills: gitea, code-review
+disallowedTools:
+  - Edit
+  - Write
 ---
 
 You are a code review specialist that provides immediate, structured feedback on pull request changes.

commands/create-repo.md

@@ -1,6 +1,7 @@
 ---
 description: Create a new repository with standard structure. Scaffolds vision.md, CLAUDE.md, and CI configuration.
 argument-hint: <repo-name>
+context: fork
 ---
 
 # Create Repository

commands/improve.md

@@ -1,5 +1,7 @@
 ---
 description: Identify improvement opportunities based on product vision. Analyzes gaps between vision goals and current backlog.
+argument-hint:
+context: fork
 ---
 
 # Improvement Analysis

commands/manifesto.md

@@ -1,5 +1,6 @@
 ---
 description: View and manage the organization manifesto. Shows identity, personas, beliefs, and principles.
+argument-hint:
 ---
 
 # Organization Manifesto

commands/plan-issues.md

@@ -1,6 +1,7 @@
 ---
 description: Plan and create issues for a feature or improvement. Breaks down work into well-structured issues with vision alignment.
 argument-hint: <feature-description>
+context: fork
 ---
 
 # Plan Feature: $1

commands/roadmap.md

@@ -1,5 +1,6 @@
 ---
 description: View current issues as a roadmap. Shows open issues organized by status and dependencies.
+argument-hint:
 ---
 
 # Roadmap View

commands/update-claude-md.md

@@ -1,6 +1,7 @@
 ---
 description: Update or create CLAUDE.md with current project context. Explores the project and ensures organization context is present.
 argument-hint:
+context: fork
 ---
 
 # Update CLAUDE.md

docs/writing-agents.md

@@ -67,6 +67,90 @@ All sections are important:
 - **When to Use**: Prevents misuse and guides selection
 - **Behavior**: Sets expectations for operation
 
+## YAML Frontmatter
+
+Agent files support YAML frontmatter for configuration. While the body content defines the agent's personality and instructions, frontmatter controls its technical behavior.
+
+### Required Fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Agent identifier (lowercase, hyphens). Should match directory name. |
+| `description` | What the agent does. Used for matching when spawning agents. |
+
+### Optional Fields
+
+| Field | Description |
+|-------|-------------|
+| `model` | Model to use: `haiku`, `sonnet`, `opus`, or `inherit` (default). |
+| `skills` | Comma-separated list of skills the agent can access. |
+| `disallowedTools` | Explicitly block specific tools from this agent. |
+| `permissionMode` | Permission behavior: `default`, `bypassPermissions`, or custom. |
+| `hooks` | Define PreToolUse, PostToolUse, or Stop hooks scoped to this agent. |
+
+### Example Frontmatter
+
+**Basic agent:**
+```yaml
+---
+name: code-reviewer
+description: Review code for quality, bugs, and style issues.
+model: sonnet
+skills: gitea, code-review
+---
+```
+
+**Agent with tool restrictions:**
+```yaml
+---
+name: read-only-analyst
+description: Analyze code without making changes.
+model: haiku
+skills: code-review
+disallowedTools:
+  - Edit
+  - Write
+  - Bash
+---
+```
+
+**Agent with hooks:**
+```yaml
+---
+name: database-admin
+description: Manage database operations safely.
+model: opus
+hooks:
+  - type: PreToolUse
+    matcher: Bash
+    command: echo "Validating database command..."
+  - type: Stop
+    command: echo "Database operation completed"
+---
+```
+
+### Permission Modes
+
+The `permissionMode` field controls how the agent handles tool permissions:
+
+| Mode | Behavior |
+|------|----------|
+| `default` | Inherits parent's permission settings (standard behavior) |
+| `bypassPermissions` | Skip permission prompts (use for trusted, well-tested agents) |
+
+Use `bypassPermissions` sparingly—only for agents that are thoroughly tested and operate within safe boundaries.
+
+## Built-in Agents
+
+Claude Code provides built-in agents that you can leverage instead of creating custom ones:
+
+| Agent | Purpose | When to Use |
+|-------|---------|-------------|
+| **Explore** | Codebase exploration and search | Finding files, understanding structure, searching code. Powered by Haiku for efficiency. |
+| **Plan** | Implementation planning | Designing approaches, breaking down tasks, architectural decisions. |
+
+Consider using built-in agents before creating custom ones—they're optimized for common tasks.
+
 ## How Agents Combine Skills
 
 Agents gain their expertise by combining multiple skills. Each skill contributes domain knowledge to the agent's overall capability.
@@ -187,6 +271,28 @@ Agents can explore codebases independently, building understanding without pollu
 - Exploration might involve many file reads and searches
 - Results should be summarized, not shown in full
 
+### 5. Background Execution
+
+Agents can run in the background while you continue working. Background agents execute asynchronously and notify the main thread when complete.
+
+```
+User working                    Background Agent
+┌─────────────────┐            ┌─────────────────┐
+│ Continue coding │            │ Running tests   │
+│ on feature      │            │ in background   │
+│                 │            │                 │
+│ (not blocked)   │   notify   │ (async work)    │
+│                 │ ◄───────── │                 │
+└─────────────────┘            └─────────────────┘
+```
+
+**Use when:**
+- Task is long-running (test suites, large codebase analysis)
+- You want to continue working while the agent operates
+- Results are needed later, not immediately
+
+Background agents can send messages to wake up the main agent when they have results or need attention.
+
 ## When to Use an Agent vs Direct Skill Invocation
 
 ### Use Direct Skill Invocation When:
@@ -573,14 +679,26 @@ Improve based on usage:
 
 ## Checklist: Before Submitting a New Agent
 
+### Structure
 - [ ] File is at `agents/<name>/AGENT.md`
 - [ ] Name follows kebab-case convention
 - [ ] Agent has a clear, recognizable role
-- [ ] Skills list is deliberate (not too many, not too few)
+
-- [ ] Model selection is deliberate (not just `inherit` by default)
+### Frontmatter
+- [ ] `name` and `description` fields are set
+- [ ] `model` selection is deliberate (not just `inherit` by default)
+- [ ] `skills` list is deliberate (not too many, not too few)
+- [ ] Consider `disallowedTools` if agent should be restricted
+- [ ] Consider `permissionMode` for trusted agents
+- [ ] Consider `hooks` for validation or logging
+
+### Content
 - [ ] Capabilities are specific and achievable
 - [ ] "When to Use" guidance is clear
 - [ ] Behavioral rules prevent problems
+
+### Integration
+- [ ] Consider if built-in agents (Explore, Plan) could be used instead
 - [ ] Agent is referenced by at least one command
 - [ ] ARCHITECTURE.md is updated
 

docs/writing-commands.md

@@ -43,10 +43,21 @@ argument-hint: <required-arg> [optional-arg]
 ---
 ```
 
-| Field | Purpose | Required |
+#### Required Fields
-|-------|---------|----------|
+
-| `description` | One-line summary for help/listings | Yes |
+| Field | Purpose |
-| `argument-hint` | Shows expected arguments | If arguments needed |
+|-------|---------|
+| `description` | One-line summary for help/listings |
+
+#### Optional Fields
+
+| Field | Purpose |
+|-------|---------|
+| `argument-hint` | Shows expected arguments (e.g., `<issue-number>`, `[title]`) |
+| `model` | Model to use: `haiku`, `sonnet`, `opus`. Overrides session default. |
+| `context` | Execution context. Use `fork` to run in isolated sub-agent context. |
+| `hooks` | Define PreToolUse, PostToolUse, or Stop hooks scoped to this command. |
+| `allowed-tools` | Restrict which tools the command can use. |
 
 ### 2. Body (Markdown Instructions)
 
@@ -83,6 +94,50 @@ argument-hint: <issue-number>
 7. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
 ```
 
+## Advanced Frontmatter Examples
+
+**Command with specific model:**
+```yaml
+---
+description: Plan complex feature implementation.
+argument-hint: <feature-description>
+model: opus
+---
+```
+
+**Command with isolated context (prevents context pollution):**
+```yaml
+---
+description: Analyze codebase architecture deeply.
+context: fork
+model: haiku
+---
+```
+
+**Command with hooks:**
+```yaml
+---
+description: Deploy to production environment.
+hooks:
+  - type: PreToolUse
+    matcher: Bash
+    command: echo "Validating deployment command..."
+  - type: Stop
+    command: ./scripts/notify-deployment.sh
+---
+```
+
+**Read-only command with tool restrictions:**
+```yaml
+---
+description: Generate codebase report without modifications.
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+---
+```
+
 ## Argument Handling
 
 Commands can accept arguments from the user. Arguments are passed via positional variables: `$1`, `$2`, etc.
@@ -643,16 +698,29 @@ Update references:
 
 ## Checklist: Before Submitting a New Command
 
+### Structure
 - [ ] File is at `commands/<name>.md`
 - [ ] Name follows kebab-case verb convention
-- [ ] Frontmatter includes description
+
-- [ ] Frontmatter includes argument-hint (if arguments needed)
+### Frontmatter (Required)
+- [ ] `description` is set with clear one-line summary
+- [ ] `argument-hint` is set (if command takes arguments)
+
+### Frontmatter (Consider)
+- [ ] `model` if command benefits from specific model (e.g., `opus` for complex planning)
+- [ ] `context: fork` if command does heavy exploration that would pollute context
+- [ ] `allowed-tools` if command should be restricted to certain tools
+- [ ] `hooks` if command needs validation or post-execution actions
+
+### Content
 - [ ] Workflow steps are clear and numbered
 - [ ] Commands and tools are specified explicitly
 - [ ] 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
+
+### Integration
 - [ ] ARCHITECTURE.md is updated with new command
 
 ## See Also

docs/writing-skills.md

@@ -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. |
+| `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., `claude-sonnet-4-20250514`). |
+| `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

skills/gitea/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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, adding comments, merging PRs, or when the user mentions tea, gitea, issue numbers, or PR numbers.
+user-invocable: false
 ---
 
 # Gitea CLI (tea)

skills/repo-conventions/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: repo-conventions
 description: Standard structure and conventions for Flowmade repositories. Use when creating new repos, reviewing repo structure, or setting up projects.
+user-invocable: false
 ---
 
 # Repository Conventions