📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,425 @@
|
||||
---
|
||||
name: claude-skills
|
||||
description: This skill should be used when creating Claude Code skills with Claude-specific features like allowed-tools, context modes (fork/inherit), argument-hint, or model overrides. Triggers on "Claude skill", "allowed-tools", "context fork", "skill arguments".
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
related-skills:
|
||||
- skills-dev
|
||||
- claude-plugins
|
||||
- claude-commands
|
||||
- claude-hooks
|
||||
allowed-tools: Read Write Edit Grep Glob Bash TaskCreate TaskUpdate TaskList TaskGet
|
||||
---
|
||||
|
||||
# Claude Code Skills
|
||||
|
||||
## Steps
|
||||
|
||||
1. Load the `outfitter:skills-dev` skill
|
||||
2. Consider the Claude Code-specific features that extend the base specification within this skill
|
||||
|
||||
## Frontmatter Extensions
|
||||
|
||||
Claude Code extends the base Agent Skills frontmatter:
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `allowed-tools` | string | Space-separated tools that run without permission prompts |
|
||||
| `user-invocable` | boolean | Default `true`. Set `false` to prevent `/skill-name` access |
|
||||
| `disable-model-invocation` | boolean | Prevents auto-activation; requires manual Skill tool invocation |
|
||||
| `context` | string | `inherit` (default) or `fork` for isolated subagent execution |
|
||||
| `agent` | string | Agent for `context: fork` (e.g., `Explore`, `outfitter:analyst`) |
|
||||
| `model` | string | Override model: `haiku`, `sonnet`, or `opus` |
|
||||
| `hooks` | object | Lifecycle hooks: `on-activate`, `on-complete` |
|
||||
| `argument-hint` | string | Hint shown after `/skill-name` (e.g., `[file path]`) |
|
||||
|
||||
### Example
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: code-review
|
||||
version: 1.0.0
|
||||
description: Reviews code for bugs, security, and best practices. Use when reviewing PRs, auditing code, or before merging.
|
||||
allowed-tools: Read Grep Glob Bash(git diff *)
|
||||
argument-hint: [file or directory]
|
||||
model: sonnet
|
||||
---
|
||||
```
|
||||
|
||||
## Tool Restrictions
|
||||
|
||||
Use `allowed-tools` to specify which tools run without permission prompts.
|
||||
|
||||
### Syntax
|
||||
|
||||
```yaml
|
||||
# Space-separated list
|
||||
allowed-tools: Read Grep Glob
|
||||
|
||||
# With Bash patterns
|
||||
allowed-tools: Read Write Bash(git *) Bash(npm run *)
|
||||
|
||||
# MCP tools (double underscore format)
|
||||
allowed-tools: Read mcp__linear__create_issue mcp__memory__store
|
||||
```
|
||||
|
||||
### Bash Pattern Syntax
|
||||
|
||||
| Pattern | Meaning | Example |
|
||||
|---------|---------|---------|
|
||||
| `Bash(git *)` | All git commands | `git status`, `git commit` |
|
||||
| `Bash(git add:*)` | Specific subcommand | `git add .`, `git add file.ts` |
|
||||
| `Bash(npm run *:*)` | Nested patterns | `npm run test:unit` |
|
||||
|
||||
### Common Patterns
|
||||
|
||||
```yaml
|
||||
# Read-only analysis
|
||||
allowed-tools: Read Grep Glob
|
||||
|
||||
# File modifications
|
||||
allowed-tools: Read Edit Write
|
||||
|
||||
# Git operations
|
||||
allowed-tools: Read Write Bash(git *)
|
||||
|
||||
# Testing workflows
|
||||
allowed-tools: Read Write Bash(bun test:*) Bash(npm test:*)
|
||||
|
||||
# Full development
|
||||
allowed-tools: Read Edit Write Bash(git *) Bash(bun *) Bash(npm *)
|
||||
```
|
||||
|
||||
### Tool Names (Case-Sensitive)
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `Read` | Read files |
|
||||
| `Write` | Write new files |
|
||||
| `Edit` | Edit existing files |
|
||||
| `Grep` | Search file contents |
|
||||
| `Glob` | Find files by pattern |
|
||||
| `Bash` | Execute bash commands |
|
||||
| `WebFetch` | Fetch web content |
|
||||
| `WebSearch` | Search the web |
|
||||
|
||||
---
|
||||
|
||||
## User Invocable Skills
|
||||
|
||||
Skills are callable as `/skill-name` by default. Use `user-invocable: false` for auto-activate-only skills.
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: code-review
|
||||
description: Reviews code for bugs and best practices...
|
||||
argument-hint: [file or PR number]
|
||||
---
|
||||
```
|
||||
|
||||
Users invoke with `/code-review src/auth.ts` or wait for auto-activation.
|
||||
|
||||
### Disabling Slash Command Access
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: internal-validator
|
||||
description: Validates internal state when specific patterns are detected...
|
||||
user-invocable: false
|
||||
---
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
The `argument-hint` field provides context in the command picker:
|
||||
|
||||
```yaml
|
||||
argument-hint: [error message or bug description]
|
||||
```
|
||||
|
||||
Arguments available via `$ARGUMENTS` in skill body.
|
||||
|
||||
---
|
||||
|
||||
## String Substitutions
|
||||
|
||||
| Pattern | Replaced With |
|
||||
|---------|---------------|
|
||||
| `$ARGUMENTS` | User input after `/skill-name` |
|
||||
| `${CLAUDE_SESSION_ID}` | Current session identifier |
|
||||
| `${CLAUDE_PLUGIN_ROOT}` | Path to the plugin root directory |
|
||||
|
||||
### Example
|
||||
|
||||
```markdown
|
||||
# Debug Skill
|
||||
|
||||
Investigating: $ARGUMENTS
|
||||
|
||||
Session: ${CLAUDE_SESSION_ID}
|
||||
|
||||
Use the debugging script:
|
||||
${CLAUDE_PLUGIN_ROOT}/scripts/debug-helper.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dynamic Context Injection
|
||||
|
||||
Use backtick-command syntax to inject dynamic content:
|
||||
|
||||
```markdown
|
||||
## Current Git Status
|
||||
|
||||
`git status`
|
||||
|
||||
## Recent Changes
|
||||
|
||||
`git log --oneline -5`
|
||||
```
|
||||
|
||||
Commands execute when Claude loads the skill; output replaces the syntax.
|
||||
|
||||
**Use cases**: Current branch state, environment info, dynamic config, recent history.
|
||||
|
||||
---
|
||||
|
||||
## Context Modes
|
||||
|
||||
The `context` field controls execution environment.
|
||||
|
||||
### inherit (default)
|
||||
|
||||
Skill runs in main conversation context with access to history and prior tool results.
|
||||
|
||||
```yaml
|
||||
context: inherit
|
||||
```
|
||||
|
||||
### fork
|
||||
|
||||
Skill runs in isolated subagent context. Useful for:
|
||||
- Preventing context pollution
|
||||
- Parallel execution
|
||||
- Specialized processing that shouldn't affect main conversation
|
||||
|
||||
```yaml
|
||||
context: fork
|
||||
agent: outfitter:analyst
|
||||
model: haiku
|
||||
```
|
||||
|
||||
When `context: fork`, specify:
|
||||
- `agent`: Which agent handles the fork
|
||||
- `model`: Override model for forked context
|
||||
|
||||
**In Steps sections**: Use "delegate by loading" language for delegated skills (they run agents, not load instructions):
|
||||
|
||||
```markdown
|
||||
3. Delegate by loading the `outfitter:security-audit` skill for vulnerability scan
|
||||
```
|
||||
|
||||
See [context-modes.md](references/context-modes.md) for patterns.
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
claude --debug
|
||||
```
|
||||
|
||||
Debug output shows:
|
||||
- `Loaded skill: skill-name from path` — Skill discovered
|
||||
- `Error loading skill: reason` — Loading failed
|
||||
- `Considering skill: skill-name` — Activation evaluated
|
||||
- `Skill allowed-tools: [list]` — Tool restrictions applied
|
||||
|
||||
### Testing Process
|
||||
|
||||
1. **Verify loading**: `claude --debug` and check for load messages
|
||||
2. **Test discovery**: Ask something that should trigger the skill
|
||||
3. **Verify tool restrictions**: Confirm permitted tools run without prompts
|
||||
4. **Test with real data**: Run actual workflows
|
||||
|
||||
### Force Skill Reload
|
||||
|
||||
Skills are cached per session. To reload after changes:
|
||||
|
||||
```
|
||||
/clear
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Skill Not Loading
|
||||
|
||||
Check file location:
|
||||
|
||||
```bash
|
||||
# Personal skills
|
||||
ls ~/.claude/skills/my-skill/SKILL.md
|
||||
|
||||
# Project skills
|
||||
ls .claude/skills/my-skill/SKILL.md
|
||||
|
||||
# Plugin skills
|
||||
ls <plugin-path>/skills/my-skill/SKILL.md
|
||||
```
|
||||
|
||||
Validate YAML frontmatter:
|
||||
|
||||
```bash
|
||||
# Check for tabs (YAML requires spaces)
|
||||
grep -P "\t" SKILL.md
|
||||
```
|
||||
|
||||
### Skill Not Activating
|
||||
|
||||
Improve description specificity:
|
||||
|
||||
```yaml
|
||||
# Before (too vague)
|
||||
description: Helps with files
|
||||
|
||||
# After (specific with triggers)
|
||||
description: Parse and validate JSON files including schema validation. Use when working with JSON data, .json files, or configuration files.
|
||||
```
|
||||
|
||||
Add trigger keywords users naturally say: file types (`.pdf`, `.json`), actions (`parse`, `validate`), domains (`API`, `database`).
|
||||
|
||||
### Tool Permission Errors
|
||||
|
||||
Tool names are case-sensitive:
|
||||
|
||||
```yaml
|
||||
# Correct
|
||||
allowed-tools: Read Grep Glob
|
||||
|
||||
# Wrong
|
||||
allowed-tools: read grep glob
|
||||
```
|
||||
|
||||
Bash patterns need wildcards:
|
||||
|
||||
```yaml
|
||||
# Correct
|
||||
allowed-tools: Bash(git *)
|
||||
|
||||
# Wrong (matches nothing)
|
||||
allowed-tools: Bash(git)
|
||||
```
|
||||
|
||||
MCP tools use double underscores:
|
||||
|
||||
```yaml
|
||||
# Correct
|
||||
allowed-tools: mcp__memory__store
|
||||
|
||||
# Wrong
|
||||
allowed-tools: mcp_memory_store
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### With Commands
|
||||
|
||||
Skills activate automatically when commands need their expertise:
|
||||
|
||||
**Command** (`.claude/commands/analyze-pdf.md`):
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Analyze PDF file
|
||||
---
|
||||
|
||||
Analyze this PDF file: $ARGUMENTS
|
||||
|
||||
Use the PDF processing skill for extraction and analysis.
|
||||
```
|
||||
|
||||
### With Hooks
|
||||
|
||||
Hooks can suggest skill usage:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write(*.ts)|Edit(*.ts)",
|
||||
"hooks": [{ "type": "command", "command": "echo 'Consider typescript-linter skill'" }]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Using Skill Tool
|
||||
|
||||
Load skills programmatically:
|
||||
|
||||
```
|
||||
Use the Skill tool to invoke the pdf-processor skill
|
||||
```
|
||||
|
||||
Useful for forcing activation, chaining skills, loading for agents.
|
||||
|
||||
See [integration.md](references/integration.md) for advanced patterns.
|
||||
|
||||
---
|
||||
|
||||
## Master-Clone Architecture
|
||||
|
||||
**For orchestrating specialized work with context isolation:**
|
||||
|
||||
**Master Agent**: Coordinates, maintains conversation context, delegates specialized tasks
|
||||
**Clone Agents**: Isolated context, loads specific skill, returns focused output
|
||||
|
||||
```
|
||||
User request
|
||||
|
|
||||
Master agent decides: needs security analysis
|
||||
|
|
||||
Launch clone agent with security-audit skill
|
||||
|
|
||||
Clone returns findings (only findings in main context)
|
||||
|
|
||||
Master synthesizes and continues
|
||||
```
|
||||
|
||||
### Implementation
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: security-audit
|
||||
context: fork
|
||||
agent: outfitter:reviewer
|
||||
model: sonnet
|
||||
---
|
||||
```
|
||||
|
||||
Or via Task tool:
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "Security audit of auth module",
|
||||
"prompt": "Review src/auth/ for vulnerabilities using security-audit skill",
|
||||
"subagent_type": "outfitter:reviewer",
|
||||
"run_in_background": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
| Reference | Content |
|
||||
|-----------|---------|
|
||||
| [context-modes.md](references/context-modes.md) | Fork vs inherit patterns |
|
||||
| [integration.md](references/integration.md) | Commands, hooks, MCP integration |
|
||||
| [performance.md](references/performance.md) | Token impact, optimization |
|
||||
@@ -0,0 +1,130 @@
|
||||
# Context Modes
|
||||
|
||||
How `context` field controls skill execution environment.
|
||||
|
||||
## inherit (default)
|
||||
|
||||
Skill runs in the main conversation context.
|
||||
|
||||
**Characteristics:**
|
||||
- Access to full conversation history
|
||||
- Prior tool results available
|
||||
- Changes affect main context
|
||||
- Shared memory/state
|
||||
|
||||
**When to use:**
|
||||
- Skills that build on conversation context
|
||||
- Iterative workflows
|
||||
- Skills that need prior decisions/results
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: code-improver
|
||||
context: inherit
|
||||
---
|
||||
```
|
||||
|
||||
## fork
|
||||
|
||||
Skill runs in isolated subagent context.
|
||||
|
||||
**Characteristics:**
|
||||
- Clean context (no conversation history)
|
||||
- Only skill instructions + user input
|
||||
- Results return to main context, but intermediate work doesn't
|
||||
- Can run in parallel
|
||||
|
||||
**When to use:**
|
||||
- Prevent context pollution from verbose analysis
|
||||
- Parallel execution of independent tasks
|
||||
- Specialized processing that shouldn't affect main flow
|
||||
- Security-sensitive operations with limited exposure
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: security-audit
|
||||
context: fork
|
||||
agent: outfitter:reviewer
|
||||
model: sonnet
|
||||
---
|
||||
```
|
||||
|
||||
## Fork Configuration
|
||||
|
||||
When using `context: fork`, additional fields control the subagent:
|
||||
|
||||
| Field | Purpose | Example |
|
||||
|-------|---------|---------|
|
||||
| `agent` | Agent type for the fork | `outfitter:analyst` |
|
||||
| `model` | Model override | `haiku`, `sonnet`, `opus` |
|
||||
|
||||
### Agent Selection
|
||||
|
||||
Choose agents based on the skill's purpose:
|
||||
|
||||
| Agent | Best For |
|
||||
|-------|----------|
|
||||
| `outfitter:analyst` | Research, analysis, synthesis |
|
||||
| `outfitter:reviewer` | Code review, security audit |
|
||||
| `outfitter:engineer` | Implementation, refactoring |
|
||||
| `Explore` | Read-only codebase exploration |
|
||||
|
||||
### Model Selection
|
||||
|
||||
| Model | When to Use |
|
||||
|-------|-------------|
|
||||
| `haiku` | Fast, simple tasks, exploration |
|
||||
| `sonnet` | Balanced (default) |
|
||||
| `opus` | Complex reasoning, nuanced judgment |
|
||||
|
||||
## Patterns
|
||||
|
||||
### Analysis Without Pollution
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: codebase-metrics
|
||||
context: fork
|
||||
agent: outfitter:analyst
|
||||
model: haiku
|
||||
description: Analyzes codebase for metrics without polluting main context
|
||||
---
|
||||
```
|
||||
|
||||
The skill can do extensive file reading and analysis; only the summary returns.
|
||||
|
||||
### Parallel Security Reviews
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: security-scan
|
||||
context: fork
|
||||
agent: outfitter:reviewer
|
||||
model: sonnet
|
||||
---
|
||||
```
|
||||
|
||||
Multiple security scans can run in parallel via `run_in_background: true` in Task tool.
|
||||
|
||||
### Specialized Processing
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: log-analyzer
|
||||
context: fork
|
||||
agent: Explore
|
||||
model: haiku
|
||||
description: Processes large log files without filling main context
|
||||
---
|
||||
```
|
||||
|
||||
## Decision Guide
|
||||
|
||||
| Scenario | Context | Why |
|
||||
|----------|---------|-----|
|
||||
| Building on conversation | `inherit` | Needs prior context |
|
||||
| One-off analysis | `fork` | Keep main context clean |
|
||||
| Verbose intermediate work | `fork` | Prevent pollution |
|
||||
| Parallel execution | `fork` | Independent subagents |
|
||||
| Iterative refinement | `inherit` | Needs state between calls |
|
||||
| Security-sensitive | `fork` | Isolated, controlled exposure |
|
||||
@@ -0,0 +1,272 @@
|
||||
# Integration Patterns
|
||||
|
||||
How skills integrate with commands, hooks, MCP servers, and agents.
|
||||
|
||||
## Skills + Commands
|
||||
|
||||
Commands can trigger skills implicitly through context.
|
||||
|
||||
### Pattern: Command as Entry Point
|
||||
|
||||
**Command** (`.claude/commands/audit-security.md`):
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Run security audit on codebase
|
||||
allowed-tools: Read Grep Glob
|
||||
---
|
||||
|
||||
Perform a security audit focusing on:
|
||||
- Authentication flows
|
||||
- Input validation
|
||||
- SQL injection vectors
|
||||
|
||||
Use the security-audit skill methodology.
|
||||
```
|
||||
|
||||
Claude recognizes the security context and activates the skill automatically.
|
||||
|
||||
### Pattern: Explicit Skill Loading
|
||||
|
||||
**Command**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Review PR with style checks
|
||||
---
|
||||
|
||||
Use the Skill tool to load the code-review skill, then:
|
||||
1. Review changes in the current PR
|
||||
2. Check against style guidelines
|
||||
3. Generate review comments
|
||||
```
|
||||
|
||||
## Skills + Hooks
|
||||
|
||||
Hooks can trigger skill loading or suggest usage.
|
||||
|
||||
### PostToolUse Suggestion
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Edit(*.ts)|Write(*.ts)",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo 'Consider running the typescript-linter skill'"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### PreToolUse Validation
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Write(**/SKILL.md)|Edit(**/SKILL.md)",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-skill.ts"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Stop Hook for Quality Gates
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"Stop": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "bun run lint && bun test"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Skills + MCP Servers
|
||||
|
||||
**Pattern**: Skills provide workflows, MCP servers provide data/tools.
|
||||
|
||||
### Architecture
|
||||
|
||||
- **MCP Server**: Handles authentication, rate limiting, data access
|
||||
- **Skill**: Handles business logic, formatting, workflows
|
||||
|
||||
### Example: Linear Integration
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: linear-standup
|
||||
description: Generates team standup reports from Linear issues
|
||||
allowed-tools: mcp__linear__get_issues mcp__linear__get_projects
|
||||
---
|
||||
|
||||
# Linear Standup
|
||||
|
||||
Use the Linear MCP server to:
|
||||
1. Fetch issues by status and assignee
|
||||
2. Group by project and priority
|
||||
3. Format as standup report
|
||||
```
|
||||
|
||||
### Example: Memory Integration
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: context-saver
|
||||
description: Saves important context to memory for later retrieval
|
||||
allowed-tools: mcp__memory__store mcp__memory__retrieve
|
||||
---
|
||||
|
||||
# Context Saver
|
||||
|
||||
When the user says "remember this" or similar:
|
||||
1. Extract key information
|
||||
2. Store via memory MCP server
|
||||
3. Confirm what was saved
|
||||
```
|
||||
|
||||
## Skills + Agents
|
||||
|
||||
Skills can specify agents for forked execution.
|
||||
|
||||
### Skill-Loaded Agent
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: deep-analysis
|
||||
context: fork
|
||||
agent: outfitter:analyst
|
||||
model: opus
|
||||
description: Deep analysis requiring extensive reasoning
|
||||
---
|
||||
|
||||
# Deep Analysis
|
||||
|
||||
Perform thorough analysis of the given topic...
|
||||
```
|
||||
|
||||
When invoked, skill runs in a forked context using the analyst agent with opus model.
|
||||
|
||||
### Agent Loading Skills
|
||||
|
||||
Agents can load skills for specific capabilities:
|
||||
|
||||
```markdown
|
||||
# Security Reviewer Agent
|
||||
|
||||
When reviewing code:
|
||||
1. Load the security-patterns skill for vulnerability patterns
|
||||
2. Apply patterns to codebase
|
||||
3. Report findings with remediation
|
||||
```
|
||||
|
||||
## Master-Clone Pattern
|
||||
|
||||
Orchestrate specialized work with context isolation.
|
||||
|
||||
```
|
||||
User request
|
||||
|
|
||||
Master agent (main context)
|
||||
|
|
||||
+---> Fork: security-audit skill (isolated)
|
||||
| Returns: findings summary
|
||||
|
|
||||
+---> Fork: performance-analysis skill (isolated)
|
||||
| Returns: performance report
|
||||
|
|
||||
Master synthesizes results
|
||||
|
|
||||
Response to user
|
||||
```
|
||||
|
||||
### Implementation
|
||||
|
||||
**Skill 1** (`security-audit`):
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: security-audit
|
||||
context: fork
|
||||
agent: outfitter:reviewer
|
||||
---
|
||||
```
|
||||
|
||||
**Skill 2** (`performance-analysis`):
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: performance-analysis
|
||||
context: fork
|
||||
agent: outfitter:analyst
|
||||
---
|
||||
```
|
||||
|
||||
**Master agent invokes via Task tool:**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"description": "Security audit",
|
||||
"prompt": "Run security-audit skill on src/auth/",
|
||||
"subagent_type": "outfitter:reviewer",
|
||||
"run_in_background": true
|
||||
},
|
||||
{
|
||||
"description": "Performance analysis",
|
||||
"prompt": "Run performance-analysis skill on src/api/",
|
||||
"subagent_type": "outfitter:analyst",
|
||||
"run_in_background": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Chaining Skills
|
||||
|
||||
Skills can reference other skills for complex workflows.
|
||||
|
||||
### Sequential Chain
|
||||
|
||||
```markdown
|
||||
# Code Review Skill
|
||||
|
||||
1. Load `code-quality` skill for static analysis
|
||||
2. Load `security-patterns` skill for vulnerability check
|
||||
3. Load `performance-tips` skill for optimization suggestions
|
||||
4. Synthesize into unified review
|
||||
```
|
||||
|
||||
### Conditional Loading
|
||||
|
||||
```markdown
|
||||
# Smart Analyzer
|
||||
|
||||
Based on file type:
|
||||
- `.ts`/`.tsx`: Load `typescript-patterns` skill
|
||||
- `.rs`: Load `rust-patterns` skill
|
||||
- `.py`: Load `python-patterns` skill
|
||||
|
||||
Then proceed with analysis.
|
||||
```
|
||||
@@ -0,0 +1,126 @@
|
||||
# Performance Considerations
|
||||
|
||||
Token impact and optimization strategies for Claude Code skills.
|
||||
|
||||
## Token Impact
|
||||
|
||||
Every skill activation loads the full SKILL.md into context.
|
||||
|
||||
| SKILL.md Size | Approximate Tokens |
|
||||
|---------------|-------------------|
|
||||
| 100 lines | ~700 tokens |
|
||||
| 300 lines | ~2,000 tokens |
|
||||
| 500 lines | ~3,500 tokens |
|
||||
| 1,000 lines | ~7,000 tokens |
|
||||
| 1,500 lines | ~10,000 tokens |
|
||||
|
||||
**Rule**: Keep SKILL.md under 500 lines. Use progressive disclosure for details.
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
Move details out of SKILL.md:
|
||||
|
||||
```
|
||||
skill-name/
|
||||
+-- SKILL.md # Core workflow (~300 lines)
|
||||
+-- references/ # Deep-dive docs
|
||||
| +-- patterns.md
|
||||
| +-- edge-cases.md
|
||||
+-- examples/ # Worked examples
|
||||
```
|
||||
|
||||
**Loading pattern**:
|
||||
1. SKILL.md loads on activation (~2,000 tokens)
|
||||
2. References load only when explicitly needed
|
||||
3. Examples load only for clarification
|
||||
|
||||
## Tool Restrictions Reduce Latency
|
||||
|
||||
Without `allowed-tools`: Claude asks permission for each tool.
|
||||
With `allowed-tools`: Listed tools run immediately.
|
||||
|
||||
```yaml
|
||||
# Fast (no permission prompts)
|
||||
allowed-tools: Read Grep Glob
|
||||
|
||||
# Slower (prompts for unlisted tools)
|
||||
# (no allowed-tools field)
|
||||
```
|
||||
|
||||
## Context Mode Optimization
|
||||
|
||||
### When to Fork
|
||||
|
||||
| Scenario | Recommendation |
|
||||
|----------|----------------|
|
||||
| Verbose intermediate work | Fork (keeps main context clean) |
|
||||
| Parallel independent tasks | Fork (run simultaneously) |
|
||||
| Building on conversation | Inherit (needs prior context) |
|
||||
| Simple one-shot task | Either (fork slightly cleaner) |
|
||||
|
||||
Fork trades context sharing for isolation. Each fork starts fresh.
|
||||
|
||||
### Fork Overhead
|
||||
|
||||
Each forked skill invocation:
|
||||
- Loads skill instructions fresh
|
||||
- No conversation history
|
||||
- Returns only final output
|
||||
|
||||
Benefit: Main context stays lean
|
||||
Cost: No state sharing between forks
|
||||
|
||||
## Description Efficiency
|
||||
|
||||
Descriptions load into system prompt for every message. Keep them concise.
|
||||
|
||||
```yaml
|
||||
# Good: Concise, specific
|
||||
description: Parse PDF files for text extraction. Use when working with .pdf files.
|
||||
|
||||
# Bad: Verbose, redundant
|
||||
description: This skill is designed to help you parse and extract text content from PDF files. It can be used whenever you need to work with PDF documents, extract text, or process PDF files for analysis.
|
||||
```
|
||||
|
||||
## Activation Efficiency
|
||||
|
||||
### Auto-Activation
|
||||
|
||||
Claude evaluates skill descriptions against user input. More specific descriptions activate faster (fewer false considerations).
|
||||
|
||||
```yaml
|
||||
# Specific (fast match)
|
||||
description: Extract tables from Excel .xlsx files
|
||||
|
||||
# Vague (many false considerations)
|
||||
description: Work with files and data
|
||||
```
|
||||
|
||||
### Manual Activation
|
||||
|
||||
For skills that shouldn't auto-activate:
|
||||
|
||||
```yaml
|
||||
disable-model-invocation: true
|
||||
```
|
||||
|
||||
Requires explicit Skill tool call. Avoids description evaluation overhead.
|
||||
|
||||
## Caching
|
||||
|
||||
Skills are cached per session. Changes require:
|
||||
|
||||
```
|
||||
/clear
|
||||
```
|
||||
|
||||
Or start a new session.
|
||||
|
||||
## Optimization Checklist
|
||||
|
||||
- [ ] SKILL.md under 500 lines
|
||||
- [ ] Details in `references/`
|
||||
- [ ] Specific description with trigger keywords
|
||||
- [ ] `allowed-tools` for frequently-used tools
|
||||
- [ ] `context: fork` for verbose processing
|
||||
- [ ] `disable-model-invocation: true` for manual-only skills
|
||||
Reference in New Issue
Block a user