📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,230 @@
|
||||
---
|
||||
name: skills-dev
|
||||
description: This skill should be used when creating skills, writing SKILL.md files, or when "create skill", "new skill", "validate skill", or "SKILL.md" are mentioned. Covers cross-platform Agent Skills specification.
|
||||
metadata:
|
||||
version: "2.1.0"
|
||||
related-skills:
|
||||
- claude-skills
|
||||
- claude-plugins
|
||||
- claude-agents
|
||||
- codex-config
|
||||
allowed-tools: Read Write Edit Grep Glob Bash TaskCreate TaskUpdate TaskList TaskGet AskUserQuestion
|
||||
---
|
||||
|
||||
# Skills Development
|
||||
|
||||
Create skills that follow the [Agent Skills specification](https://agentskills.io/specification)—an open format supported by Claude Code, Cursor, VS Code, GitHub Copilot, Codex, and other agent products.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Discovery** — Understand what the skill should do
|
||||
2. **Archetype Selection** — Choose the best pattern
|
||||
3. **Initialization** — Create skill structure
|
||||
4. **Customization** — Tailor to specific needs
|
||||
5. **Validation** — Verify quality before committing
|
||||
|
||||
## Stage 1: Discovery
|
||||
|
||||
Ask about the skill:
|
||||
|
||||
- What problem does this skill solve?
|
||||
- What are the main capabilities?
|
||||
- What triggers should invoke it? (phrases users would say)
|
||||
- Where should it live? (personal, project, or plugin)
|
||||
|
||||
## Stage 2: Archetype Selection
|
||||
|
||||
| Archetype | Use When | Example |
|
||||
|-----------|----------|---------|
|
||||
| **simple** | Basic skill without scripts | Quick reference, style guide |
|
||||
| **api-wrapper** | Wrapping external APIs | GitHub API, Stripe API |
|
||||
| **document-processor** | Working with file formats | PDF extractor, Excel analyzer |
|
||||
| **dev-workflow** | Automating development tasks | Git workflow, project scaffolder |
|
||||
| **research-synthesizer** | Gathering and synthesizing information | Competitive analysis, literature review |
|
||||
|
||||
## Stage 3: Directory Structure
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # Required: instructions + metadata
|
||||
├── scripts/ # Optional: executable code
|
||||
├── references/ # Optional: documentation
|
||||
└── assets/ # Optional: templates, resources
|
||||
```
|
||||
|
||||
## Stage 4: Frontmatter Schema
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: What it does and when to use it. Include trigger keywords.
|
||||
version: 1.0.0 # optional, recommended
|
||||
license: Apache-2.0 # optional
|
||||
compatibility: Requires git and jq # optional
|
||||
metadata: # optional
|
||||
author: your-org
|
||||
category: development
|
||||
tags: [testing, automation]
|
||||
---
|
||||
```
|
||||
|
||||
| Field | Required | Constraints |
|
||||
|-------|----------|-------------|
|
||||
| `name` | Yes | 2-64 chars, lowercase/numbers/hyphens, must match directory |
|
||||
| `description` | Yes | 10-1024 chars, describes what + when |
|
||||
| `version` | No | Semantic version (MAJOR.MINOR.PATCH) |
|
||||
| `license` | No | License name or reference |
|
||||
| `compatibility` | No | 1-500 chars, environment requirements |
|
||||
| `metadata` | No | Object for custom fields |
|
||||
|
||||
**Note**: Platform-specific fields (e.g., Claude's `allowed-tools`, `user-invocable`) should be added per-platform. See [claude-code.md](references/claude-code.md) for Claude Code extensions.
|
||||
|
||||
### Custom Frontmatter
|
||||
|
||||
Custom fields **must** be nested under `metadata`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: my-skill
|
||||
description: ...
|
||||
metadata:
|
||||
author: your-org
|
||||
version: "1.0"
|
||||
category: development
|
||||
tags: [typescript, testing]
|
||||
---
|
||||
```
|
||||
|
||||
Top-level custom fields are not allowed and may cause parsing errors.
|
||||
|
||||
### Description Formula
|
||||
|
||||
**[WHAT] + [WHEN] + [TRIGGERS]**
|
||||
|
||||
```yaml
|
||||
description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
```
|
||||
|
||||
**Checklist:**
|
||||
- [ ] Explains WHAT (capabilities)
|
||||
- [ ] States WHEN (trigger conditions)
|
||||
- [ ] Includes 3-5 trigger KEYWORDS
|
||||
- [ ] Uses third-person voice
|
||||
- [ ] Under 200 words
|
||||
|
||||
## Stage 5: Validation
|
||||
|
||||
### Validation Checklist
|
||||
|
||||
#### A. YAML Frontmatter
|
||||
|
||||
- [ ] Opens with `---` on line 1, closes with `---`
|
||||
- [ ] `name` and `description` present (required)
|
||||
- [ ] Uses spaces, not tabs
|
||||
- [ ] Special characters quoted
|
||||
|
||||
#### B. Naming
|
||||
|
||||
- [ ] Lowercase, numbers, hyphens only (1-64 chars)
|
||||
- [ ] Matches parent directory name
|
||||
- [ ] No `--`, leading/trailing hyphens
|
||||
- [ ] No `anthropic` or `claude` in name
|
||||
|
||||
#### C. Description Quality
|
||||
|
||||
- [ ] WHAT: Explains capabilities
|
||||
- [ ] WHEN: States "Use when..." conditions
|
||||
- [ ] TRIGGERS: 3-5 keywords users would say
|
||||
- [ ] Third-person voice (not "I can" or "you can")
|
||||
|
||||
#### D. Structure
|
||||
|
||||
- [ ] SKILL.md under 500 lines
|
||||
- [ ] All referenced files exist
|
||||
- [ ] No TODO/placeholder markers
|
||||
- [ ] Progressive disclosure (details in `references/`)
|
||||
|
||||
### Report Format
|
||||
|
||||
```markdown
|
||||
# Skill Check: {skill-name}
|
||||
|
||||
**Status**: PASS | WARNINGS | FAIL
|
||||
**Issues**: {critical} critical, {warnings} warnings
|
||||
|
||||
## Critical (must fix)
|
||||
1. {issue with fix}
|
||||
|
||||
## Warnings (should fix)
|
||||
1. {issue with fix}
|
||||
|
||||
## Strengths
|
||||
- {what's done well}
|
||||
```
|
||||
|
||||
## Core Principles
|
||||
|
||||
### Concise is key
|
||||
|
||||
Context window is shared. Only include what the agent doesn't already know. Challenge each paragraph—does it justify its token cost?
|
||||
|
||||
### Third-person descriptions
|
||||
|
||||
Descriptions inject into system prompt:
|
||||
- "Extracts text from PDFs"
|
||||
- "I can help you extract text from PDFs"
|
||||
|
||||
### Progressive disclosure
|
||||
|
||||
Keep SKILL.md under 500 lines. Move details to:
|
||||
- `references/` - Detailed docs, API references
|
||||
- `scripts/` - Executable utilities (code never enters context)
|
||||
- `assets/` - Templates, data files
|
||||
|
||||
Token loading:
|
||||
1. **Metadata** (~100 tokens): name + description at startup
|
||||
2. **Instructions** (<5000 tokens): SKILL.md body when activated
|
||||
3. **Resources** (as needed): files loaded only when referenced
|
||||
|
||||
### Degrees of freedom
|
||||
|
||||
Match instruction specificity to task requirements:
|
||||
- **High freedom** (text): Multiple valid approaches, use judgment
|
||||
- **Medium freedom** (pseudocode): Preferred pattern with variation allowed
|
||||
- **Low freedom** (scripts): Exact sequence required, no deviation
|
||||
|
||||
See [patterns.md](references/patterns.md) for detailed examples.
|
||||
|
||||
## Naming Requirements
|
||||
|
||||
- Lowercase letters, numbers, hyphens only
|
||||
- Cannot start/end with hyphen or contain `--`
|
||||
- Must match parent directory name
|
||||
- Cannot contain `anthropic` or `claude`
|
||||
|
||||
**Recommended**: Gerund form (`processing-pdfs`, `reviewing-code`)
|
||||
|
||||
## Platform-Specific Guidance
|
||||
|
||||
Skills are cross-platform, but each tool has specific implementation details:
|
||||
|
||||
- **Claude Code**: See [claude-code.md](references/claude-code.md) for tool restrictions, testing, troubleshooting, and Claude-specific frontmatter extensions
|
||||
- **Codex CLI**: See [codex.md](references/codex.md) for discovery paths, `$skill-name` invocation
|
||||
|
||||
See [implementations.md](references/implementations.md) for storage paths and [invocations.md](references/invocations.md) for activation patterns.
|
||||
|
||||
## References
|
||||
|
||||
- [steps-pattern.md](references/steps-pattern.md) - Composable skill workflows with dependencies
|
||||
- [patterns.md](references/patterns.md) - Degrees of freedom, script design, variant organization
|
||||
- [best-practices.md](references/best-practices.md) - Community patterns, testing strategies
|
||||
- [quick-reference.md](references/quick-reference.md) - Fast checklist and one-liners
|
||||
- [implementations.md](references/implementations.md) - Per-tool storage paths
|
||||
- [invocations.md](references/invocations.md) - How tools activate skills
|
||||
- [compatibility.md](references/compatibility.md) - Path compatibility matrix
|
||||
|
||||
## External Resources
|
||||
|
||||
- [Agent Skills Specification](https://agentskills.io/specification)
|
||||
- [Best Practices Guide](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
|
||||
- [skills-ref Validation Library](https://github.com/agentskills/agentskills/tree/main/skills-ref)
|
||||
@@ -0,0 +1,913 @@
|
||||
# Agent Skills Best Practices
|
||||
|
||||
Community-sourced patterns, techniques, and pitfalls from practitioners and official documentation.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Progressive Disclosure Architecture](#progressive-disclosure-architecture)
|
||||
- [Skill Composition Patterns](#skill-composition-patterns)
|
||||
- [Description Optimization](#description-optimization)
|
||||
- [Common Pitfalls](#common-pitfalls)
|
||||
- [Testing Strategies](#testing-strategies)
|
||||
- [Advanced Techniques](#advanced-techniques)
|
||||
- [Security Considerations](#security-considerations)
|
||||
- [Organization-Wide Patterns](#organization-wide-patterns)
|
||||
|
||||
## Progressive Disclosure Architecture
|
||||
|
||||
**Three-tier information model**: Discovery → Activation → Execution
|
||||
|
||||
### Discovery Layer (~50 tokens)
|
||||
|
||||
YAML frontmatter that helps agents find the right skill without loading full content.
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: pdf-processing
|
||||
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
---
|
||||
```
|
||||
|
||||
**Keys to effective discovery**:
|
||||
- Include WHAT the skill does AND WHEN to use it
|
||||
- Use third-person voice
|
||||
- Include specific trigger terms users might mention
|
||||
- Keep under 100 tokens
|
||||
|
||||
### Activation Layer (~2-5K tokens)
|
||||
|
||||
Core SKILL.md instructions loaded when skill is invoked.
|
||||
|
||||
**Structure**:
|
||||
|
||||
```markdown
|
||||
# Skill Name
|
||||
|
||||
<when_to_use>
|
||||
Clear criteria for when this skill applies
|
||||
</when_to_use>
|
||||
|
||||
<workflow>
|
||||
Step-by-step process (numbered or structured)
|
||||
</workflow>
|
||||
|
||||
<rules>
|
||||
- ALWAYS: Mandatory behaviors
|
||||
- NEVER: Prohibited actions
|
||||
- PREFER: Recommended approaches
|
||||
</rules>
|
||||
|
||||
<references>
|
||||
Links to deep-dive docs in references/ subdirectory
|
||||
</references>
|
||||
```
|
||||
|
||||
**Keys to effective activation**:
|
||||
- **Assume intelligence**: Claude doesn't need basic concepts explained
|
||||
- **Be directive, not comprehensive**: Focus on what makes THIS approach different
|
||||
- **Keep under 500 lines**: Move details to references/
|
||||
- **Use examples sparingly**: Only for non-obvious patterns
|
||||
|
||||
### Execution Layer (dynamic)
|
||||
|
||||
Deep-dive content loaded on-demand from references/ subdirectory.
|
||||
|
||||
**Pattern from practitioners**:
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # Core workflow (500 lines max)
|
||||
├── references/
|
||||
│ ├── configuration.md # Detailed config options
|
||||
│ ├── error-handling.md # Edge cases and recovery
|
||||
│ ├── advanced-patterns.md # Expert techniques
|
||||
│ └── examples.md # Worked examples
|
||||
└── scripts/ # Helper utilities
|
||||
```
|
||||
|
||||
**Why this works** (source: Juan C Olamendy, skillmatic-ai):
|
||||
- Prevents context rot from loading irrelevant information
|
||||
- Allows targeted follow-up ("show me the advanced patterns")
|
||||
- Keeps initial load fast and focused
|
||||
- Scales to complex domains without overwhelming context
|
||||
|
||||
## Skill Composition Patterns
|
||||
|
||||
### Skills Invoking Skills
|
||||
|
||||
**Pattern**: Reference other skills in instructions rather than duplicating methodology.
|
||||
|
||||
```markdown
|
||||
## Error Investigation
|
||||
|
||||
Load the **outfitter:debugging** skill using the Skill tool to investigate
|
||||
this authentication failure systematically.
|
||||
|
||||
Pass these parameters to the debugging workflow:
|
||||
- Error context: [collected error details]
|
||||
- Hypothesis: Token validation timing issue
|
||||
```
|
||||
|
||||
**Why this works**:
|
||||
- Reuses established methodologies
|
||||
- Maintains single source of truth
|
||||
- Allows skills to evolve independently
|
||||
- Reduces duplication across skill library
|
||||
|
||||
**Anti-pattern**: Embedding another skill's instructions inline.
|
||||
|
||||
### Subagent Architecture
|
||||
|
||||
For orchestrating specialized work with context isolation, see [claude-code.md](./claude-code.md#master-clone-architecture) for Claude Code-specific patterns.
|
||||
|
||||
### Skill + External Service Integration
|
||||
|
||||
Skills can integrate with external services (APIs, MCP servers) by separating concerns:
|
||||
- **External service**: Handles authentication, rate limiting, data access
|
||||
- **Skill**: Handles business logic, formatting, workflows
|
||||
|
||||
This separation enables reuse across similar domains.
|
||||
|
||||
## Description Optimization
|
||||
|
||||
**Goal**: Help Claude discover your skill without loading it.
|
||||
|
||||
### Include Both WHAT and WHEN
|
||||
|
||||
❌ **Vague**: "Processes PDFs"
|
||||
✅ **Specific**: "Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
|
||||
|
||||
### Use Third-Person Voice
|
||||
|
||||
❌ "Use me when you need to debug"
|
||||
✅ "Debugs issues using systematic root cause analysis. Use when encountering errors, unexpected behavior, or test failures."
|
||||
|
||||
### Include Trigger Terms
|
||||
|
||||
Think about what users actually say:
|
||||
|
||||
```yaml
|
||||
description: Creates weekly team status reports with wins, challenges, and priorities.
|
||||
Use when the user asks for a team update, standup report, weekly summary, or status
|
||||
email. Keywords: standup, weekly update, team report, status.
|
||||
```
|
||||
|
||||
### Be Specific About Scope
|
||||
|
||||
❌ "Helps with testing"
|
||||
✅ "Implements test-driven development using Red-Green-Refactor cycles. Use when implementing new features with tests first, refactoring with test coverage, or reproducing bugs as failing tests."
|
||||
|
||||
**Source**: Official Anthropic best practices emphasize specificity prevents Claude from loading irrelevant skills.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### 1. Making SKILL.md Too Verbose
|
||||
|
||||
**Symptom**: 1000+ line SKILL.md files with exhaustive explanations.
|
||||
|
||||
**Why it's a problem**:
|
||||
- Wastes context window on every invocation
|
||||
- Buries key directives in noise
|
||||
- Assumes Claude needs basic concepts explained
|
||||
|
||||
**Fix**:
|
||||
- Keep SKILL.md under 500 lines
|
||||
- Move deep dives to references/
|
||||
- Trust Claude's base knowledge
|
||||
- Focus on WHAT makes THIS approach unique
|
||||
|
||||
**Example** (source: Anthropic best practices):
|
||||
|
||||
❌ **Verbose**:
|
||||
|
||||
```markdown
|
||||
## What is Test-Driven Development?
|
||||
|
||||
Test-Driven Development (TDD) is a software development methodology where you write
|
||||
tests before writing the actual code. This approach was popularized by Kent Beck
|
||||
and has become a cornerstone of modern software engineering practices...
|
||||
|
||||
[500 lines of TDD philosophy]
|
||||
```
|
||||
|
||||
✅ **Concise**:
|
||||
|
||||
```markdown
|
||||
## TDD Workflow
|
||||
|
||||
1. **Red**: Write a failing test for the next small piece of functionality
|
||||
2. **Green**: Write minimal code to make the test pass
|
||||
3. **Refactor**: Improve code while keeping tests green
|
||||
|
||||
ALWAYS write the test first. NEVER skip the refactor step.
|
||||
```
|
||||
|
||||
### 2. Negative-Only Constraints
|
||||
|
||||
**Symptom**: Instructions full of "NEVER do X" without alternatives.
|
||||
|
||||
❌ **Problem**:
|
||||
|
||||
```markdown
|
||||
- NEVER use any types
|
||||
- NEVER skip error handling
|
||||
- NEVER commit without tests
|
||||
```
|
||||
|
||||
**Why it's a problem**: Tells Claude what NOT to do but not what TO do.
|
||||
|
||||
✅ **Fix**: Pair constraints with positive alternatives:
|
||||
|
||||
```markdown
|
||||
- ALWAYS use strict types; NEVER use `any`
|
||||
- ALWAYS handle errors with Result types; NEVER let exceptions propagate silently
|
||||
- ALWAYS run tests before committing; NEVER push untested code
|
||||
```
|
||||
|
||||
### 3. Deeply Nested File References
|
||||
|
||||
**Symptom**: Skills referencing files that reference other files 3+ levels deep.
|
||||
|
||||
**Why it's a problem**:
|
||||
- Context explosion
|
||||
- Circular references
|
||||
- Hard to maintain
|
||||
|
||||
**Fix** (source: skillmatic-ai research):
|
||||
- Keep references ONE level deep
|
||||
- Use table of contents in long reference files
|
||||
- Let Claude request additional detail if needed
|
||||
|
||||
❌ **Deep nesting**:
|
||||
|
||||
```
|
||||
SKILL.md → references/patterns.md → references/examples/auth.md → references/examples/auth/jwt.md
|
||||
```
|
||||
|
||||
✅ **Flat structure**:
|
||||
|
||||
```
|
||||
SKILL.md → references/auth-patterns.md (with ToC for JWT, OAuth, etc.)
|
||||
```
|
||||
|
||||
### 4. Not Treating Skills Like Code
|
||||
|
||||
**Symptom**: Skills maintained as loose documents without version control, testing, or reviews.
|
||||
|
||||
**Why it's a problem**:
|
||||
- Skills drift from reality
|
||||
- Breaking changes go unnoticed
|
||||
- No way to roll back problematic versions
|
||||
|
||||
**Fix** (source: blog.sshh.io, Nate's newsletter):
|
||||
- **Version control**: Skills in git repos with semantic versioning
|
||||
- **Testing**: Build evaluations to validate skill behavior
|
||||
- **Reviews**: Treat skill PRs like code reviews
|
||||
- **Changelog**: Document what changed and why
|
||||
|
||||
**Pattern from practitioners**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: api-integration
|
||||
version: 2.1.0
|
||||
changelog: |
|
||||
2.1.0 - Added retry logic for rate limiting
|
||||
2.0.0 - Switched to streaming responses (breaking)
|
||||
1.5.0 - Added webhook verification
|
||||
---
|
||||
```
|
||||
|
||||
### 5. Over-Relying on Auto-Compaction
|
||||
|
||||
**Symptom**: Never manually clearing context, letting auto-compaction handle everything.
|
||||
|
||||
**Why it's a problem** (source: blog.sshh.io practitioner experience):
|
||||
- Important context gets compressed or dropped
|
||||
- Skill instructions get summarized incorrectly
|
||||
- Debugging becomes harder when full skill isn't visible
|
||||
|
||||
**Fix**: Manual context management strategy:
|
||||
1. Start complex tasks with `/clear` for clean slate
|
||||
2. Use `/catchup` with explicit context about what skills are active
|
||||
3. Let auto-compaction handle routine continuations
|
||||
4. Force reload skills after compaction if behavior seems off
|
||||
|
||||
**When to manually clear**:
|
||||
- Starting new major feature
|
||||
- Switching between unrelated tasks
|
||||
- After hitting context limits on complex debugging
|
||||
- When skill behavior seems inconsistent
|
||||
|
||||
### 6. Unclear Skill Boundaries
|
||||
|
||||
**Symptom**: Skill tries to do too many unrelated things.
|
||||
|
||||
**Example**: "code-helper" that does linting, testing, documentation, deployment, and debugging.
|
||||
|
||||
**Why it's a problem**:
|
||||
- Hard to discover (description too generic)
|
||||
- Loads unnecessary context
|
||||
- Becomes maintenance nightmare
|
||||
|
||||
**Fix**: **One skill, one job**.
|
||||
|
||||
✅ **Well-scoped skills**:
|
||||
- `linting-workflow`: Code quality checks and fixes
|
||||
- `tdd`: TDD methodology
|
||||
- `api-documentation`: API reference generation
|
||||
- `deployment-automation`: Deploy and rollback workflows
|
||||
- `debugging`: Root cause investigation
|
||||
|
||||
**Exception**: Orchestrator skills that explicitly load other skills (like `feature-development` that loads TDD → documentation → deployment in sequence).
|
||||
|
||||
### 7. No Usage Examples
|
||||
|
||||
**Symptom**: Skill has abstract instructions but no concrete examples.
|
||||
|
||||
**Why it's a problem**: Claude may misinterpret intent without seeing desired output.
|
||||
|
||||
**Fix**: Include 1-2 examples in references/examples.md
|
||||
|
||||
**Pattern**:
|
||||
|
||||
```markdown
|
||||
# Examples
|
||||
|
||||
## Example 1: Simple Case
|
||||
|
||||
**Input**: User asks to add login endpoint
|
||||
|
||||
**Workflow**:
|
||||
1. Load TDD skill
|
||||
2. Write failing test for /login POST
|
||||
3. Implement minimal auth logic
|
||||
4. Refactor to service layer
|
||||
|
||||
**Output**: [Show actual test code + implementation]
|
||||
|
||||
## Example 2: Edge Case
|
||||
|
||||
**Input**: User asks to add login with OAuth and JWT and refresh tokens
|
||||
|
||||
**Workflow**:
|
||||
1. Load pathfinding skill to break down requirements
|
||||
2. Load TDD skill for each component separately
|
||||
3. OAuth integration → JWT generation → Refresh logic
|
||||
4. Each gets its own test cycle
|
||||
|
||||
**Output**: [Show breakdown and test structure]
|
||||
```
|
||||
|
||||
**Source**: Official Anthropic best practices recommend examples for non-obvious patterns.
|
||||
|
||||
## Testing Strategies
|
||||
|
||||
### Eval-Driven Development
|
||||
|
||||
**Pattern**: Build evaluations BEFORE extensive documentation (source: Nate's newsletter).
|
||||
|
||||
**Workflow**:
|
||||
1. Create minimal skill version
|
||||
2. Build test suite with target inputs/outputs
|
||||
3. Iterate skill until evals pass consistently
|
||||
4. THEN write comprehensive docs
|
||||
|
||||
**Why this works**:
|
||||
- Prevents documenting the wrong approach
|
||||
- Faster iteration cycles
|
||||
- Forces clarity about success criteria
|
||||
- Builds regression test suite automatically
|
||||
|
||||
**Implementation** (from Nate's debugging toolkit):
|
||||
|
||||
```typescript
|
||||
// skill-testing-framework pattern
|
||||
interface SkillEval {
|
||||
name: string;
|
||||
input: string;
|
||||
expectedBehavior: string[];
|
||||
forbiddenBehavior: string[];
|
||||
targetModels: ('haiku' | 'sonnet' | 'opus')[];
|
||||
}
|
||||
|
||||
const tddSkillEvals: SkillEval[] = [
|
||||
{
|
||||
name: "basic-tdd-workflow",
|
||||
input: "Add a login endpoint",
|
||||
expectedBehavior: [
|
||||
"Writes test first",
|
||||
"Test fails initially (red phase)",
|
||||
"Implements minimal solution",
|
||||
"Test passes (green phase)",
|
||||
"Refactors with tests passing"
|
||||
],
|
||||
forbiddenBehavior: [
|
||||
"Writes implementation before test",
|
||||
"Skips refactor step",
|
||||
"Makes test pass by modifying test"
|
||||
],
|
||||
targetModels: ['haiku', 'sonnet', 'opus']
|
||||
}
|
||||
];
|
||||
```
|
||||
|
||||
### Multi-Model Testing
|
||||
|
||||
**Pattern**: Test skills with all target models.
|
||||
|
||||
**Why**: Haiku, Sonnet, and Opus interpret instructions differently:
|
||||
- **Haiku**: Needs more explicit instructions, less inference
|
||||
- **Sonnet**: Balanced reasoning, good for most workflows
|
||||
- **Opus**: Handles complex context, better with ambiguity
|
||||
|
||||
**Testing strategy** (source: Anthropic best practices):
|
||||
|
||||
| Aspect | Haiku Test | Sonnet Test | Opus Test |
|
||||
|--------|------------|-------------|-----------|
|
||||
| Clarity | Do instructions work with minimal reasoning? | Do instructions balance brevity and clarity? | Do instructions leverage advanced reasoning? |
|
||||
| Context | Works with small context? | Handles moderate references? | Manages large cross-references? |
|
||||
| Edge cases | Explicit handling? | Reasonable inference? | Sophisticated judgment? |
|
||||
|
||||
**Fix pattern**: If Haiku fails but Sonnet passes, instructions likely assume too much inference.
|
||||
|
||||
### Real-World Usage Testing
|
||||
|
||||
**Pattern**: Test skills with actual users/agents in production-like scenarios.
|
||||
|
||||
**Anti-pattern**: Only testing with constructed examples.
|
||||
|
||||
**Strategy** (from practitioner experience):
|
||||
1. **Dogfooding**: Use your own skills for real work
|
||||
2. **Iteration tracking**: Log when skills are loaded but not followed
|
||||
3. **Confusion signals**: Detect when Claude asks for clarification (skill might be unclear)
|
||||
4. **Outcome validation**: Did the skill achieve its intended result?
|
||||
|
||||
**Metrics to track**:
|
||||
- Skill load frequency (is it discoverable?)
|
||||
- Completion rate (do workflows finish?)
|
||||
- User satisfaction (did it solve the problem?)
|
||||
- Iteration count (how many tries to get it right?)
|
||||
|
||||
**From blog.sshh.io**: "Built 10 debugging tools after watching 100 people hit the same problems in their first week."
|
||||
|
||||
### Systematic Evaluation Framework
|
||||
|
||||
**Components** (source: Nate's newsletter, skillmatic-ai research):
|
||||
|
||||
1. **skill-debugging-assistant**: Identifies where skills fail
|
||||
2. **skill-security-analyzer**: Checks for security risks in skill code
|
||||
3. **skill-gap-analyzer**: Finds missing skills in your library
|
||||
4. **skill-performance-profiler**: Tracks context usage and latency
|
||||
5. **prompt-optimization-analyzer**: Improves skill descriptions for discovery
|
||||
6. **skill-testing-framework**: Automated test runner for skills
|
||||
|
||||
**Pattern**: Build tools to test tools.
|
||||
|
||||
## Advanced Techniques
|
||||
|
||||
### Hook-Based Validation
|
||||
|
||||
For platform-specific hook implementation patterns, see [claude-code.md](./claude-code.md#hook-based-validation).
|
||||
|
||||
**General principle**: Use hooks to enforce constraints at decision points—prevent destructive operations, enforce testing requirements, validate configuration before deployment.
|
||||
|
||||
### Organization-Wide Skill Libraries
|
||||
|
||||
**Pattern**: Centralized skill repository as institutional knowledge (source: Juan C Olamendy, Medium).
|
||||
|
||||
**Structure**:
|
||||
|
||||
```
|
||||
company-skills/
|
||||
├── engineering/
|
||||
│ ├── deployment-workflow/
|
||||
│ ├── incident-response/
|
||||
│ └── architecture-review/
|
||||
├── product/
|
||||
│ ├── user-story-creation/
|
||||
│ └── feature-planning/
|
||||
└── business/
|
||||
├── team-standup/
|
||||
└── quarterly-planning/
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- Codifies company processes
|
||||
- Onboarding material becomes executable
|
||||
- Process improvements propagate automatically
|
||||
- Consistency across teams
|
||||
|
||||
**Implementation** (from practitioners):
|
||||
1. **Central registry**: Marketplace or internal skill server
|
||||
2. **Contribution guidelines**: Templates for creating company skills
|
||||
3. **Review process**: Skills reviewed like code before publishing
|
||||
4. **Version management**: Semantic versioning for breaking changes
|
||||
5. **Deprecation policy**: How to sunset old patterns
|
||||
|
||||
**Pattern from blog.sshh.io**:
|
||||
|
||||
```markdown
|
||||
# Company Skill Manifest
|
||||
|
||||
## Deployment
|
||||
- `deployment-staging`: Deploy to staging with rollback plan
|
||||
- `deployment-production`: Production deploy with checklist
|
||||
- `deployment-rollback`: Emergency rollback procedures
|
||||
|
||||
## Code Review
|
||||
- `pr-review-backend`: Backend code review checklist
|
||||
- `pr-review-frontend`: Frontend code review standards
|
||||
- `security-review`: Security-focused code review
|
||||
|
||||
## Documentation
|
||||
- `api-documentation`: OpenAPI spec generation
|
||||
- `readme-maintenance`: README updates for features
|
||||
```
|
||||
|
||||
**Anti-pattern**: Every team building their own version of the same workflows.
|
||||
|
||||
### Progressive Skill Disclosure in Practice
|
||||
|
||||
**Advanced pattern**: Table of contents in reference files for targeted loading.
|
||||
|
||||
**Example** (source: skillmatic-ai architecture):
|
||||
|
||||
```markdown
|
||||
# API Integration Patterns
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [REST Basics](#rest-basics) - Standard CRUD operations
|
||||
- [GraphQL](#graphql) - Query and mutation patterns
|
||||
- [Webhooks](#webhooks) - Event-driven integrations
|
||||
- [Rate Limiting](#rate-limiting) - Backoff and retry
|
||||
- [Authentication](#authentication) - OAuth, JWT, API keys
|
||||
- [Error Handling](#error-handling) - Retry logic and fallbacks
|
||||
|
||||
## REST Basics
|
||||
|
||||
[Focused content on REST]
|
||||
|
||||
## GraphQL
|
||||
|
||||
[Focused content on GraphQL]
|
||||
```
|
||||
|
||||
**Usage**: Skill says "See references/api-patterns.md#rate-limiting for retry logic" rather than loading entire file.
|
||||
|
||||
**Why it works**:
|
||||
- Claude can navigate to specific section
|
||||
- Preserves context for other tasks
|
||||
- User can request more depth if needed
|
||||
|
||||
### Skills as Living Documentation
|
||||
|
||||
**Pattern**: Skills replace static documentation that goes stale.
|
||||
|
||||
**Traditional docs**: "Here's how to deploy" (written once, outdated quickly)
|
||||
**Skill**: Executes deployment with current best practices
|
||||
|
||||
**Benefits** (source: Juan C Olamendy):
|
||||
- **Always current**: If process changes, skill changes
|
||||
- **Executable**: Not just instructions but enforcement
|
||||
- **Testable**: Verify the process actually works
|
||||
- **Discoverable**: Claude can find relevant process
|
||||
|
||||
**Example transformation**:
|
||||
|
||||
❌ **Static doc** (docs/deployment.md):
|
||||
|
||||
```markdown
|
||||
# Deployment Process
|
||||
|
||||
1. Run tests
|
||||
2. Update version number
|
||||
3. Build production bundle
|
||||
4. Upload to S3
|
||||
5. Clear CDN cache
|
||||
6. Notify team in Slack
|
||||
|
||||
[This gets outdated when we switch to Vercel]
|
||||
```
|
||||
|
||||
✅ **Skill** (skills/deployment/SKILL.md):
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: deployment-production
|
||||
description: Deploys to production with safety checks
|
||||
---
|
||||
|
||||
# Production Deployment
|
||||
|
||||
1. Verify all tests pass: `bun test`
|
||||
2. Run build: `bun run build`
|
||||
3. Deploy to Vercel: `vercel --prod`
|
||||
4. Verify deployment: Check /api/health
|
||||
5. Notify team: Use Slack MCP to post to #deployments
|
||||
|
||||
ALWAYS wait for health check before considering deploy complete.
|
||||
```
|
||||
|
||||
**When process changes**: Update skill, test it, deploy new version. Documentation stays current.
|
||||
|
||||
### Skill Chaining for Complex Workflows
|
||||
|
||||
**Pattern**: Master skill orchestrates sequence of specialized skills.
|
||||
|
||||
**Example** (source: practitioner patterns):
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: feature-development
|
||||
description: End-to-end feature development workflow
|
||||
---
|
||||
|
||||
# Feature Development Workflow
|
||||
|
||||
## Stage 1: Planning
|
||||
Load **pathfinding** skill to clarify requirements and architecture.
|
||||
|
||||
## Stage 2: Implementation
|
||||
Load **tdd** skill to implement with tests.
|
||||
|
||||
## Stage 3: Documentation
|
||||
Load **api-documentation** skill to generate API docs.
|
||||
|
||||
## Stage 4: Review
|
||||
Load **code-review** skill to validate implementation.
|
||||
|
||||
## Stage 5: Deployment
|
||||
Load **deployment-staging** skill to deploy for testing.
|
||||
|
||||
Each stage must complete successfully before proceeding to next.
|
||||
```
|
||||
|
||||
**Advantage**: Each specialized skill can evolve independently. Feature-development orchestrates but doesn't duplicate.
|
||||
|
||||
**Related pattern - Conditional chaining**:
|
||||
|
||||
```markdown
|
||||
## Error Recovery
|
||||
|
||||
If tests fail in Stage 2:
|
||||
Load **debugging** skill to investigate
|
||||
Return to Stage 2 after fixes
|
||||
|
||||
If code review finds issues in Stage 4:
|
||||
Return to Stage 2 for fixes
|
||||
Re-run Stage 3 to update docs
|
||||
Re-run Stage 4 to re-review
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
**Critical warning** (source: Sid Bharath tutorial, security research): Skills can execute arbitrary code and access files. Only use skills from trusted sources.
|
||||
|
||||
### Risks
|
||||
|
||||
1. **Code execution**: Skills can include scripts that run on your machine
|
||||
2. **File access**: Skills can read/write files in project
|
||||
3. **Network access**: Skills can make HTTP requests
|
||||
4. **Credential access**: Skills can access environment variables, config files
|
||||
5. **Social engineering**: Malicious skills disguised as helpful tools
|
||||
|
||||
### Protection Strategies
|
||||
|
||||
**1. Source verification**:
|
||||
- Only install skills from trusted authors
|
||||
- Review skill code before using
|
||||
- Check community reputation and reviews
|
||||
- Verify skill matches description (no hidden behavior)
|
||||
|
||||
**2. Code review checklist** (from security research):
|
||||
|
||||
```markdown
|
||||
## Skill Security Review
|
||||
|
||||
- [ ] Review all scripts in scripts/ directory
|
||||
- [ ] Check for file system access patterns
|
||||
- [ ] Verify network requests are legitimate
|
||||
- [ ] Confirm no credential harvesting
|
||||
- [ ] Check for obfuscated code
|
||||
- [ ] Validate external dependencies
|
||||
- [ ] Test in isolated environment first
|
||||
```
|
||||
|
||||
**3. Sandbox testing**:
|
||||
- Test new skills in isolated project first
|
||||
- Use throwaway credentials for initial testing
|
||||
- Monitor file system and network activity
|
||||
- Check for unexpected side effects
|
||||
|
||||
**4. Minimal permissions**:
|
||||
|
||||
```yaml
|
||||
# Proposed security metadata (from research)
|
||||
permissions:
|
||||
file_read: ['src/**', 'docs/**']
|
||||
file_write: ['docs/**']
|
||||
network: ['https://api.company.com']
|
||||
environment: []
|
||||
```
|
||||
|
||||
**5. Audit logging**:
|
||||
Track what skills do in production:
|
||||
- What files were accessed?
|
||||
- What commands were executed?
|
||||
- What network requests were made?
|
||||
|
||||
**From security papers**: "Skills are code execution with conversational interface. Treat them with same security rigor as any code dependency."
|
||||
|
||||
## Organization-Wide Patterns
|
||||
|
||||
### Skill as Institutional Knowledge
|
||||
|
||||
**Pattern**: Replace tribal knowledge with executable skills (source: Juan C Olamendy).
|
||||
|
||||
**Traditional problem**:
|
||||
- "How do we deploy?" → Ask Sarah, she knows
|
||||
- "What's the PR review process?" → Different on every team
|
||||
- "How do we handle incidents?" → Check the wiki (outdated)
|
||||
|
||||
**Skill solution**:
|
||||
- **deployment-production skill**: Encodes Sarah's knowledge
|
||||
- **pr-review skill**: Standardizes review process
|
||||
- **incident-response skill**: Current playbook, always up to date
|
||||
|
||||
**Implementation strategy**:
|
||||
|
||||
1. **Identify critical workflows**: What knowledge is locked in people's heads?
|
||||
2. **Interview experts**: How do they actually do the work?
|
||||
3. **Create skills**: Encode process as executable workflow
|
||||
4. **Test with novices**: Can someone unfamiliar complete the task?
|
||||
5. **Iterate**: Refine based on real usage
|
||||
6. **Deprecate docs**: Point to skills instead of wikis
|
||||
|
||||
**Example from blog.sshh.io**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: internal-deploy
|
||||
description: Company deployment process with all safety checks
|
||||
---
|
||||
|
||||
# Internal Deployment Workflow
|
||||
|
||||
## Pre-Deploy Checklist
|
||||
1. Verify Jira ticket is in "Ready for Deploy" status
|
||||
2. Confirm tests pass in CI: `check-ci-status`
|
||||
3. Get approval in #deploy-requests Slack channel
|
||||
|
||||
## Deploy
|
||||
1. Run staging deploy: `npm run deploy:staging`
|
||||
2. Verify staging health: `curl https://staging.company.com/health`
|
||||
3. Run smoke tests: `npm run smoke-test:staging`
|
||||
4. Deploy to production: `npm run deploy:prod`
|
||||
5. Monitor for 5 minutes: Watch Datadog dashboard
|
||||
|
||||
## Post-Deploy
|
||||
1. Verify production health: `curl https://company.com/health`
|
||||
2. Post to #deployments: "Deployed [feature] to prod"
|
||||
3. Update Jira ticket to "Deployed"
|
||||
|
||||
NEVER skip smoke tests. ALWAYS monitor after deploy.
|
||||
```
|
||||
|
||||
**Benefit**: New team members can deploy safely on day one.
|
||||
|
||||
### Contribution Guidelines
|
||||
|
||||
**Pattern**: Treat skills like open source contributions.
|
||||
|
||||
**Template** (from ComposioHQ awesome-claude-skills):
|
||||
|
||||
```markdown
|
||||
# Contributing Skills
|
||||
|
||||
## Before Submitting
|
||||
|
||||
1. **Test thoroughly**: Run skill with Haiku, Sonnet, and Opus
|
||||
2. **Follow structure**: Use provided skill template
|
||||
3. **Document clearly**: Include description, when to use, examples
|
||||
4. **Security review**: No malicious code or credential access
|
||||
5. **License**: MIT or Apache 2.0
|
||||
|
||||
## Skill Requirements
|
||||
|
||||
- [ ] Descriptive name (kebab-case)
|
||||
- [ ] Clear description with trigger terms
|
||||
- [ ] SKILL.md under 500 lines
|
||||
- [ ] References in references/ subdirectory
|
||||
- [ ] At least one example in examples/
|
||||
- [ ] Testing results documented
|
||||
- [ ] README.md with usage instructions
|
||||
|
||||
## Review Process
|
||||
|
||||
1. Submit PR with skill in skills/your-skill-name/
|
||||
2. Maintainers review for quality and security
|
||||
3. Address feedback
|
||||
4. Approved skills merged and published
|
||||
```
|
||||
|
||||
### Versioning Strategy
|
||||
|
||||
**Pattern**: Semantic versioning for skills (from practitioners).
|
||||
|
||||
**Format**: MAJOR.MINOR.PATCH
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: api-integration
|
||||
version: 2.1.0
|
||||
---
|
||||
```
|
||||
|
||||
**Versioning rules**:
|
||||
- **MAJOR**: Breaking changes (workflow steps changed, different inputs required)
|
||||
- **MINOR**: New features (additional optional steps, new references added)
|
||||
- **PATCH**: Bug fixes (typos, clarifications, small improvements)
|
||||
|
||||
**Breaking change example**:
|
||||
|
||||
```markdown
|
||||
# Version 1.x: Required user to provide API key
|
||||
---
|
||||
name: api-client
|
||||
version: 1.5.0
|
||||
description: Make API calls with provided credentials
|
||||
---
|
||||
|
||||
# Version 2.x: Uses MCP server for authentication (breaking)
|
||||
---
|
||||
name: api-client
|
||||
version: 2.0.0
|
||||
description: Make API calls using Linear MCP server
|
||||
---
|
||||
```
|
||||
|
||||
**Migration guide pattern**:
|
||||
|
||||
```markdown
|
||||
# Migration Guide: 1.x → 2.0
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
- No longer accepts `api_key` parameter
|
||||
- Now requires Linear MCP server configured
|
||||
- Response format changed from JSON to structured objects
|
||||
|
||||
## Migration Steps
|
||||
|
||||
1. Install Linear MCP server: `/mcp install linear`
|
||||
2. Update skill invocations to remove `api_key`
|
||||
3. Update code expecting JSON to handle structured objects
|
||||
```
|
||||
|
||||
## Summary: Hierarchy of Best Practices
|
||||
|
||||
### Essential (Do These Always)
|
||||
|
||||
1. **Progressive disclosure**: Keep SKILL.md under 500 lines, use references/
|
||||
2. **Clear descriptions**: Include what AND when, with trigger terms
|
||||
3. **Assume intelligence**: Claude doesn't need basics explained
|
||||
4. **Test with real usage**: Dogfood your own skills
|
||||
5. **Version control**: Track changes, review like code
|
||||
|
||||
### Important (Do These Usually)
|
||||
|
||||
6. **Multi-model testing**: Verify Haiku, Sonnet, Opus behavior
|
||||
7. **Positive constraints**: Say what TO do, not just what NOT to do
|
||||
8. **Examples for non-obvious**: Show expected behavior
|
||||
9. **Composition over duplication**: Reference other skills
|
||||
10. **Security review**: Audit code execution and file access
|
||||
|
||||
### Advanced (Do These for Scale)
|
||||
|
||||
11. **Eval-driven development**: Build tests before extensive docs
|
||||
12. **Hook-based enforcement**: Use PreToolUse for quality gates
|
||||
13. **Organization-wide libraries**: Centralized skill registry
|
||||
14. **Semantic versioning**: Track breaking changes
|
||||
15. **Skills as living docs**: Replace static documentation
|
||||
|
||||
### Expert (Do These for Excellence)
|
||||
|
||||
16. **Systematic evaluation framework**: Build tools to test tools
|
||||
17. **Master-Clone architecture**: Optimize context usage
|
||||
18. **Conditional skill chaining**: Orchestrate complex workflows
|
||||
19. **Audit logging**: Track skill execution in production
|
||||
20. **Community contribution**: Share patterns, learn from others
|
||||
|
||||
## Sources
|
||||
|
||||
Research synthesized from:
|
||||
|
||||
- **Official Documentation**: Anthropic Claude Agent Skills Best Practices
|
||||
- **Community Repositories**: ComposioHQ/awesome-claude-skills, skillmatic-ai/awesome-agent-skills
|
||||
- **Practitioner Blogs**: blog.sshh.io (Claude Code at scale), Juan C Olamendy (Medium), Sid Bharath
|
||||
- **Research**: Security considerations from academic papers, progressive disclosure architecture
|
||||
- **Tooling**: Nate's Newsletter (debugging toolkit), evaluation frameworks
|
||||
|
||||
Last updated: 2026-01-10
|
||||
@@ -0,0 +1,628 @@
|
||||
# Claude Code Extensions
|
||||
|
||||
> **Note**: For comprehensive Claude Code skill development, load the `outfitter:claude-skills` skill. This reference provides a quick overview.
|
||||
|
||||
Claude Code-specific implementation details for Agent Skills. For cross-platform concepts (structure, frontmatter, validation), load the `outfitter:skills-dev` skill.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Frontmatter Extensions](#frontmatter-extensions)
|
||||
- [Tool Restrictions](#tool-restrictions)
|
||||
- [User Invocable Skills](#user-invocable-skills)
|
||||
- [String Substitutions](#string-substitutions)
|
||||
- [Dynamic Context Injection](#dynamic-context-injection)
|
||||
- [Context Modes](#context-modes)
|
||||
- [Testing with Debug Mode](#testing-with-debug-mode)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Integration Patterns](#integration-patterns)
|
||||
- [Master-Clone Architecture](#master-clone-architecture)
|
||||
- [Hook-Based Validation](#hook-based-validation)
|
||||
- [Skill + MCP Integration](#skill--mcp-integration)
|
||||
|
||||
---
|
||||
|
||||
## Frontmatter Extensions
|
||||
|
||||
Claude Code extends the base Agent Skills specification with additional frontmatter fields:
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `allowed-tools` | string | Space-separated list of tools the skill can use without permission prompts |
|
||||
| `user-invocable` | boolean | Default `true`. Set to `false` to prevent slash command access |
|
||||
| `disable-model-invocation` | boolean | Prevents automatic activation; requires manual invocation via Skill tool |
|
||||
| `context` | string | `inherit` (default) or `fork` for isolated subagent execution |
|
||||
| `agent` | string | Agent to use when skill is invoked (e.g., `outfitter:analyst`) |
|
||||
| `model` | string | Override model: `haiku`, `sonnet`, or `opus` |
|
||||
| `hooks` | object | Lifecycle hooks: `on-activate`, `on-complete` |
|
||||
| `argument-hint` | string | Hint text shown after `/skill-name` (e.g., `[file path]`) |
|
||||
|
||||
### Example
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: code-review
|
||||
version: 1.0.0
|
||||
description: Reviews code for bugs, security issues, 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
|
||||
---
|
||||
```
|
||||
|
||||
> **Note:** `user-invocable` defaults to `true`, so skills are callable as `/skill-name` by default. Only set `user-invocable: false` if you want to prevent slash command access.
|
||||
|
||||
---
|
||||
|
||||
## Tool Restrictions
|
||||
|
||||
Use `allowed-tools` to specify which tools Claude can use when a skill is active. Listed 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 |
|
||||
|
||||
### Behavior
|
||||
|
||||
- **With `allowed-tools`**: Listed tools run without permission prompts
|
||||
- **Without `allowed-tools`**: Inherits conversation permissions; Claude may ask
|
||||
|
||||
---
|
||||
|
||||
## User Invocable Skills
|
||||
|
||||
Skills are callable as slash commands by default (`user-invocable: true`). Use `user-invocable: false` to prevent slash command access for skills that should only be auto-activated.
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: code-review
|
||||
description: Reviews code for bugs and best practices...
|
||||
argument-hint: [file or PR number]
|
||||
---
|
||||
```
|
||||
|
||||
Users can invoke with `/code-review src/auth.ts` or wait for auto-activation based on the description.
|
||||
|
||||
### Disabling Slash Command Access
|
||||
|
||||
For skills that should only activate automatically (not manually invoked):
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: internal-validator
|
||||
description: Validates internal state when specific patterns are detected...
|
||||
user-invocable: false
|
||||
---
|
||||
```
|
||||
|
||||
### With Arguments
|
||||
|
||||
The `argument-hint` field provides context in the command picker:
|
||||
|
||||
```yaml
|
||||
argument-hint: [error message or bug description]
|
||||
```
|
||||
|
||||
Arguments are available in the skill body via `$ARGUMENTS`.
|
||||
|
||||
---
|
||||
|
||||
## String Substitutions
|
||||
|
||||
Claude Code supports these substitution patterns in skill content:
|
||||
|
||||
| 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`
|
||||
```
|
||||
|
||||
When Claude loads the skill, these commands execute and their output replaces the command syntax.
|
||||
|
||||
**Use cases:**
|
||||
- Current branch state
|
||||
- Environment information
|
||||
- Dynamic configuration
|
||||
- Recent history
|
||||
|
||||
---
|
||||
|
||||
## Context Modes
|
||||
|
||||
The `context` field controls how skills execute:
|
||||
|
||||
### inherit (default)
|
||||
|
||||
Skill runs in the main conversation context. Has access to conversation history and prior tool results.
|
||||
|
||||
```yaml
|
||||
context: inherit
|
||||
```
|
||||
|
||||
### fork
|
||||
|
||||
Skill runs in an 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`, the skill can specify:
|
||||
- `agent`: Which agent type handles the fork
|
||||
- `model`: Override model for the forked context
|
||||
|
||||
---
|
||||
|
||||
## Testing with Debug Mode
|
||||
|
||||
```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 being evaluated
|
||||
- `Skill allowed-tools: [list]` — Tool restrictions applied
|
||||
|
||||
### Testing Process
|
||||
|
||||
1. **Verify loading**: Run `claude --debug` and check for load messages
|
||||
2. **Test discovery**: Ask Claude something that should trigger the skill
|
||||
3. **Verify tool restrictions**: Confirm permitted tools run without prompts
|
||||
4. **Test with real data**: Run actual workflows
|
||||
|
||||
### Example Test Session
|
||||
|
||||
```bash
|
||||
# Start debug session
|
||||
claude --debug
|
||||
|
||||
# In conversation, trigger the skill naturally:
|
||||
# "Can you help me process this PDF file?"
|
||||
|
||||
# Look for:
|
||||
# "Considering skill: pdf-processor"
|
||||
# "Activated skill: pdf-processor"
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
# Validate syntax
|
||||
bun run outfitter/scripts/validate-skill-frontmatter.ts SKILL.md
|
||||
```
|
||||
|
||||
**Check file permissions:**
|
||||
|
||||
```bash
|
||||
chmod 644 SKILL.md
|
||||
chmod +x scripts/*.sh
|
||||
```
|
||||
|
||||
### 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** that users naturally say:
|
||||
- File types: `.pdf`, `.json`, `.xlsx`
|
||||
- Actions: `parse`, `validate`, `test`, `analyze`
|
||||
- Domains: `API`, `database`, `spreadsheet`
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
### Script Execution Errors
|
||||
|
||||
**Ensure executable:**
|
||||
|
||||
```bash
|
||||
chmod +x scripts/*.sh
|
||||
```
|
||||
|
||||
**Use portable shebang:**
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash # Recommended
|
||||
#!/bin/bash # Also works
|
||||
```
|
||||
|
||||
**Use ${CLAUDE_PLUGIN_ROOT} for paths:**
|
||||
|
||||
```markdown
|
||||
# Correct
|
||||
${CLAUDE_PLUGIN_ROOT}/scripts/process.sh input.txt
|
||||
|
||||
# Wrong (breaks portability)
|
||||
/Users/me/.claude/skills/my-skill/scripts/process.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
```
|
||||
|
||||
When user runs `/analyze-pdf report.pdf`, Claude recognizes the PDF context and activates the skill.
|
||||
|
||||
### With Hooks
|
||||
|
||||
Hooks can suggest skill usage:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write(*.ts)|Edit(*.ts)",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo 'Consider using typescript-linter skill'"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Using Skill Tool
|
||||
|
||||
Load skills programmatically with the Skill tool:
|
||||
|
||||
```
|
||||
Use the Skill tool to invoke the pdf-processor skill
|
||||
```
|
||||
|
||||
This is useful for:
|
||||
- Forcing specific skill activation
|
||||
- Chaining skills together
|
||||
- Loading skills for agents
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
**Advantage over inline execution**: Master preserves main conversation context; specialist work happens in isolated bubble.
|
||||
|
||||
### 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
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Hook-Based Validation
|
||||
|
||||
Use hooks to enforce constraints at decision points.
|
||||
|
||||
### PreToolUse Hook Example
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Write(**/SKILL.md)|Edit(**/SKILL.md)",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-skill-frontmatter.ts",
|
||||
"timeout": 10
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Use Cases
|
||||
|
||||
- Prevent destructive operations
|
||||
- Enforce testing requirements
|
||||
- Validate configuration before deployment
|
||||
- Check security constraints
|
||||
- Validate skill frontmatter before saving
|
||||
|
||||
### Block at Submit Pattern
|
||||
|
||||
```typescript
|
||||
export async function blockAtSubmit() {
|
||||
const issues = await runStaticAnalysis();
|
||||
const testsPassing = await runTestSuite();
|
||||
const securityClear = await runSecurityAudit();
|
||||
|
||||
return {
|
||||
block: issues.length > 0 || !testsPassing || !securityClear,
|
||||
reason: formatBlockingIssues(issues)
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skill + MCP Integration
|
||||
|
||||
**Pattern**: Skills provide workflows, MCP servers provide data/tools.
|
||||
|
||||
### Example Architecture
|
||||
|
||||
- **MCP Server**: Linear API access (issues, projects, users)
|
||||
- **Skill**: Project standup workflow (what data to pull, how to format, communication patterns)
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: linear-standup
|
||||
description: Generates team standup reports from Linear issues
|
||||
allowed-tools: mcp__linear__get_issues mcp__linear__get_projects
|
||||
---
|
||||
|
||||
# Linear Standup Skill
|
||||
|
||||
Use the Linear MCP server to:
|
||||
1. Fetch issues by status and assignee
|
||||
2. Group by project and priority
|
||||
3. Format as standup report
|
||||
```
|
||||
|
||||
### Why Separate
|
||||
|
||||
- MCP handles authentication, rate limiting, data access
|
||||
- Skill handles business logic, formatting, workflows
|
||||
- Easier to reuse across similar domains
|
||||
|
||||
---
|
||||
|
||||
## Performance Tips
|
||||
|
||||
### Keep SKILL.md Small
|
||||
|
||||
Token impact of skill size:
|
||||
- 300 lines ≈ 2,000 tokens
|
||||
- 1,500 lines ≈ 10,000 tokens
|
||||
|
||||
Each activation loads the full SKILL.md. Use progressive disclosure.
|
||||
|
||||
### Tool Restrictions Speed Up Execution
|
||||
|
||||
Without restrictions: Claude asks permission for each tool.
|
||||
With restrictions: Listed tools run immediately.
|
||||
|
||||
```yaml
|
||||
# Fast (no prompts for these tools)
|
||||
allowed-tools: Read Grep Glob
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```bash
|
||||
# Find all skills
|
||||
find ~/.claude/skills .claude/skills -name "SKILL.md" 2>/dev/null
|
||||
|
||||
# Validate YAML
|
||||
bun run outfitter/scripts/validate-skill-frontmatter.ts SKILL.md
|
||||
|
||||
# Check for tabs
|
||||
grep -P "\t" SKILL.md
|
||||
|
||||
# Test in debug mode
|
||||
claude --debug
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Resources
|
||||
|
||||
For comprehensive guidance, load the relevant skill:
|
||||
|
||||
- Claude Code skills: `outfitter:claude-skills`
|
||||
- Cross-platform skills: `outfitter:skills-dev`
|
||||
- Plugin development: `outfitter:claude-plugins`
|
||||
- Hook integration: `outfitter:claude-hooks`
|
||||
- Command integration: `outfitter:claude-commands`
|
||||
|
||||
Reference docs in this directory:
|
||||
|
||||
- [best-practices.md](best-practices.md) — Community patterns and testing strategies
|
||||
- [patterns.md](patterns.md) — Advanced skill patterns and degrees of freedom
|
||||
@@ -0,0 +1,255 @@
|
||||
# Codex CLI Implementation
|
||||
|
||||
Codex CLI-specific implementation details for Agent Skills. For cross-platform concepts, see the main [SKILL.md](../SKILL.md).
|
||||
|
||||
## Discovery Paths
|
||||
|
||||
Codex loads skills from multiple locations with this precedence order (higher overrides lower):
|
||||
|
||||
| Scope | Location | Use Case |
|
||||
| ----- | -------- | -------- |
|
||||
| `REPO` | `$CWD/.codex/skills` | Project-specific skills in current directory |
|
||||
| `REPO` | `$CWD/../.codex/skills` | Parent folder skills (when in Git repo) |
|
||||
| `REPO` | `$REPO_ROOT/.codex/skills` | Repository root skills |
|
||||
| `USER` | `$CODEX_HOME/skills` (default: `~/.codex/skills`) | User's personal skills |
|
||||
| `ADMIN` | `/etc/codex/skills` | System/admin skills |
|
||||
| `SYSTEM` | Bundled with Codex | Built-in skills |
|
||||
|
||||
**Key behaviors:**
|
||||
- Skills with the same name from higher precedence scopes overwrite lower ones
|
||||
- Skills are discovered at startup by scanning these paths
|
||||
- Restart Codex after installing new skills to load them
|
||||
|
||||
## Enabling Skills
|
||||
|
||||
Skills are gated behind a feature flag:
|
||||
|
||||
```bash
|
||||
# Check if enabled
|
||||
codex features list
|
||||
|
||||
# Enable once
|
||||
codex --enable skills
|
||||
|
||||
# Enable permanently in ~/.codex/config.toml:
|
||||
[features]
|
||||
skills = true
|
||||
```
|
||||
|
||||
## Invocation Methods
|
||||
|
||||
### Explicit Invocation
|
||||
|
||||
Supported in CLI and IDE extensions:
|
||||
|
||||
```
|
||||
# Skill picker
|
||||
Type $ to see available skills
|
||||
|
||||
# Slash command
|
||||
/skills
|
||||
|
||||
# Direct mention in prompt
|
||||
$skill-name analyze this code
|
||||
```
|
||||
|
||||
Not yet supported in Codex Web or iOS.
|
||||
|
||||
### Implicit Invocation
|
||||
|
||||
Works across all platforms (CLI, Web, iOS):
|
||||
|
||||
- Codex auto-detects when task matches a skill's description
|
||||
- The `description` field is the primary trigger signal
|
||||
- Write descriptions with "Use when..." clauses for better matching
|
||||
|
||||
```yaml
|
||||
# Good: clear trigger conditions
|
||||
description: Extracts text and tables from PDFs. Use when working with PDF files or document extraction.
|
||||
|
||||
# Bad: vague, hard to match
|
||||
description: Helps with files
|
||||
```
|
||||
|
||||
## AGENTS.md vs Skills
|
||||
|
||||
Codex uses `AGENTS.md` for project instructions, separate from skills:
|
||||
|
||||
| Aspect | AGENTS.md | Skills |
|
||||
| ------ | --------- | ------ |
|
||||
| **Loading** | Always loaded per-session | Loaded on-demand when invoked |
|
||||
| **Purpose** | Project-wide context and rules | Task-specific capabilities |
|
||||
| **Scope** | Per-repository | Personal, project, or system |
|
||||
| **Location** | Repository root or `~/.codex/` | `skills/` directories |
|
||||
|
||||
**AGENTS.md discovery order:**
|
||||
1. `~/.codex/AGENTS.override.md` (or `AGENTS.md`)
|
||||
2. Repository root `AGENTS.md`
|
||||
3. Nested `AGENTS.override.md` in subdirectories
|
||||
|
||||
## Built-in Skills
|
||||
|
||||
Codex includes utility skills:
|
||||
|
||||
| Skill | Purpose |
|
||||
| ----- | ------- |
|
||||
| `$skill-creator` | Creates new skills interactively |
|
||||
| `$skill-installer` | Downloads skills from GitHub repos |
|
||||
| `$create-plan` | Experimental planning skill |
|
||||
|
||||
### Skill Installer
|
||||
|
||||
```bash
|
||||
# Install from OpenAI's curated skills
|
||||
$skill-installer linear
|
||||
$skill-installer notion-spec-to-implementation
|
||||
|
||||
# Downloads to $CODEX_HOME/skills/
|
||||
```
|
||||
|
||||
## Tool Restrictions
|
||||
|
||||
The `allowed-tools` field is experimental in Codex:
|
||||
|
||||
```yaml
|
||||
allowed-tools: Bash(git:*) Bash(jq:*) Read
|
||||
```
|
||||
|
||||
**Status:**
|
||||
- Marked as "experimental" in the Agent Skills spec
|
||||
- "Support for this field may vary between agent implementations"
|
||||
- No explicit Codex documentation on implementation
|
||||
|
||||
**Alternative controls in Codex:**
|
||||
- Global `sandbox_mode` setting
|
||||
- Global `approval_policy` setting
|
||||
- MCP servers support `enabled_tools` and `disabled_tools` arrays
|
||||
- No per-skill tool restrictions documented
|
||||
|
||||
## Testing Skills
|
||||
|
||||
### Validation
|
||||
|
||||
Use the skills-ref validator:
|
||||
|
||||
```bash
|
||||
skills-ref validate ./my-skill
|
||||
```
|
||||
|
||||
Checks:
|
||||
- YAML frontmatter validity
|
||||
- Name/description constraints
|
||||
- Naming conventions
|
||||
|
||||
### Testing Workflow
|
||||
|
||||
1. Create skill in `~/.codex/skills/my-skill/`
|
||||
2. **Restart Codex** to load it (required)
|
||||
3. Test explicit invocation: `$my-skill test task`
|
||||
4. Test implicit invocation: Use keywords from description
|
||||
5. Check `/skills` command to confirm it's loaded
|
||||
|
||||
### Debugging
|
||||
|
||||
- Check `~/.codex/log/codex-tui.log` for skill loading errors
|
||||
- Validation errors shown at startup if YAML malformed
|
||||
- Codex ignores empty files and symlinked directories
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Skill Not Loading
|
||||
|
||||
**Check feature flag:**
|
||||
|
||||
```bash
|
||||
codex features list
|
||||
# Look for: skills ... true
|
||||
```
|
||||
|
||||
**Verify file location:**
|
||||
|
||||
```bash
|
||||
# Personal skills
|
||||
ls ~/.codex/skills/my-skill/SKILL.md
|
||||
|
||||
# Project skills
|
||||
ls .codex/skills/my-skill/SKILL.md
|
||||
```
|
||||
|
||||
**Restart Codex:**
|
||||
|
||||
Skills are only discovered at startup. After adding a new skill, restart the CLI.
|
||||
|
||||
### Skill Not Activating
|
||||
|
||||
**Check description triggers:**
|
||||
|
||||
The description is the primary trigger for implicit invocation. Ensure it includes:
|
||||
- What the skill does
|
||||
- "Use when..." conditions
|
||||
- Keywords users would naturally say
|
||||
|
||||
**Try explicit invocation:**
|
||||
|
||||
```
|
||||
$skill-name do the task
|
||||
```
|
||||
|
||||
If explicit works but implicit doesn't, improve the description.
|
||||
|
||||
### Validation Errors
|
||||
|
||||
**Check YAML syntax:**
|
||||
|
||||
```bash
|
||||
# Validate YAML
|
||||
python3 -c "import yaml; yaml.safe_load(open('SKILL.md').read().split('---')[1])"
|
||||
|
||||
# Check for tabs (YAML requires spaces)
|
||||
grep -P "\t" SKILL.md
|
||||
```
|
||||
|
||||
**Common issues:**
|
||||
- Tabs instead of spaces
|
||||
- Missing quotes around special characters
|
||||
- Missing closing `---` delimiter
|
||||
|
||||
## Differences from Claude Code
|
||||
|
||||
| Feature | Codex CLI | Claude Code |
|
||||
| ------- | --------- | ----------- |
|
||||
| **Skill loading** | Feature flag required | Built-in support |
|
||||
| **Discovery paths** | 6 scopes with precedence | Plugin system + `.claude/skills/` |
|
||||
| **Invocation** | `$skill-name` syntax | Skill tool, natural language |
|
||||
| **Project instructions** | `AGENTS.md` | `CLAUDE.md` |
|
||||
| **Restart required** | Yes, after adding skills | No, skills reload on `/clear` |
|
||||
| **Tool restrictions** | `allowed-tools` (experimental) | `allowed-tools` (functional) |
|
||||
| **Built-in creator** | `$skill-creator` | Manual or via outfitter plugin |
|
||||
| **Debug mode** | Log files | `claude --debug` |
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```bash
|
||||
# Check skills feature is enabled
|
||||
codex features list
|
||||
|
||||
# Find all skills
|
||||
find ~/.codex/skills .codex/skills -name "SKILL.md" 2>/dev/null
|
||||
|
||||
# Validate skill
|
||||
skills-ref validate ./my-skill
|
||||
|
||||
# Check logs for errors
|
||||
cat ~/.codex/log/codex-tui.log | grep -i skill
|
||||
|
||||
# Invoke skill explicitly
|
||||
# In Codex prompt: $skill-name do something
|
||||
```
|
||||
|
||||
## Sources
|
||||
|
||||
- [Codex Skills Overview](https://developers.openai.com/codex/skills)
|
||||
- [Create Skills Guide](https://developers.openai.com/codex/skills/create-skill)
|
||||
- [AGENTS.md Documentation](https://developers.openai.com/codex/guides/agents-md)
|
||||
- [Agent Skills Specification](https://agentskills.io/specification)
|
||||
- [Codex Configuration Reference](https://developers.openai.com/codex/config-reference)
|
||||
@@ -0,0 +1,105 @@
|
||||
# Skills Compatibility
|
||||
|
||||
This document tracks which tools have adopted the Agent Skills standard and their supported skill paths.
|
||||
|
||||
## Adopting Tools
|
||||
|
||||
| Tool | Vendor | Status | Notes |
|
||||
| ------ | -------- | -------- | ------- |
|
||||
| Claude Code | Anthropic | Stable | Origin of the `.claude/skills` convention |
|
||||
| Claude (claude.ai) | Anthropic | Stable | Custom skills via zip upload |
|
||||
| Claude API | Anthropic | Stable | Skills API endpoints |
|
||||
| GitHub Copilot | GitHub/Microsoft | Stable | Repo-level; org/enterprise coming soon |
|
||||
| VS Code (Copilot) | Microsoft | Preview | Behind `chat.useAgentSkills` in Insiders |
|
||||
| OpenAI Codex | OpenAI | Stable | Full precedence hierarchy |
|
||||
| Cursor | Cursor | Nightly | Agent-decided only (no manual invocation) |
|
||||
| Amp | Sourcegraph | Stable | Lazy-loaded; conflicting user path docs |
|
||||
| Letta | Letta | Stable | Two memory blocks (`skills` + `loaded_skills`) |
|
||||
| Goose | Block | Stable | Explicit Claude compatibility |
|
||||
| OpenCode | Community | Plugin | Requires `opencode-skills` third-party plugin |
|
||||
|
||||
## Path Compatibility Matrix
|
||||
|
||||
Which skill paths each tool reads:
|
||||
|
||||
| Tool | `.claude/skills/` | `.github/skills/` | Tool-specific path | User-level path |
|
||||
| ------ | :-----------------: | :-----------------: | :------------------: | :---------------: |
|
||||
| **Claude Code** | ✅ Primary | — | — | `~/.claude/skills/` |
|
||||
| **GitHub Copilot** | ✅ Compat | ✅ Primary | — | — |
|
||||
| **VS Code (Copilot)** | ✅ Legacy | ✅ Primary | — | — |
|
||||
| **OpenAI Codex** | — | — | `.codex/skills/` | `~/.codex/skills/` |
|
||||
| **Cursor** | — | — | (not documented) | — |
|
||||
| **Amp** | ✅ Compat | — | `.agents/skills/` | `~/.config/amp/skills/` ⚠️ |
|
||||
| **Letta** | — | — | `.skills/` | (via `--skills` flag) |
|
||||
| **Goose** | ✅ Compat | — | `.goose/skills/` | `~/.config/goose/skills/` |
|
||||
| **OpenCode** | — | — | `.opencode/skills/` | `~/.opencode/skills/` |
|
||||
|
||||
⚠️ Amp has conflicting docs: manual says `~/.config/amp/skills/`, announcement says `~/.config/agents/skills/`
|
||||
|
||||
**Legend:**
|
||||
- ✅ Primary = Recommended/default path
|
||||
- ✅ Compat = Supported for compatibility
|
||||
- ✅ Legacy = Supported but deprecated
|
||||
- — = Not supported
|
||||
|
||||
## Interoperability Patterns
|
||||
|
||||
### The `.claude/skills` Bridge
|
||||
|
||||
The `.claude/skills` convention originated with Anthropic's Claude Code and has become a de facto compatibility layer:
|
||||
|
||||
- **GitHub, VS Code, Amp, Goose** all read `.claude/skills` for backward compatibility
|
||||
- This makes `.claude/skills` the most portable choice for cross-tool skills
|
||||
|
||||
### The `.github/skills` Convention
|
||||
|
||||
GitHub/Microsoft are pushing `.github/skills` as the repo-native convention:
|
||||
|
||||
- Primary for GitHub Copilot and VS Code Copilot
|
||||
- Still supports `.claude/skills` as legacy fallback
|
||||
|
||||
### Tool-Specific Conventions
|
||||
|
||||
Other ecosystems maintain their own scoped conventions while often reading `.claude/skills`:
|
||||
|
||||
| Convention | Tools |
|
||||
| ------------ | ------- |
|
||||
| `.codex/skills` | OpenAI Codex |
|
||||
| `.agents/skills` | Amp |
|
||||
| `.skills` | Letta |
|
||||
| `.goose/skills` | Goose |
|
||||
| `.opencode/skills` | OpenCode |
|
||||
|
||||
## Choosing a Path Convention
|
||||
|
||||
| Goal | Recommended Path |
|
||||
| ------ | ------------------ |
|
||||
| Maximum portability | `.claude/skills/` |
|
||||
| GitHub/VS Code native | `.github/skills/` |
|
||||
| Tool-specific optimization | Use tool's primary path |
|
||||
| Multi-tool project | Use both `.claude/skills/` and tool-specific |
|
||||
|
||||
## User-Level Skills Paths
|
||||
|
||||
For personal skills shared across projects:
|
||||
|
||||
| Tool | User Path |
|
||||
| ------ | ----------- |
|
||||
| Claude Code | `~/.claude/skills/` |
|
||||
| OpenAI Codex | `~/.codex/skills/` (via `$CODEX_HOME/skills`) |
|
||||
| Amp | `~/.config/amp/skills/` (per manual) |
|
||||
| Goose | `~/.config/goose/skills/` |
|
||||
| Letta | Custom via `--skills` flag |
|
||||
| OpenCode* | `~/.opencode/skills/` or `~/.config/opencode/skills/` |
|
||||
|
||||
*OpenCode requires the `opencode-skills` third-party plugin.
|
||||
|
||||
## Admin/System-Level Skills
|
||||
|
||||
Some tools support organization-wide or system-level skills:
|
||||
|
||||
| Tool | Admin Path | Notes |
|
||||
| ------ | ------------ | ------- |
|
||||
| OpenAI Codex | `/etc/codex/skills` | System-wide |
|
||||
| Claude API | Org-wide via API | Skills API endpoints |
|
||||
| GitHub Copilot | — | Org/enterprise coming soon |
|
||||
@@ -0,0 +1,225 @@
|
||||
# Skills Implementations
|
||||
|
||||
Per-product implementation details for Agent Skills support.
|
||||
|
||||
## Claude Products
|
||||
|
||||
### Claude Code
|
||||
|
||||
The origin of the `.claude/skills` convention.
|
||||
|
||||
**Storage Paths:**
|
||||
|
||||
| Scope | Path |
|
||||
| ----- | ---- |
|
||||
| Personal | `~/.claude/skills/` |
|
||||
| Project | `.claude/skills/` |
|
||||
| Plugin | Bundled with installed plugins |
|
||||
|
||||
**Precedence:** Not officially documented. Skills are "automatically discovered" from all sources.
|
||||
|
||||
**Special Features:**
|
||||
- `allowed-tools` frontmatter to restrict tool access (Claude Code only, not SDK/API)
|
||||
- Skills are model-invoked (vs user-invoked slash commands)
|
||||
|
||||
**SDK Note:** By default, the SDK does not load skills from filesystem. Must explicitly set `settingSources: ['user', 'project']`.
|
||||
|
||||
**Reference:** [Claude Code Skills Docs](https://code.claude.com/docs/en/skills)
|
||||
|
||||
---
|
||||
|
||||
### Claude (claude.ai)
|
||||
|
||||
**Storage:**
|
||||
- Custom skills uploaded as **zip files** via Settings
|
||||
- Per-user (not admin-managed)
|
||||
- Does not sync to API or other surfaces
|
||||
|
||||
**Pre-built Skills:**
|
||||
- Document actions (automatic activation)
|
||||
|
||||
**Reference:** [Claude Skills Docs](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
|
||||
|
||||
---
|
||||
|
||||
### Claude API
|
||||
|
||||
**Storage:**
|
||||
- Pre-built skills referenced by stable IDs (`pptx`, `xlsx`, `docx`, `pdf`)
|
||||
- Custom skills uploaded via Skills API endpoints
|
||||
- Stored **org-wide** (separate from claude.ai uploads)
|
||||
|
||||
**Integration:**
|
||||
- Reference `skill_id` in code execution container
|
||||
|
||||
**Reference:** [Claude API Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
|
||||
|
||||
---
|
||||
|
||||
## GitHub Copilot
|
||||
|
||||
**Storage Paths:**
|
||||
|
||||
| Scope | Path |
|
||||
| ----- | ---- |
|
||||
| Primary | `./.github/skills/<skill>/SKILL.md` |
|
||||
| Compatibility | `./.claude/skills/` |
|
||||
|
||||
**Notes:**
|
||||
- Currently repo-level only
|
||||
- Org/enterprise-level skills "coming soon"
|
||||
- `SKILL.md` injected into agent context when used
|
||||
|
||||
---
|
||||
|
||||
## VS Code (Copilot)
|
||||
|
||||
**Storage Paths:**
|
||||
|
||||
| Scope | Path |
|
||||
| ----- | ---- |
|
||||
| Recommended | `./.github/skills/` |
|
||||
| Legacy | `./.claude/skills/` |
|
||||
|
||||
**Availability:**
|
||||
- Preview in **VS Code Insiders**
|
||||
- Enable via `chat.useAgentSkills` setting
|
||||
|
||||
**Reference:** [VS Code Agent Skills](https://code.visualstudio.com/docs/copilot/customization/agent-skills)
|
||||
|
||||
---
|
||||
|
||||
## OpenAI Codex
|
||||
|
||||
**Storage Paths (with precedence, highest overrides lowest):**
|
||||
|
||||
| Priority | Scope | Path | Use Case |
|
||||
| -------- | ----- | ---- | -------- |
|
||||
| 1 (highest) | Repo (CWD) | `$CWD/.codex/skills` | Skills for specific folder/microservice |
|
||||
| 2 | Repo (parent) | `$CWD/../.codex/skills` | Shared skills in parent folder |
|
||||
| 3 | Repo (root) | `$REPO_ROOT/.codex/skills` | Repository-wide skills |
|
||||
| 4 | User | `$CODEX_HOME/skills` (`~/.codex/skills`) | Personal skills across all repos |
|
||||
| 5 | Admin | `/etc/codex/skills` | SDK scripts, automation, admin defaults |
|
||||
| 6 (lowest) | System | Bundled with Codex | Built-in skills (`$plan`, `$skill-creator`) |
|
||||
|
||||
**Note:** Skills with the same name are overwritten by higher-precedence scopes.
|
||||
|
||||
**Built-in skills:** `$plan`, `$skill-creator`, `$skill-installer`
|
||||
|
||||
**Reference:** [Codex Skills](https://developers.openai.com/codex/skills/)
|
||||
|
||||
---
|
||||
|
||||
## Cursor
|
||||
|
||||
**Storage:**
|
||||
- File-based and repo-trackable
|
||||
- Can install via GitHub repository links
|
||||
- Exact default paths not publicly documented
|
||||
|
||||
**Availability:**
|
||||
- Agent Skills only on **Nightly** update channel
|
||||
- Enable via Settings > Rules > Import Settings > Agent Skills
|
||||
- Switch channel: Cursor Settings (`Cmd+Shift+J`/`Ctrl+Shift+J`) > Beta > Nightly
|
||||
|
||||
**Constraints:**
|
||||
- Skills are agent-decided only — cannot be configured as "always apply" or manually invoked
|
||||
|
||||
**Reference:** [Cursor Skills Docs](https://cursor.com/docs/context/skills)
|
||||
|
||||
---
|
||||
|
||||
## Amp
|
||||
|
||||
**Storage Paths:**
|
||||
|
||||
| Scope | Path |
|
||||
| ----- | ---- |
|
||||
| Workspace (default) | `.agents/skills/` |
|
||||
| User-level | `~/.config/amp/skills/` (per manual) |
|
||||
| User-level (alt) | `~/.config/agents/skills/` (per announcement) |
|
||||
| Compatibility | `.claude/skills/`, `~/.claude/skills/` |
|
||||
|
||||
**Note:** Official docs have conflicting user paths — manual says `~/.config/amp/skills/`, announcement says `~/.config/agents/skills/`.
|
||||
|
||||
**Behavior:**
|
||||
- Skills are lazy-loaded instructions (on-demand)
|
||||
|
||||
**Reference:** [Amp Owner's Manual](https://ampcode.com/manual#agent-skills)
|
||||
|
||||
---
|
||||
|
||||
## Letta (Letta Code)
|
||||
|
||||
**Storage Path:**
|
||||
- Project root: `.skills/`
|
||||
- Custom location: `letta --skills ~/my-global-skills`
|
||||
- Each skill is a subdirectory with `SKILL.md`, optional `references/`, `scripts/`, `examples/`, `assets/`
|
||||
|
||||
**Internal Persistence (Two Memory Blocks):**
|
||||
- **`skills` block** (always visible, read-only): List of available skills with names + descriptions
|
||||
- **`loaded_skills` block** (session, read-only): Full content of currently loaded skills
|
||||
|
||||
**Token Optimization:**
|
||||
- Only loaded skills consume context tokens
|
||||
- Can have 50 available skills but only 2 loaded
|
||||
|
||||
**Special Commands:**
|
||||
- `/skill` — Extract a new reusable skill from recent work (agent reflects on recent messages)
|
||||
|
||||
**Reference:** [Letta Code Skills Docs](https://docs.letta.com/letta-code/skills)
|
||||
|
||||
---
|
||||
|
||||
## Goose
|
||||
|
||||
**Storage Paths (with precedence, highest first):**
|
||||
|
||||
| Priority | Path |
|
||||
| -------- | ---- |
|
||||
| 1 (highest) | `./.goose/skills/` |
|
||||
| 2 | `./.claude/skills/` |
|
||||
| 3 | `~/.config/goose/skills/` |
|
||||
| 4 (lowest) | `~/.claude/skills/` |
|
||||
|
||||
**Compatibility:**
|
||||
- Explicitly supports "Claude Desktop" skill sharing
|
||||
- Treats `.claude/skills/` as compatibility layer
|
||||
|
||||
---
|
||||
|
||||
## OpenCode
|
||||
|
||||
**Important:** Skills are NOT native to OpenCode. Requires the third-party **`opencode-skills`** community plugin.
|
||||
|
||||
**Installation:**
|
||||
|
||||
```json
|
||||
{
|
||||
"plugin": ["opencode-skills"]
|
||||
}
|
||||
```
|
||||
|
||||
Requires OpenCode SDK ≥ 1.0.126.
|
||||
|
||||
**Storage Paths (precedence, highest first):**
|
||||
|
||||
| Priority | Scope | Path |
|
||||
| -------- | ----- | ---- |
|
||||
| 1 (highest) | Project | `.opencode/skills/` |
|
||||
| 2 | Custom | `$OPENCODE_CONFIG_DIR/skills/` |
|
||||
| 3 | Global | `~/.opencode/skills/` |
|
||||
| 4 (lowest) | XDG | `~/.config/opencode/skills/` |
|
||||
|
||||
**Integration:**
|
||||
- Plugin discovers skills at startup (cached, no hot reload)
|
||||
- Skills registered as dynamic tools: `skills_{name}` (hyphens → underscores)
|
||||
- Example: `brand-guidelines/` → `skills_brand_guidelines`
|
||||
|
||||
**Operational Notes:**
|
||||
- Adding/modifying skills requires restarting OpenCode
|
||||
- Duplicate skill names: project version takes precedence (with warning)
|
||||
|
||||
**References:**
|
||||
- [opencode-skills Plugin](https://github.com/malhashemi/opencode-skills)
|
||||
- [Superpowers for OpenCode](https://blog.fsck.com/2025/11/24/Superpowers-for-OpenCode/)
|
||||
@@ -0,0 +1,223 @@
|
||||
# Skills Invocations
|
||||
|
||||
How each tool activates and invokes skills.
|
||||
|
||||
## Invocation Patterns Overview
|
||||
|
||||
| Tool | Pattern | Description |
|
||||
| ------ | --------- | ------------- |
|
||||
| Claude Code | Model-invoked | Agent autonomously decides based on request + description |
|
||||
| Claude (claude.ai) | Auto + Model | Pre-built skills auto-activate; custom skills when relevant |
|
||||
| GitHub Copilot | Model-invoked | Based on prompt + skill description |
|
||||
| VS Code (Copilot) | Model-invoked | Auto-activates, follows progressive disclosure |
|
||||
| OpenAI Codex | Explicit + Implicit | `/skills` command or `$skill` mentions, or model decides |
|
||||
| Cursor | Model-invoked | Agent determines relevance automatically |
|
||||
| Amp | Lazy-loaded | On-demand loading when relevant |
|
||||
| Letta | Tool-based | Agent calls `Skill` tool to load into memory |
|
||||
| Goose | Model-invoked | Loads skills, accesses files via file tools |
|
||||
| OpenCode | Tool-based | Skills registered as dynamic tools via plugin |
|
||||
|
||||
## Detailed Invocation Methods
|
||||
|
||||
### Claude Code
|
||||
|
||||
**Type:** Model-invoked (autonomous)
|
||||
|
||||
Claude autonomously decides to use skills based on:
|
||||
- Current request context
|
||||
- Skill `name` and `description` from frontmatter
|
||||
|
||||
**Contrast with slash commands:**
|
||||
- Skills = model-invoked (agent decides)
|
||||
- Slash commands = user-invoked (explicit)
|
||||
|
||||
---
|
||||
|
||||
### Claude (claude.ai)
|
||||
|
||||
**Type:** Automatic + Model-invoked
|
||||
|
||||
- **Pre-built skills** (document actions): Activate automatically
|
||||
- **Custom skills**: Load when model determines relevance
|
||||
|
||||
---
|
||||
|
||||
### GitHub Copilot
|
||||
|
||||
**Type:** Model-invoked
|
||||
|
||||
Copilot decides activation based on:
|
||||
- User's prompt content
|
||||
- Skill `description` field
|
||||
|
||||
When activated:
|
||||
- `SKILL.md` content injected into agent context
|
||||
|
||||
---
|
||||
|
||||
### VS Code (Copilot)
|
||||
|
||||
**Type:** Model-invoked (auto-activation)
|
||||
|
||||
- No manual skill selection required
|
||||
- Follows progressive disclosure pattern
|
||||
- Model determines when skills are relevant
|
||||
|
||||
---
|
||||
|
||||
### OpenAI Codex
|
||||
|
||||
**Type:** Explicit + Implicit
|
||||
|
||||
**Explicit invocation:**
|
||||
- `/skills` slash command — Opens skill selector
|
||||
- `$<skill-name>` mention — Reference specific skill in prompt (e.g., `$plan`, `$skill-creator`)
|
||||
|
||||
**Implicit invocation:**
|
||||
- Codex decides based on skill descriptions
|
||||
- Automatic activation when task matches skill description
|
||||
|
||||
**Surface support:**
|
||||
- CLI and IDE extensions support explicit invocation
|
||||
- Web and iOS don't support explicit invocation yet (but can prompt Codex to use repo skills)
|
||||
|
||||
**Built-in skills:**
|
||||
- `$plan` — Research and create implementation plans
|
||||
- `$skill-creator` — Bootstrap new skills
|
||||
- `$skill-installer` — Download skills from GitHub
|
||||
|
||||
---
|
||||
|
||||
### Cursor
|
||||
|
||||
**Type:** Model-invoked ("agent-decided rules")
|
||||
|
||||
- Agent determines relevance automatically
|
||||
- No manual intervention required
|
||||
- Skills applied without user selection
|
||||
|
||||
**Constraint:** Skills cannot be configured as "always apply" or manually invoked — agent-decided only.
|
||||
|
||||
---
|
||||
|
||||
### Amp
|
||||
|
||||
**Type:** Lazy-loaded
|
||||
|
||||
- Skills loaded on-demand when relevant
|
||||
- Described as "lazy-loaded instructions"
|
||||
- No explicit invocation required
|
||||
|
||||
---
|
||||
|
||||
### Letta (Letta Code)
|
||||
|
||||
**Type:** Tool-based
|
||||
|
||||
**Model invocation:**
|
||||
- Agent calls the **`Skill` tool** to load skills into memory
|
||||
- Agent decides when to load based on context
|
||||
- Skill tool commands: `load`, `unload`, `refresh`
|
||||
|
||||
**Explicit invocation:**
|
||||
- Prompt: "Use the testing skill..." to force specific skill
|
||||
- `/skill` command: Extract new skill from recent work
|
||||
|
||||
**Memory integration (Two Blocks):**
|
||||
- **`skills` block**: Always visible — list of available skills (names + descriptions)
|
||||
- **`loaded_skills` block**: Session state — full content of currently loaded skills
|
||||
- Both blocks are read-only (modified only via Skill tool)
|
||||
|
||||
**Alternative access:**
|
||||
- Can read `.skills/<name>/SKILL.md` directly for one-time preview (without loading)
|
||||
|
||||
---
|
||||
|
||||
### Goose
|
||||
|
||||
**Type:** Model-invoked
|
||||
|
||||
- Loads skills when relevant
|
||||
- Accesses supporting files via file tools
|
||||
- Treats skills as filesystem resources
|
||||
|
||||
---
|
||||
|
||||
### OpenCode
|
||||
|
||||
**Type:** Tool-based
|
||||
|
||||
- `opencode-skills` plugin registers skills as **dynamic tools**
|
||||
- Skills become tool-like affordances
|
||||
- Agent invokes skills as it would any other tool
|
||||
|
||||
## Invocation Pattern Comparison
|
||||
|
||||
### Model-Invoked (Autonomous)
|
||||
|
||||
The agent decides when to use skills without explicit user action.
|
||||
|
||||
**Pros:**
|
||||
- Seamless user experience
|
||||
- Agent can combine skills as needed
|
||||
- No learning curve for users
|
||||
|
||||
**Cons:**
|
||||
- Less predictable
|
||||
- May miss relevant skills
|
||||
- User has less control
|
||||
|
||||
**Tools:** Claude Code, Claude, GitHub Copilot, VS Code, Cursor, Amp, Goose
|
||||
|
||||
### Explicit Invocation
|
||||
|
||||
User directly requests skill usage via commands or mentions.
|
||||
|
||||
**Pros:**
|
||||
- Predictable behavior
|
||||
- User maintains control
|
||||
- Clear audit trail
|
||||
|
||||
**Cons:**
|
||||
- Requires user to know available skills
|
||||
- More friction
|
||||
- May miss opportunities
|
||||
|
||||
**Tools:** OpenAI Codex (`$skill`, `/skills`)
|
||||
|
||||
### Tool-Based
|
||||
|
||||
Skills are exposed as tools the agent can call programmatically.
|
||||
|
||||
**Pros:**
|
||||
- Fits existing tool-use patterns
|
||||
- Clear invocation semantics
|
||||
- Integrates with agent memory
|
||||
|
||||
**Cons:**
|
||||
- Requires tool infrastructure
|
||||
- More complex implementation
|
||||
|
||||
**Tools:** Letta, OpenCode
|
||||
|
||||
## Progressive Disclosure in Invocation
|
||||
|
||||
Most tools follow a staged loading pattern:
|
||||
|
||||
```text
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Stage 1: Index │
|
||||
│ Load: name, description │
|
||||
│ When: Startup / cache refresh │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Stage 2: Activate │
|
||||
│ Load: Full SKILL.md body │
|
||||
│ When: Agent decides skill is relevant │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Stage 3: Execute │
|
||||
│ Load: scripts/, references/, assets/ │
|
||||
│ When: Skill instructions reference them │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
This minimizes context usage while maintaining full capability access.
|
||||
@@ -0,0 +1,587 @@
|
||||
# Advanced Skill Patterns
|
||||
|
||||
Patterns from official Anthropic examples and production skills. These extend the core concepts in [SKILL.md](../SKILL.md) and [best-practices.md](./best-practices.md).
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Degrees of Freedom](#degrees-of-freedom)
|
||||
- [Script Design Principles](#script-design-principles)
|
||||
- [Variant Organization](#variant-organization)
|
||||
- [Reference File Structure](#reference-file-structure)
|
||||
- [Visual Indicators](#visual-indicators)
|
||||
- [Writing Patterns](#writing-patterns)
|
||||
- [Naming Patterns](#naming-patterns)
|
||||
|
||||
---
|
||||
|
||||
## Degrees of Freedom
|
||||
|
||||
Control how much latitude Claude has when executing instructions.
|
||||
|
||||
### High Freedom (Text Instructions)
|
||||
|
||||
Use when multiple valid approaches exist. Claude applies judgment.
|
||||
|
||||
```markdown
|
||||
## Data Validation
|
||||
|
||||
Validate user input before processing. Check for:
|
||||
- Required fields present
|
||||
- Data types match schema
|
||||
- Values within acceptable ranges
|
||||
|
||||
Handle invalid input gracefully with clear error messages.
|
||||
```
|
||||
|
||||
**When to use:** Creative tasks, flexible requirements, exploratory work.
|
||||
|
||||
### Medium Freedom (Pseudocode)
|
||||
|
||||
Use when a preferred pattern exists but variation is acceptable.
|
||||
|
||||
```markdown
|
||||
## Data Validation
|
||||
|
||||
1. Extract fields from input
|
||||
2. For each field:
|
||||
- Check type matches schema[field].type
|
||||
- Check value passes schema[field].validator
|
||||
- Collect errors for invalid fields
|
||||
3. If errors: return { valid: false, errors }
|
||||
4. Return { valid: true, data: sanitized }
|
||||
```
|
||||
|
||||
**When to use:** Standard workflows, established patterns, moderate complexity.
|
||||
|
||||
### Low Freedom (Specific Scripts)
|
||||
|
||||
Use for fragile operations requiring exact sequences.
|
||||
|
||||
```markdown
|
||||
## Data Validation
|
||||
|
||||
Run the validation script:
|
||||
|
||||
```bash
|
||||
bun run scripts/validate.ts --schema=user.json --input=$INPUT_FILE
|
||||
```
|
||||
|
||||
Do not modify the validation logic inline. If changes are needed, update scripts/validate.ts.
|
||||
|
||||
```
|
||||
|
||||
**When to use:** Security-critical, deterministic reliability, complex algorithms.
|
||||
|
||||
### Selection Guide
|
||||
|
||||
| Scenario | Freedom Level |
|
||||
|----------|---------------|
|
||||
| Creative writing, exploration | High |
|
||||
| Standard CRUD operations | Medium |
|
||||
| Authentication flows | Low |
|
||||
| Database migrations | Low |
|
||||
| API integrations | Medium |
|
||||
| Error message formatting | High |
|
||||
| Cryptographic operations | Low (always script) |
|
||||
|
||||
---
|
||||
|
||||
## Script Design Principles
|
||||
|
||||
Scripts in `scripts/` should be robust and informative.
|
||||
|
||||
### Solve, Don't Punt
|
||||
|
||||
Scripts should handle errors explicitly rather than failing to Claude.
|
||||
|
||||
**Good (solves the problem):**
|
||||
|
||||
```python
|
||||
def process_file(path: str) -> str:
|
||||
"""Process file, creating if doesn't exist."""
|
||||
try:
|
||||
with open(path) as f:
|
||||
return f.read()
|
||||
except FileNotFoundError:
|
||||
print(f"File {path} not found. Creating empty file.")
|
||||
Path(path).parent.mkdir(parents=True, exist_ok=True)
|
||||
Path(path).touch()
|
||||
return ""
|
||||
except PermissionError:
|
||||
print(f"Permission denied for {path}. Try: chmod 644 {path}")
|
||||
raise
|
||||
```
|
||||
|
||||
**Bad (punts to Claude):**
|
||||
|
||||
```python
|
||||
def process_file(path: str) -> str:
|
||||
return open(path).read() # Fails, Claude figures it out
|
||||
```
|
||||
|
||||
### Actionable Error Messages
|
||||
|
||||
Include specific suggestions for resolution.
|
||||
|
||||
```python
|
||||
if not api_key:
|
||||
print("Error: API_KEY not set")
|
||||
print("Fix: export API_KEY=your-key-here")
|
||||
print("Or create .env file with API_KEY=...")
|
||||
sys.exit(1)
|
||||
```
|
||||
|
||||
### Document Non-Obvious Values
|
||||
|
||||
No "voodoo constants" - explain why values are chosen.
|
||||
|
||||
```python
|
||||
# Rate limit: 100 requests per minute (API docs: https://api.example.com/limits)
|
||||
RATE_LIMIT = 100
|
||||
|
||||
# Timeout: 30s based on P99 latency from production metrics
|
||||
TIMEOUT_SECONDS = 30
|
||||
|
||||
# Retry count: 3 attempts covers transient failures without excessive delay
|
||||
MAX_RETRIES = 3
|
||||
```
|
||||
|
||||
### Test Before Including
|
||||
|
||||
Run scripts with representative samples before bundling.
|
||||
|
||||
```markdown
|
||||
## Testing Checklist
|
||||
|
||||
- [ ] Script runs on clean environment
|
||||
- [ ] Handles missing dependencies gracefully
|
||||
- [ ] Error messages are actionable
|
||||
- [ ] Output format matches skill expectations
|
||||
- [ ] No hardcoded paths or credentials
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Variant Organization
|
||||
|
||||
For skills supporting multiple frameworks, providers, or approaches.
|
||||
|
||||
### Pattern: Selection in SKILL.md, Details in References
|
||||
|
||||
**SKILL.md structure:**
|
||||
|
||||
```markdown
|
||||
# Cloud Deployment
|
||||
|
||||
Deploy applications to major cloud providers.
|
||||
|
||||
## Provider Selection
|
||||
|
||||
| Provider | Best For |
|
||||
|----------|----------|
|
||||
| AWS | Enterprise, full-stack |
|
||||
| GCP | Data/ML workloads |
|
||||
| Azure | Microsoft ecosystem |
|
||||
|
||||
Choose provider based on requirements, then see specific guide.
|
||||
|
||||
## Deployment Workflow
|
||||
|
||||
1. Configure credentials (provider-specific)
|
||||
2. Define infrastructure (see provider guide)
|
||||
3. Deploy: `deploy.sh --provider=<provider>`
|
||||
4. Verify deployment health
|
||||
|
||||
## Provider Guides
|
||||
|
||||
- **AWS**: See [references/aws.md](references/aws.md)
|
||||
- **GCP**: See [references/gcp.md](references/gcp.md)
|
||||
- **Azure**: See [references/azure.md](references/azure.md)
|
||||
```
|
||||
|
||||
**Each reference file is complete and standalone:**
|
||||
|
||||
```markdown
|
||||
# AWS Deployment Guide
|
||||
|
||||
Complete guide for deploying to AWS.
|
||||
|
||||
## Prerequisites
|
||||
- AWS CLI installed
|
||||
- IAM credentials configured
|
||||
|
||||
## Infrastructure Setup
|
||||
[Complete AWS-specific content]
|
||||
|
||||
## Deployment
|
||||
[Complete AWS-specific content]
|
||||
|
||||
## Troubleshooting
|
||||
[AWS-specific issues]
|
||||
```
|
||||
|
||||
### Why This Pattern Works
|
||||
|
||||
1. **Context efficiency**: Only load the relevant variant
|
||||
2. **Independent evolution**: Update one provider without touching others
|
||||
3. **Clear selection**: User picks once, then gets focused content
|
||||
4. **No cross-contamination**: Each guide is complete without assumptions
|
||||
|
||||
### Anti-Pattern: Mixed Content
|
||||
|
||||
**Avoid:**
|
||||
|
||||
```markdown
|
||||
## Deployment
|
||||
|
||||
For AWS: `aws s3 cp`
|
||||
For GCP: `gsutil cp`
|
||||
For Azure: `az storage blob upload`
|
||||
|
||||
Then for AWS do X, but for GCP do Y, and Azure is different...
|
||||
```
|
||||
|
||||
This creates cognitive load and wastes tokens.
|
||||
|
||||
---
|
||||
|
||||
## Reference File Structure
|
||||
|
||||
Patterns for organizing reference files effectively.
|
||||
|
||||
### Table of Contents for Large Files
|
||||
|
||||
Files over 100 lines should include a TOC for partial reads.
|
||||
|
||||
```markdown
|
||||
# API Reference
|
||||
|
||||
## Contents
|
||||
|
||||
- [Authentication](#authentication) - Setup and credential management
|
||||
- [Core Methods](#core-methods) - CRUD operations
|
||||
- [Batch Operations](#batch-operations) - Bulk processing
|
||||
- [Webhooks](#webhooks) - Event notifications
|
||||
- [Error Handling](#error-handling) - Status codes and recovery
|
||||
- [Rate Limits](#rate-limits) - Throttling and quotas
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
[Section content...]
|
||||
|
||||
## Core Methods
|
||||
|
||||
[Section content...]
|
||||
```
|
||||
|
||||
**Why it matters:** Claude may use `head -100` previews. A TOC ensures visibility of full scope even in partial reads.
|
||||
|
||||
### Conditional Loading Patterns
|
||||
|
||||
**Bold keywords with links:**
|
||||
|
||||
```markdown
|
||||
**For tracked changes**: See [REDLINING.md](REDLINING.md)
|
||||
**For complex formatting**: See [OOXML.md](OOXML.md)
|
||||
```
|
||||
|
||||
**Bullet arrows:**
|
||||
|
||||
```markdown
|
||||
- **Form filling** -> See [FORMS.md](FORMS.md) for complete guide
|
||||
- **API reference** -> See [REFERENCE.md](REFERENCE.md) for all methods
|
||||
```
|
||||
|
||||
**Domain-based routing:**
|
||||
|
||||
```markdown
|
||||
## Available Datasets
|
||||
|
||||
- **Finance**: Revenue, ARR, billing -> See [finance.md](references/finance.md)
|
||||
- **Sales**: Opportunities, pipeline -> See [sales.md](references/sales.md)
|
||||
- **Product**: API usage, features -> See [product.md](references/product.md)
|
||||
|
||||
## Quick Search
|
||||
|
||||
Find specific metrics:
|
||||
```bash
|
||||
grep -i "revenue" references/finance.md
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
### Keep References One Level Deep
|
||||
|
||||
```
|
||||
|
||||
# Good
|
||||
|
||||
SKILL.md -> reference.md
|
||||
|
||||
# Bad (too deep)
|
||||
|
||||
SKILL.md -> advanced.md -> details.md -> specifics.md
|
||||
|
||||
```
|
||||
|
||||
Claude may partially read nested files, getting incomplete information.
|
||||
|
||||
### Topic-Based File Naming
|
||||
|
||||
```
|
||||
|
||||
references/
|
||||
├── finance.md # Clear domain
|
||||
├── sales.md
|
||||
└── product.md
|
||||
|
||||
```
|
||||
|
||||
**Not:**
|
||||
|
||||
```
|
||||
|
||||
references/
|
||||
├── doc1.md # What's in this?
|
||||
├── reference2.md
|
||||
└── stuff.md
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Visual Indicators
|
||||
|
||||
Emoji conventions from official Anthropic skills.
|
||||
|
||||
### Reference Type Indicators
|
||||
|
||||
| Emoji | Meaning | Example |
|
||||
|-------|---------|---------|
|
||||
| `[icon]` | Guidelines/checklist | `[checklist] MCP Best Practices` |
|
||||
| `[lightning]` | Quick guide | `[lightning] Quick Start` |
|
||||
| `[python]` | Python-specific | `[python] Python Setup` |
|
||||
| `[check]` | Evaluation/testing | `[check] Test Suite` |
|
||||
|
||||
**In context:**
|
||||
|
||||
```markdown
|
||||
Load these resources as needed:
|
||||
- [checklist] [MCP Best Practices](references/best-practices.md)
|
||||
- [lightning] [Quick Start](references/quick-start.md)
|
||||
- [python] [Python Client](references/python.md)
|
||||
```
|
||||
|
||||
### Status Indicators
|
||||
|
||||
```markdown
|
||||
## Implementation Status
|
||||
|
||||
- [check] Core API endpoints
|
||||
- [check] Authentication flow
|
||||
- [pending] Webhook handlers
|
||||
- [x] Rate limiting
|
||||
```
|
||||
|
||||
### When to Use
|
||||
|
||||
- Making references scannable
|
||||
- Indicating content type at a glance
|
||||
- Categorizing in lists
|
||||
|
||||
### When to Avoid
|
||||
|
||||
- Main body text (distracting)
|
||||
- Already-clear headings
|
||||
- User-facing output (unless requested)
|
||||
|
||||
---
|
||||
|
||||
## Writing Patterns
|
||||
|
||||
Consistent style for skill instructions.
|
||||
|
||||
### Imperative Voice
|
||||
|
||||
Always use imperative/infinitive form.
|
||||
|
||||
```markdown
|
||||
# Good
|
||||
Run the script.
|
||||
Create a mapping.
|
||||
Validate the output.
|
||||
|
||||
# Bad
|
||||
You should run the script.
|
||||
The script can be run.
|
||||
It's recommended to run the script.
|
||||
```
|
||||
|
||||
### Concise Examples Over Explanations
|
||||
|
||||
Assume Claude's base knowledge. Don't explain fundamentals.
|
||||
|
||||
**Good:**
|
||||
|
||||
```python
|
||||
# Extract text from PDF
|
||||
with pdfplumber.open("file.pdf") as pdf:
|
||||
text = pdf.pages[0].extract_text()
|
||||
```
|
||||
|
||||
**Bad:**
|
||||
|
||||
```markdown
|
||||
PDFs (Portable Document Format) are a common file format developed by Adobe
|
||||
that contains text, images, and formatting information. To extract text from
|
||||
a PDF file, you'll need to use a specialized library. We recommend pdfplumber
|
||||
because it's easy to use and handles most PDF formats. First, you'll need to
|
||||
install it with pip install pdfplumber, then you can open the file and...
|
||||
|
||||
[50 more lines explaining basic concepts]
|
||||
```
|
||||
|
||||
### Template Pattern
|
||||
|
||||
For strict output requirements, provide exact templates.
|
||||
|
||||
```markdown
|
||||
ALWAYS use this exact commit message format:
|
||||
|
||||
```
|
||||
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
|
||||
<footer>
|
||||
```
|
||||
|
||||
Types: feat, fix, docs, style, refactor, test, chore
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
feat(auth): add refresh token rotation
|
||||
|
||||
Implements automatic token rotation on refresh to improve security.
|
||||
Tokens are invalidated after single use.
|
||||
|
||||
Closes #123
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
### Checklist Pattern
|
||||
|
||||
For multi-step validation workflows.
|
||||
|
||||
```markdown
|
||||
## Pre-Deploy Checklist
|
||||
|
||||
- [ ] All tests pass: `bun test`
|
||||
- [ ] No linting errors: `bun lint`
|
||||
- [ ] Build succeeds: `bun run build`
|
||||
- [ ] Environment variables set
|
||||
- [ ] Database migrations applied
|
||||
- [ ] Health check endpoint responds
|
||||
|
||||
Do not proceed until all items are checked.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Naming Patterns
|
||||
|
||||
Conventions for skill, file, and reference naming.
|
||||
|
||||
### Gerund Form (Preferred)
|
||||
|
||||
Use verb + -ing form for skill names.
|
||||
|
||||
```
|
||||
processing-pdfs
|
||||
analyzing-spreadsheets
|
||||
managing-databases
|
||||
testing-code
|
||||
writing-documentation
|
||||
deploying-applications
|
||||
debugging-issues
|
||||
```
|
||||
|
||||
### Noun Form (Acceptable)
|
||||
|
||||
When gerund feels awkward.
|
||||
|
||||
```
|
||||
pdf-processing
|
||||
spreadsheet-analysis
|
||||
code-review
|
||||
api-integration
|
||||
```
|
||||
|
||||
### Avoid
|
||||
|
||||
```
|
||||
# Vague
|
||||
helper
|
||||
utils
|
||||
tools
|
||||
stuff
|
||||
|
||||
# Too Generic
|
||||
documents
|
||||
data
|
||||
files
|
||||
code
|
||||
|
||||
# Reserved Words
|
||||
anthropic-helper
|
||||
claude-tools
|
||||
claude-assistant
|
||||
```
|
||||
|
||||
### File Naming
|
||||
|
||||
```
|
||||
references/
|
||||
├── authentication.md # Domain topic
|
||||
├── error-handling.md # Concept
|
||||
├── aws-deployment.md # Variant-specific
|
||||
└── quick-start.md # Purpose
|
||||
```
|
||||
|
||||
**Not:**
|
||||
|
||||
```
|
||||
references/
|
||||
├── ref1.md
|
||||
├── DOCS.md
|
||||
├── more_stuff.md
|
||||
└── NEW-FILE.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Pattern | When to Use |
|
||||
|---------|-------------|
|
||||
| Degrees of Freedom | Control Claude's latitude per task type |
|
||||
| Solve Don't Punt | Scripts should handle errors, not fail to Claude |
|
||||
| Variant Organization | Multi-framework/provider skills |
|
||||
| TOC in References | Large files (>100 lines) |
|
||||
| Visual Indicators | Make reference lists scannable |
|
||||
| Imperative Voice | All instructions |
|
||||
| Gerund Naming | Skill and file names |
|
||||
|
||||
## Sources
|
||||
|
||||
Patterns derived from:
|
||||
- Official Anthropic skills repository (pdf, skill-creator, mcp-builder)
|
||||
- Anthropic Agent Skills Best Practices documentation
|
||||
- Production skill analysis
|
||||
|
||||
Last updated: 2026-01-10
|
||||
@@ -0,0 +1,222 @@
|
||||
# Quick Reference: Skills Best Practices
|
||||
|
||||
Fast checklist for skill development. See [best-practices.md](./best-practices.md) for detailed explanations.
|
||||
|
||||
## Skill Creation Checklist
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # < 500 lines, core workflow
|
||||
├── references/ # Deep dives (loaded on demand)
|
||||
│ ├── patterns.md
|
||||
│ ├── examples.md
|
||||
│ └── advanced.md
|
||||
└── scripts/ # Helper utilities
|
||||
```
|
||||
|
||||
### SKILL.md Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: kebab-case-name
|
||||
description: What it does AND when to use it. Trigger terms: keywords, phrases.
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
<when_to_use>
|
||||
Clear criteria for when this applies
|
||||
</when_to_use>
|
||||
|
||||
<workflow>
|
||||
1. Step one
|
||||
2. Step two
|
||||
3. Step three
|
||||
</workflow>
|
||||
|
||||
<rules>
|
||||
- ALWAYS: Do this
|
||||
- NEVER: Don't do that
|
||||
- PREFER: Recommended approach
|
||||
</rules>
|
||||
|
||||
<references>
|
||||
- [Pattern details](references/patterns.md)
|
||||
- [Examples](references/examples.md)
|
||||
</references>
|
||||
```
|
||||
|
||||
## Description Checklist
|
||||
|
||||
- [ ] Third-person voice ("Creates reports" not "I create reports")
|
||||
- [ ] Includes WHAT skill does
|
||||
- [ ] Includes WHEN to use it
|
||||
- [ ] Lists trigger terms users might say
|
||||
- [ ] Under 100 tokens
|
||||
- [ ] Specific, not generic
|
||||
|
||||
✅ **Good**: "Implements test-driven development using Red-Green-Refactor cycles. Use when implementing features with tests first, refactoring with test coverage, or reproducing bugs. Keywords: TDD, test-first, red-green-refactor."
|
||||
|
||||
❌ **Bad**: "Helps with testing"
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
| Mistake | Fix |
|
||||
|---------|-----|
|
||||
| Verbose SKILL.md (1000+ lines) | Keep under 500, move details to references/ |
|
||||
| "NEVER do X" without alternatives | "ALWAYS do Y; NEVER do X" |
|
||||
| Deeply nested references (3+ levels) | Keep 1 level deep with table of contents |
|
||||
| No version control | Track in git with semantic versioning |
|
||||
| No examples | Add 1-2 examples in references/examples.md |
|
||||
| Unclear scope (skill does too much) | One skill, one job |
|
||||
| Testing only with Sonnet | Test with Haiku, Sonnet, AND Opus |
|
||||
| Static text without action | Make it executable/testable |
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
### Before Publishing
|
||||
|
||||
- [ ] Test with Haiku (needs more explicit instructions?)
|
||||
- [ ] Test with Sonnet (balanced clarity?)
|
||||
- [ ] Test with Opus (handles complexity?)
|
||||
- [ ] Use skill for real work (dogfooding)
|
||||
- [ ] Check description triggers discovery correctly
|
||||
- [ ] Verify workflow completes successfully
|
||||
- [ ] Review security (no malicious code)
|
||||
- [ ] Under 500 lines in SKILL.md
|
||||
- [ ] References properly linked
|
||||
|
||||
### Ongoing Validation
|
||||
|
||||
- [ ] Track skill load frequency
|
||||
- [ ] Monitor completion rate
|
||||
- [ ] Log user satisfaction
|
||||
- [ ] Note when Claude asks for clarification (skill unclear?)
|
||||
- [ ] Build regression tests for critical paths
|
||||
|
||||
## Composition Patterns
|
||||
|
||||
### Reference Other Skills
|
||||
|
||||
```markdown
|
||||
Load the **outfitter:debugging** skill using the Skill tool to investigate.
|
||||
```
|
||||
|
||||
### Skill Chaining
|
||||
|
||||
```markdown
|
||||
1. Load **pathfinding** skill for planning
|
||||
2. Load **tdd** skill for implementation
|
||||
3. Load **code-review** skill for validation
|
||||
```
|
||||
|
||||
### Skills + MCP
|
||||
|
||||
- **MCP**: Data access (APIs, databases, tools)
|
||||
- **Skill**: Workflows (what to do with that data)
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
```
|
||||
Discovery (50 tokens) → YAML frontmatter
|
||||
↓
|
||||
Activation (2-5K tokens) → SKILL.md core
|
||||
↓
|
||||
Execution (dynamic) → references/ loaded on demand
|
||||
```
|
||||
|
||||
**Key**: Don't load everything upfront. Let Claude request detail.
|
||||
|
||||
## Degrees of Freedom
|
||||
|
||||
| Level | Format | When to Use |
|
||||
|-------|--------|-------------|
|
||||
| **High** | Text instructions | Creative tasks, multiple valid approaches |
|
||||
| **Medium** | Pseudocode | Standard patterns with variation allowed |
|
||||
| **Low** | Scripts | Security-critical, exact sequence required |
|
||||
|
||||
**Examples:**
|
||||
|
||||
| Task | Freedom |
|
||||
|------|---------|
|
||||
| Error message formatting | High |
|
||||
| API integration | Medium |
|
||||
| Authentication flows | Low |
|
||||
| Database migrations | Low |
|
||||
| Code formatting | High |
|
||||
|
||||
## Security Quick Check
|
||||
|
||||
- [ ] Review all scripts in scripts/ directory
|
||||
- [ ] No credential harvesting (API keys, tokens)
|
||||
- [ ] No unexpected file system writes
|
||||
- [ ] No suspicious network requests
|
||||
- [ ] No obfuscated code
|
||||
- [ ] Verify external dependencies
|
||||
- [ ] Test in isolated environment first
|
||||
|
||||
## Description Optimization Formula
|
||||
|
||||
```
|
||||
[What it does] + [When to use] + [Trigger keywords]
|
||||
```
|
||||
|
||||
**Example**:
|
||||
"Debugs issues using systematic root cause analysis. Use when encountering errors, unexpected behavior, or test failures. Keywords: debug, troubleshoot, error, failure, bug."
|
||||
|
||||
## Versioning Rules
|
||||
|
||||
- **MAJOR** (1.0.0 → 2.0.0): Breaking changes (workflow changed, different inputs)
|
||||
- **MINOR** (1.0.0 → 1.1.0): New features (additional optional steps)
|
||||
- **PATCH** (1.0.0 → 1.0.1): Bug fixes (typos, clarifications)
|
||||
|
||||
## One-Liners to Remember
|
||||
|
||||
1. **Assume intelligence** - Claude doesn't need basic concepts explained
|
||||
2. **Be directive, not comprehensive** - Focus on what makes THIS approach different
|
||||
3. **One skill, one job** - Don't make Swiss Army knife skills
|
||||
4. **Test like code** - Build evals, use version control, review changes
|
||||
5. **Progressive disclosure** - Start small, load detail on demand
|
||||
6. **Security matters** - Skills execute code; review carefully
|
||||
7. **Positive constraints** - Tell what TO do, not just what NOT to do
|
||||
8. **Examples clarify** - Non-obvious patterns need concrete examples
|
||||
9. **Version semantically** - Breaking changes = major version bump
|
||||
10. **Dogfood relentlessly** - Use your own skills for real work
|
||||
|
||||
## Advanced Patterns Quick List
|
||||
|
||||
- **Degrees of freedom**: Match instruction specificity to task type
|
||||
- **Solve don't punt**: Scripts should handle errors, not fail to Claude
|
||||
- **Variant organization**: Multi-framework skills with selection in SKILL.md
|
||||
- **Hook-based validation**: PreToolUse for quality gates
|
||||
- **Master-Clone architecture**: Preserve context via subagents
|
||||
- **Eval-driven development**: Tests before extensive docs
|
||||
- **Organization-wide libraries**: Central skill registry
|
||||
- **Skills as living docs**: Replace static wikis
|
||||
- **Conditional chaining**: Orchestrate complex workflows
|
||||
- **ToC in references**: Navigate to specific sections (>100 lines)
|
||||
- **Skill contribution flow**: Treat like open source PRs
|
||||
|
||||
See [patterns.md](./patterns.md) for detailed examples.
|
||||
|
||||
## When to Create a Skill vs Other Tools
|
||||
|
||||
| Need | Use |
|
||||
|------|-----|
|
||||
| Multi-step workflow with judgment | **Skill** |
|
||||
| Simple shortcut/expansion | Slash command |
|
||||
| Data access / API integration | MCP server |
|
||||
| Specialized autonomous work | Subagent |
|
||||
| Event-triggered automation | Hook |
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Official docs**: <https://platform.claude.com/docs/en/agents-and-tools/agent-skills>
|
||||
- **Community**: ComposioHQ/awesome-claude-skills (GitHub)
|
||||
- **Research**: skillmatic-ai/awesome-agent-skills (GitHub)
|
||||
- **Examples**: Load existing well-crafted skills for patterns
|
||||
|
||||
Last updated: 2026-01-10
|
||||
@@ -0,0 +1,311 @@
|
||||
# Steps Pattern
|
||||
|
||||
Composable building blocks for skill workflows. Use when skills depend on other skills or have clear sequential stages.
|
||||
|
||||
## Basic Structure
|
||||
|
||||
```markdown
|
||||
# Skill Name
|
||||
|
||||
## Steps
|
||||
|
||||
1. Load the `plugin:prerequisite-skill` skill
|
||||
2. { main action }
|
||||
3. { next action }
|
||||
```
|
||||
|
||||
Place `## Steps` immediately after the H1 title, before any other content.
|
||||
|
||||
## Syntax
|
||||
|
||||
### Loading Skills
|
||||
|
||||
```markdown
|
||||
1. Load the `outfitter:skills-dev` skill
|
||||
```
|
||||
|
||||
Always use the full `plugin:skill-name` format. Never link to SKILL.md files.
|
||||
|
||||
### Conditional Steps
|
||||
|
||||
```markdown
|
||||
3. If working with TypeScript, load the `outfitter:typescript-dev` skill
|
||||
4. If tests fail, load the `outfitter:debugging` skill
|
||||
```
|
||||
|
||||
Conditions should be brief and contextual.
|
||||
|
||||
### Action Steps
|
||||
|
||||
```markdown
|
||||
2. Analyze the codebase structure
|
||||
5. Generate the implementation plan
|
||||
```
|
||||
|
||||
Use imperative voice, drop articles, keep brief.
|
||||
|
||||
### Delegated Skills (Agent-Handled)
|
||||
|
||||
Skills with `context: fork` + `agent` delegate work to agents rather than loading instructions into the current context. Use "delegate by loading" language:
|
||||
|
||||
```markdown
|
||||
3. Delegate by loading the `outfitter:security-audit` skill for vulnerability analysis
|
||||
4. Delegate by loading the `outfitter:codebase-recon` skill for deep analysis
|
||||
```
|
||||
|
||||
**Key difference**:
|
||||
- `Load the skill` → instructions enter current context
|
||||
- `Delegate by loading the skill` → agent runs in isolated context, returns results
|
||||
|
||||
Delegated skills are defined with:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: security-audit
|
||||
context: fork
|
||||
agent: outfitter:reviewer
|
||||
model: sonnet
|
||||
---
|
||||
```
|
||||
|
||||
When referenced in Steps, make the delegation explicit so readers understand work happens in a subagent.
|
||||
|
||||
### Branching Workflows
|
||||
|
||||
```markdown
|
||||
## Steps
|
||||
|
||||
1. Load the `outfitter:codebase-recon` skill
|
||||
2. Investigate the problem area
|
||||
3. Based on findings:
|
||||
- If pattern issue → load `outfitter:patterns` skill
|
||||
- If root cause needed → load `outfitter:find-root-causes` skill
|
||||
- If ready to report → load `outfitter:report-findings` skill
|
||||
```
|
||||
|
||||
### Plan Mode and User Questions
|
||||
|
||||
Use Plan mode and AskUserQuestion for workflows that need user input or have decision points:
|
||||
|
||||
```markdown
|
||||
## Steps
|
||||
|
||||
1. Delegate by loading the `outfitter:claude-plugin-audit` skill for analysis
|
||||
2. Apply auto-fixable issues
|
||||
3. Enter Plan mode
|
||||
4. Present remaining issues with AskUserQuestion
|
||||
```
|
||||
|
||||
**Why Plan mode?** Claude thinks more carefully and presents options sequentially. Good for:
|
||||
- Transitioning from automated to manual work
|
||||
- Complex decisions requiring user input
|
||||
- Presenting multiple options with tradeoffs
|
||||
|
||||
### Brainstorming with Plan Agent
|
||||
|
||||
For complex problems benefiting from multiple perspectives:
|
||||
|
||||
```markdown
|
||||
## Steps
|
||||
|
||||
1. Gather initial context
|
||||
2. Brainstorm with Plan agent for approaches
|
||||
3. Present options with AskUserQuestion
|
||||
4. Implement chosen approach
|
||||
```
|
||||
|
||||
The Plan agent (`subagent_type: Plan`) explores the problem space independently, returning with considered options. Gets more than one "mind" on the problem before committing to an approach.
|
||||
|
||||
## Examples
|
||||
|
||||
### Extension Skill (claude-skills)
|
||||
|
||||
```markdown
|
||||
# Claude Code Skills
|
||||
|
||||
## Steps
|
||||
|
||||
1. Load the `outfitter:skills-dev` skill
|
||||
2. Apply Claude Code-specific extensions from this skill
|
||||
```
|
||||
|
||||
Simple two-step: load base, extend with specifics.
|
||||
|
||||
### Research Workflow
|
||||
|
||||
```markdown
|
||||
# Technical Research
|
||||
|
||||
## Steps
|
||||
|
||||
1. Load the `outfitter:codebase-recon` skill
|
||||
2. Gather evidence from codebase
|
||||
3. If external research needed, use WebSearch/WebFetch
|
||||
4. Load the `outfitter:report-findings` skill
|
||||
5. Synthesize into structured report
|
||||
```
|
||||
|
||||
Linear workflow with conditional mid-step.
|
||||
|
||||
### Debugging Workflow
|
||||
|
||||
```markdown
|
||||
# Debugging
|
||||
|
||||
## Steps
|
||||
|
||||
1. Load the `outfitter:find-root-causes` skill
|
||||
2. Investigate with systematic diagnosis
|
||||
3. If code-level issue, apply fix
|
||||
4. If architectural issue, load the `outfitter:architecture` skill
|
||||
5. Validate fix resolves the issue
|
||||
```
|
||||
|
||||
Branching based on diagnosis outcome.
|
||||
|
||||
### TDD Workflow
|
||||
|
||||
```markdown
|
||||
# Test-Driven Development
|
||||
|
||||
## Steps
|
||||
|
||||
1. Write failing test (Red)
|
||||
2. Implement minimal code to pass (Green)
|
||||
3. Load the `outfitter:simplify` skill
|
||||
4. Refactor while keeping tests green
|
||||
5. Repeat from step 1 for next requirement
|
||||
```
|
||||
|
||||
Cyclical workflow with embedded skill.
|
||||
|
||||
### Security Review with Delegated Skill
|
||||
|
||||
```markdown
|
||||
# Pre-Merge Security Check
|
||||
|
||||
## Steps
|
||||
|
||||
1. Gather changed files from PR
|
||||
2. Delegate by loading the `outfitter:security-audit` skill for vulnerability scan
|
||||
3. Review findings and severity levels
|
||||
4. If critical issues, block merge with explanation
|
||||
5. If clean, approve with security sign-off
|
||||
```
|
||||
|
||||
The `security-audit` skill has `context: fork` and `agent: outfitter:reviewer`, so step 2 delegates to a subagent. Results return to main context for steps 3-5.
|
||||
|
||||
## Guidelines
|
||||
|
||||
### Keep Steps Brief
|
||||
|
||||
Each step should be one line. If a step needs explanation, the detail belongs in the skill body, not the steps.
|
||||
|
||||
```markdown
|
||||
# Good
|
||||
2. Analyze authentication patterns
|
||||
|
||||
# Bad
|
||||
2. Analyze authentication patterns including OAuth flows, JWT handling,
|
||||
session management, and credential storage
|
||||
```
|
||||
|
||||
### 3-6 Steps Ideal
|
||||
|
||||
- Fewer than 3: probably doesn't need Steps section
|
||||
- More than 6: consider splitting into stages or separate skills
|
||||
|
||||
### Steps vs Workflow Tag
|
||||
|
||||
| Use `## Steps` | Use `<workflow>` tag |
|
||||
|----------------|---------------------|
|
||||
| Dependencies on other skills | Self-contained process |
|
||||
| High-level orchestration | Detailed methodology |
|
||||
| Composable building blocks | Single-skill workflow |
|
||||
|
||||
Can combine both: Steps for orchestration, `<workflow>` for detail within a step.
|
||||
|
||||
### Steps vs Stages
|
||||
|
||||
Steps are for the top-level flow. Stages are for detailed breakdown within the skill body.
|
||||
|
||||
```markdown
|
||||
# Skill Name
|
||||
|
||||
## Steps
|
||||
|
||||
1. Load prerequisite skill
|
||||
2. Execute Stage 1-3 below
|
||||
3. Load synthesis skill
|
||||
|
||||
## Stage 1: Discovery
|
||||
{ detailed content }
|
||||
|
||||
## Stage 2: Analysis
|
||||
{ detailed content }
|
||||
|
||||
## Stage 3: Output
|
||||
{ detailed content }
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### Linking to SKILL.md
|
||||
|
||||
```markdown
|
||||
# Wrong
|
||||
1. See [skills-dev](../skills-dev/SKILL.md) for base patterns
|
||||
|
||||
# Right
|
||||
1. Load the `outfitter:skills-dev` skill
|
||||
```
|
||||
|
||||
### Verbose Steps
|
||||
|
||||
```markdown
|
||||
# Wrong
|
||||
1. First, you should load the skills-dev skill which provides the base
|
||||
Agent Skills specification that this skill extends
|
||||
|
||||
# Right
|
||||
1. Load the `outfitter:skills-dev` skill
|
||||
```
|
||||
|
||||
### Steps That Are Just Headers
|
||||
|
||||
```markdown
|
||||
# Wrong - these are stages, not steps
|
||||
## Steps
|
||||
1. Discovery
|
||||
2. Analysis
|
||||
3. Synthesis
|
||||
|
||||
# Right - actionable steps
|
||||
## Steps
|
||||
1. Load the `outfitter:codebase-recon` skill
|
||||
2. Investigate problem area
|
||||
3. Load the `outfitter:report-findings` skill
|
||||
```
|
||||
|
||||
### Too Many Steps
|
||||
|
||||
```markdown
|
||||
# Wrong - this is a detailed workflow, not steps
|
||||
## Steps
|
||||
1. Read the error message
|
||||
2. Check the stack trace
|
||||
3. Find the failing line
|
||||
4. Read surrounding context
|
||||
5. Form hypothesis
|
||||
6. Add logging
|
||||
7. Reproduce issue
|
||||
8. Verify hypothesis
|
||||
9. Implement fix
|
||||
10. Run tests
|
||||
|
||||
# Right - high-level steps, detail in body
|
||||
## Steps
|
||||
1. Load the `outfitter:find-root-causes` skill
|
||||
2. Diagnose with systematic investigation
|
||||
3. Implement and validate fix
|
||||
```
|
||||
+271
@@ -0,0 +1,271 @@
|
||||
#!/usr/bin/env bun
|
||||
|
||||
/**
|
||||
* Initialize a new Claude skill from template or scratch
|
||||
*
|
||||
* Usage:
|
||||
* bun run init-skill.ts <skill-name> <output-dir>
|
||||
* bun run init-skill.ts <skill-name> <output-dir> --template <template-name>
|
||||
*
|
||||
* Templates: api-wrapper, document-processor, dev-workflow, research-synthesizer, simple
|
||||
*/
|
||||
|
||||
import * as fs from "node:fs";
|
||||
import { homedir } from "node:os";
|
||||
import * as path from "node:path";
|
||||
|
||||
const SCRIPT_DIR = path.dirname(new URL(import.meta.url).pathname);
|
||||
const TEMPLATES_DIR = path.join(SCRIPT_DIR, "../templates/skill-archetypes");
|
||||
|
||||
/**
|
||||
* Result of skill initialization.
|
||||
*/
|
||||
interface InitResult {
|
||||
/** Whether initialization succeeded or failed */
|
||||
status: "success" | "error";
|
||||
/** Path to created skill directory */
|
||||
skillDir?: string;
|
||||
/** Template used if any */
|
||||
template?: string;
|
||||
/** Files created during initialization */
|
||||
files?: string[];
|
||||
/** Suggested next steps after initialization */
|
||||
nextSteps?: string[];
|
||||
/** Error message if status is "error" */
|
||||
error?: string;
|
||||
/** Available templates when template not found */
|
||||
availableTemplates?: string[];
|
||||
}
|
||||
|
||||
function getAvailableTemplates(): string[] {
|
||||
if (!fs.existsSync(TEMPLATES_DIR)) return [];
|
||||
return fs
|
||||
.readdirSync(TEMPLATES_DIR)
|
||||
.filter((f) => fs.statSync(path.join(TEMPLATES_DIR, f)).isDirectory());
|
||||
}
|
||||
|
||||
function copyDir(src: string, dest: string): string[] {
|
||||
const copiedFiles: string[] = [];
|
||||
fs.mkdirSync(dest, { recursive: true });
|
||||
|
||||
for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
|
||||
// Prevent path traversal attacks
|
||||
if (entry.name.includes("..") || path.isAbsolute(entry.name)) {
|
||||
throw new Error(`Invalid file name: ${entry.name}`);
|
||||
}
|
||||
const srcPath = path.join(src, entry.name);
|
||||
// Rename SKILL.template.md to SKILL.md during copy
|
||||
const destName =
|
||||
entry.name === "SKILL.template.md" ? "SKILL.md" : entry.name;
|
||||
const destPath = path.join(dest, destName);
|
||||
|
||||
if (entry.isDirectory()) {
|
||||
copiedFiles.push(...copyDir(srcPath, destPath));
|
||||
} else {
|
||||
fs.copyFileSync(srcPath, destPath);
|
||||
copiedFiles.push(path.relative(dest, destPath) || destName);
|
||||
}
|
||||
}
|
||||
|
||||
return copiedFiles;
|
||||
}
|
||||
|
||||
function toTitleCase(str: string): string {
|
||||
return str
|
||||
.split("-")
|
||||
.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
|
||||
.join(" ");
|
||||
}
|
||||
|
||||
function createMinimalSkill(skillName: string, outputDir: string): InitResult {
|
||||
const skillDir = path.join(outputDir, skillName);
|
||||
|
||||
if (fs.existsSync(skillDir)) {
|
||||
return {
|
||||
status: "error",
|
||||
error: `Directory already exists: ${skillDir}`,
|
||||
};
|
||||
}
|
||||
|
||||
fs.mkdirSync(skillDir, { recursive: true });
|
||||
|
||||
const titleName = toTitleCase(skillName);
|
||||
const skillMd = `---
|
||||
name: ${titleName}
|
||||
description: TODO - Describe what this skill does and when to use it. Include trigger keywords users might mention.
|
||||
---
|
||||
|
||||
# ${titleName}
|
||||
|
||||
## Quick Start
|
||||
|
||||
TODO: Fastest path to value (3-5 lines)
|
||||
|
||||
## Instructions
|
||||
|
||||
When this skill is activated:
|
||||
|
||||
1. **Step 1**
|
||||
- Detail
|
||||
|
||||
2. **Step 2**
|
||||
- Detail
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Basic Usage
|
||||
|
||||
\`\`\`
|
||||
TODO: Add concrete example
|
||||
\`\`\`
|
||||
|
||||
## Best Practices
|
||||
|
||||
- TODO: Add best practices
|
||||
|
||||
## Related Skills
|
||||
|
||||
- TODO: Add related skills if any
|
||||
`;
|
||||
|
||||
fs.writeFileSync(path.join(skillDir, "SKILL.md"), skillMd);
|
||||
|
||||
return {
|
||||
status: "success",
|
||||
skillDir,
|
||||
files: ["SKILL.md"],
|
||||
nextSteps: [
|
||||
"Edit SKILL.md frontmatter - description is critical for discovery",
|
||||
"Replace all TODO placeholders with actual content",
|
||||
"Add examples that demonstrate real usage",
|
||||
"Run validate-claude-skill to check quality",
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
function createFromTemplate(
|
||||
skillName: string,
|
||||
outputDir: string,
|
||||
templateName: string,
|
||||
): InitResult {
|
||||
const templateDir = path.join(TEMPLATES_DIR, templateName);
|
||||
const availableTemplates = getAvailableTemplates();
|
||||
|
||||
if (!fs.existsSync(templateDir)) {
|
||||
return {
|
||||
status: "error",
|
||||
error: `Template '${templateName}' not found`,
|
||||
availableTemplates,
|
||||
};
|
||||
}
|
||||
|
||||
const skillDir = path.join(outputDir, skillName);
|
||||
|
||||
if (fs.existsSync(skillDir)) {
|
||||
return {
|
||||
status: "error",
|
||||
error: `Directory already exists: ${skillDir}`,
|
||||
};
|
||||
}
|
||||
|
||||
const files = copyDir(templateDir, skillDir);
|
||||
|
||||
// Make scripts executable
|
||||
const scriptsDir = path.join(skillDir, "scripts");
|
||||
if (fs.existsSync(scriptsDir)) {
|
||||
for (const script of fs.readdirSync(scriptsDir)) {
|
||||
const scriptPath = path.join(scriptsDir, script);
|
||||
fs.chmodSync(scriptPath, 0o755);
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
status: "success",
|
||||
skillDir,
|
||||
template: templateName,
|
||||
files,
|
||||
nextSteps: [
|
||||
"Replace all {{PLACEHOLDERS}} in SKILL.md with actual values",
|
||||
"Update scripts/ with your specific logic",
|
||||
"Craft a strong description for discoverability",
|
||||
"Test with real inputs",
|
||||
"Run validate-claude-skill to check quality",
|
||||
],
|
||||
};
|
||||
}
|
||||
|
||||
function showUsage(): void {
|
||||
const templates = getAvailableTemplates();
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
{
|
||||
usage: "init-skill.ts <skill-name> <output-dir> [--template <name>]",
|
||||
examples: [
|
||||
"bun run init-skill.ts my-skill ~/.claude/skills",
|
||||
"bun run init-skill.ts github-api .claude/skills --template api-wrapper",
|
||||
],
|
||||
availableTemplates: templates,
|
||||
templateDescriptions: {
|
||||
"api-wrapper": "For wrapping external APIs (REST, GraphQL)",
|
||||
"document-processor":
|
||||
"For working with file formats (PDF, DOCX, etc)",
|
||||
"dev-workflow": "For automating development tasks (git, CI, etc)",
|
||||
"research-synthesizer": "For gathering and synthesizing information",
|
||||
simple: "Minimal skill without scripts",
|
||||
},
|
||||
},
|
||||
null,
|
||||
2,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
// Main
|
||||
const args = process.argv.slice(2);
|
||||
|
||||
if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
|
||||
showUsage();
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
const templateIdx = args.indexOf("--template");
|
||||
let template: string | null = null;
|
||||
|
||||
if (templateIdx !== -1) {
|
||||
template = args[templateIdx + 1];
|
||||
args.splice(templateIdx, 2);
|
||||
}
|
||||
|
||||
const [skillName, outputDir] = args;
|
||||
|
||||
if (!skillName || !outputDir) {
|
||||
showUsage();
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Validate skill name (minimum 2 chars, kebab-case)
|
||||
if (skillName.length < 2 || !/^[a-z][a-z0-9-]*[a-z0-9]$|^[a-z]{2}$/.test(skillName)) {
|
||||
console.log(
|
||||
JSON.stringify({
|
||||
status: "error",
|
||||
error:
|
||||
"Skill name must be kebab-case (lowercase with hyphens, min 2 chars)",
|
||||
examples: ["my-skill", "github-api", "pdf-processor", "ai"],
|
||||
}),
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Expand ~ to home directory
|
||||
const expandedOutputDir = outputDir.replace(/^~/, homedir());
|
||||
|
||||
let result: InitResult;
|
||||
|
||||
if (template) {
|
||||
result = createFromTemplate(skillName, expandedOutputDir, template);
|
||||
} else {
|
||||
result = createMinimalSkill(skillName, expandedOutputDir);
|
||||
}
|
||||
|
||||
console.log(JSON.stringify(result, null, 2));
|
||||
process.exit(result.status === "success" ? 0 : 1);
|
||||
+59
@@ -0,0 +1,59 @@
|
||||
---
|
||||
name: {{API_NAME}}-api
|
||||
description: Interact with the {{API_NAME}} API. Use when {{TRIGGER_CONTEXTS}}. Supports {{CAPABILITIES}}.
|
||||
---
|
||||
|
||||
# {{API_NAME}} API
|
||||
|
||||
## Setup
|
||||
|
||||
Set your API key:
|
||||
|
||||
```bash
|
||||
export {{API_NAME_UPPER}}_API_KEY="your-key-here"
|
||||
```
|
||||
|
||||
## Available Operations
|
||||
|
||||
### {{OPERATION_1}}
|
||||
|
||||
{{Description of operation}}
|
||||
|
||||
```bash
|
||||
bun run scripts/client.ts {{operation_1}} --param value
|
||||
```
|
||||
|
||||
### {{OPERATION_2}}
|
||||
|
||||
{{Description of operation}}
|
||||
|
||||
```bash
|
||||
bun run scripts/client.ts {{operation_2}} --param value
|
||||
```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Workflow 1: {{WORKFLOW_NAME}}
|
||||
|
||||
1. First, {{step 1}}
|
||||
2. Then, {{step 2}}
|
||||
3. Finally, {{step 3}}
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Meaning | Resolution |
|
||||
|-------|---------|------------|
|
||||
| 401 | Invalid API key | Check {{API_NAME_UPPER}}_API_KEY is set correctly |
|
||||
| 429 | Rate limited | Wait and retry, or reduce request frequency |
|
||||
| 500 | Server error | Retry after a moment |
|
||||
|
||||
## Requirements
|
||||
|
||||
- Bun runtime
|
||||
- {{API_NAME_UPPER}}_API_KEY environment variable
|
||||
|
||||
## Tips
|
||||
|
||||
- Use `--verbose` flag for detailed output
|
||||
- Results are returned as JSON for easy parsing
|
||||
- Paginated endpoints support `--limit` and `--offset`
|
||||
+111
@@ -0,0 +1,111 @@
|
||||
#!/usr/bin/env bun
|
||||
|
||||
/**
|
||||
* {{API_NAME}} API Client
|
||||
*
|
||||
* Usage: bun run client.ts <command> [options]
|
||||
*/
|
||||
|
||||
const API_BASE = "https://api.example.com/v1";
|
||||
|
||||
function getApiKey(): string {
|
||||
const key = process.env.API_NAME_UPPER_API_KEY;
|
||||
if (!key) {
|
||||
console.error(
|
||||
JSON.stringify({
|
||||
error: "{{API_NAME_UPPER}}_API_KEY environment variable not set",
|
||||
fix: "export {{API_NAME_UPPER}}_API_KEY='your-key'",
|
||||
}),
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
return key;
|
||||
}
|
||||
|
||||
async function apiRequest<T>(
|
||||
endpoint: string,
|
||||
options: RequestInit = {},
|
||||
): Promise<T> {
|
||||
const url = `${API_BASE}${endpoint}`;
|
||||
const headers = {
|
||||
Authorization: `Bearer ${getApiKey()}`,
|
||||
"Content-Type": "application/json",
|
||||
...options.headers,
|
||||
};
|
||||
|
||||
const response = await fetch(url, { ...options, headers });
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.text();
|
||||
throw new Error(`API error ${response.status}: ${error}`);
|
||||
}
|
||||
|
||||
return response.json() as Promise<T>;
|
||||
}
|
||||
|
||||
// Example operations — replace with actual API endpoints
|
||||
|
||||
async function listItems(limit = 10) {
|
||||
return apiRequest<{ items: unknown[] }>(`/items?limit=${limit}`);
|
||||
}
|
||||
|
||||
async function getItem(id: string) {
|
||||
return apiRequest<{ item: unknown }>(`/items/${id}`);
|
||||
}
|
||||
|
||||
async function createItem(data: Record<string, unknown>) {
|
||||
return apiRequest<{ item: unknown }>("/items", {
|
||||
method: "POST",
|
||||
body: JSON.stringify(data),
|
||||
});
|
||||
}
|
||||
|
||||
// CLI handler
|
||||
async function main() {
|
||||
const [command, ...args] = process.argv.slice(2);
|
||||
|
||||
try {
|
||||
switch (command) {
|
||||
case "list": {
|
||||
const limit = args[0] ? parseInt(args[0], 10) : 10;
|
||||
const result = await listItems(limit);
|
||||
console.log(JSON.stringify(result, null, 2));
|
||||
break;
|
||||
}
|
||||
case "get": {
|
||||
if (!args[0]) throw new Error("Usage: get <id>");
|
||||
const result = await getItem(args[0]);
|
||||
console.log(JSON.stringify(result, null, 2));
|
||||
break;
|
||||
}
|
||||
case "create": {
|
||||
if (!args[0]) throw new Error("Usage: create <json-data>");
|
||||
const data = JSON.parse(args[0]);
|
||||
const result = await createItem(data);
|
||||
console.log(JSON.stringify(result, null, 2));
|
||||
break;
|
||||
}
|
||||
default:
|
||||
console.log(
|
||||
JSON.stringify({
|
||||
usage: "client.ts <list|get|create> [args]",
|
||||
commands: {
|
||||
list: "List items (optional: limit)",
|
||||
get: "Get item by ID",
|
||||
create: "Create item from JSON",
|
||||
},
|
||||
}),
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
} catch (error) {
|
||||
console.error(
|
||||
JSON.stringify({
|
||||
error: error instanceof Error ? error.message : String(error),
|
||||
}),
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
+81
@@ -0,0 +1,81 @@
|
||||
---
|
||||
name: {{WORKFLOW}}-workflow
|
||||
description: Automate {{WORKFLOW}} tasks. Use when {{TRIGGER_CONTEXTS}}. Supports {{CAPABILITIES}}.
|
||||
---
|
||||
|
||||
# {{WORKFLOW}} Workflow
|
||||
|
||||
## Commands
|
||||
|
||||
### {{COMMAND_1}}
|
||||
|
||||
{{Description}}
|
||||
|
||||
```bash
|
||||
bun run scripts/run.ts {{command_1}} [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--dry-run` — Preview without executing
|
||||
- `--verbose` — Show detailed output
|
||||
|
||||
### {{COMMAND_2}}
|
||||
|
||||
{{Description}}
|
||||
|
||||
```bash
|
||||
bun run scripts/run.ts {{command_2}} [options]
|
||||
```
|
||||
|
||||
## Safety
|
||||
|
||||
Destructive operations require confirmation:
|
||||
|
||||
```bash
|
||||
bun run scripts/run.ts dangerous-op
|
||||
# Prompts: "This will delete X. Continue? [y/N]"
|
||||
|
||||
bun run scripts/run.ts dangerous-op --force
|
||||
# Skips confirmation (use with caution)
|
||||
```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Workflow 1: {{WORKFLOW_NAME}}
|
||||
|
||||
1. Run `{{command_1}}` to {{step 1 purpose}}
|
||||
2. Review the output
|
||||
3. Run `{{command_2}}` to {{step 2 purpose}}
|
||||
|
||||
### Workflow 2: {{WORKFLOW_NAME_2}}
|
||||
|
||||
1. {{Step 1}}
|
||||
2. {{Step 2}}
|
||||
3. {{Step 3}}
|
||||
|
||||
## Idempotency
|
||||
|
||||
All commands are designed to be safely re-run:
|
||||
|
||||
- `init` — Creates only if not exists
|
||||
- `update` — Applies only changed items
|
||||
- `clean` — Removes only managed files
|
||||
|
||||
## Requirements
|
||||
|
||||
- Bun runtime
|
||||
- {{DEPENDENCIES}}
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Cause | Solution |
|
||||
|-------|-------|----------|
|
||||
| Permission denied | Insufficient access | Check file/directory permissions |
|
||||
| Already exists | Resource conflict | Use `--force` to overwrite |
|
||||
| Not found | Missing dependency | Ensure prerequisites are installed |
|
||||
|
||||
## Tips
|
||||
|
||||
- Always use `--dry-run` first for destructive operations
|
||||
- Check `--verbose` output for debugging
|
||||
- Commands are idempotent and safe to re-run
|
||||
+161
@@ -0,0 +1,161 @@
|
||||
#!/usr/bin/env bun
|
||||
|
||||
/**
|
||||
* {{WORKFLOW}} Workflow Runner
|
||||
*
|
||||
* Usage: bun run run.ts <command> [options]
|
||||
*/
|
||||
|
||||
import { $ } from "bun";
|
||||
|
||||
/**
|
||||
* Options for workflow execution.
|
||||
*/
|
||||
interface RunOptions {
|
||||
/** Preview without executing */
|
||||
dryRun: boolean;
|
||||
/** Show detailed output */
|
||||
verbose: boolean;
|
||||
/** Skip confirmations */
|
||||
force: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Result of a workflow command execution.
|
||||
*/
|
||||
interface RunResult {
|
||||
/** Execution status */
|
||||
status: "success" | "error" | "dry-run";
|
||||
/** Human-readable result message */
|
||||
message: string;
|
||||
/** Additional execution details */
|
||||
details?: unknown;
|
||||
}
|
||||
|
||||
function parseOptions(args: string[]): {
|
||||
command: string;
|
||||
options: RunOptions;
|
||||
args: string[];
|
||||
} {
|
||||
const options: RunOptions = {
|
||||
dryRun: false,
|
||||
verbose: false,
|
||||
force: false,
|
||||
};
|
||||
|
||||
const positional: string[] = [];
|
||||
|
||||
for (const arg of args) {
|
||||
if (arg === "--dry-run") options.dryRun = true;
|
||||
else if (arg === "--verbose") options.verbose = true;
|
||||
else if (arg === "--force") options.force = true;
|
||||
else positional.push(arg);
|
||||
}
|
||||
|
||||
return {
|
||||
command: positional[0] || "",
|
||||
options,
|
||||
args: positional.slice(1),
|
||||
};
|
||||
}
|
||||
|
||||
async function confirm(message: string): Promise<boolean> {
|
||||
process.stdout.write(`${message} [y/N] `);
|
||||
const response = await new Promise<string>((resolve) => {
|
||||
process.stdin.once("data", (data) => resolve(data.toString().trim()));
|
||||
});
|
||||
return response.toLowerCase() === "y";
|
||||
}
|
||||
|
||||
async function run(
|
||||
cmd: string,
|
||||
options: RunOptions,
|
||||
): Promise<{ stdout: string; exitCode: number }> {
|
||||
if (options.verbose) console.error(`[verbose] Running: ${cmd}`);
|
||||
if (options.dryRun) {
|
||||
console.error(`[dry-run] Would execute: ${cmd}`);
|
||||
return { stdout: "", exitCode: 0 };
|
||||
}
|
||||
|
||||
const result = await $`${{ raw: cmd }}`.quiet();
|
||||
return { stdout: result.stdout.toString(), exitCode: result.exitCode };
|
||||
}
|
||||
|
||||
// Command implementations — replace with actual logic
|
||||
|
||||
async function exampleSafeCommand(options: RunOptions): Promise<RunResult> {
|
||||
const { stdout } = await run("echo 'This is safe'", options);
|
||||
|
||||
return {
|
||||
status: options.dryRun ? "dry-run" : "success",
|
||||
message: "Safe command completed",
|
||||
details: { output: stdout.trim() },
|
||||
};
|
||||
}
|
||||
|
||||
async function exampleDestructiveCommand(
|
||||
options: RunOptions,
|
||||
): Promise<RunResult> {
|
||||
if (!options.force && !options.dryRun) {
|
||||
const confirmed = await confirm(
|
||||
"This will do something destructive. Continue?",
|
||||
);
|
||||
if (!confirmed) {
|
||||
return { status: "error", message: "Aborted by user" };
|
||||
}
|
||||
}
|
||||
|
||||
const { stdout } = await run("echo 'Doing destructive thing'", options);
|
||||
|
||||
return {
|
||||
status: options.dryRun ? "dry-run" : "success",
|
||||
message: "Destructive command completed",
|
||||
details: { output: stdout.trim() },
|
||||
};
|
||||
}
|
||||
|
||||
// CLI handler
|
||||
async function main() {
|
||||
const { command, options } = parseOptions(process.argv.slice(2));
|
||||
|
||||
let result: RunResult;
|
||||
|
||||
try {
|
||||
switch (command) {
|
||||
case "safe":
|
||||
result = await exampleSafeCommand(options);
|
||||
break;
|
||||
case "destructive":
|
||||
result = await exampleDestructiveCommand(options);
|
||||
break;
|
||||
default:
|
||||
result = {
|
||||
status: "error",
|
||||
message: JSON.stringify({
|
||||
usage:
|
||||
"run.ts <safe|destructive> [--dry-run] [--verbose] [--force]",
|
||||
commands: {
|
||||
safe: "Run a safe operation",
|
||||
destructive:
|
||||
"Run a destructive operation (requires confirmation)",
|
||||
},
|
||||
options: {
|
||||
"--dry-run": "Preview without executing",
|
||||
"--verbose": "Show detailed output",
|
||||
"--force": "Skip confirmations",
|
||||
},
|
||||
}),
|
||||
};
|
||||
}
|
||||
} catch (error) {
|
||||
result = {
|
||||
status: "error",
|
||||
message: error instanceof Error ? error.message : String(error),
|
||||
};
|
||||
}
|
||||
|
||||
console.log(JSON.stringify(result, null, 2));
|
||||
process.exit(result.status === "error" ? 1 : 0);
|
||||
}
|
||||
|
||||
main();
|
||||
+74
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: {{FORMAT}}-processor
|
||||
description: Process and analyze {{FORMAT}} files. Use when {{TRIGGER_CONTEXTS}}. Supports {{CAPABILITIES}}.
|
||||
---
|
||||
|
||||
# {{FORMAT}} Processor
|
||||
|
||||
## Operations
|
||||
|
||||
### Read / Extract
|
||||
|
||||
Extract content from {{FORMAT}} files:
|
||||
|
||||
```bash
|
||||
bun run scripts/process.ts extract input.{{ext}}
|
||||
```
|
||||
|
||||
**Output formats:**
|
||||
- `--json` — Structured JSON (default)
|
||||
- `--text` — Plain text
|
||||
- `--markdown` — Markdown formatted
|
||||
|
||||
### Transform
|
||||
|
||||
Transform {{FORMAT}} files:
|
||||
|
||||
```bash
|
||||
bun run scripts/process.ts transform input.{{ext}} --option value
|
||||
```
|
||||
|
||||
### Create
|
||||
|
||||
Create new {{FORMAT}} files:
|
||||
|
||||
```bash
|
||||
bun run scripts/process.ts create output.{{ext}} --from data.json
|
||||
```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Extract and Analyze
|
||||
|
||||
1. Extract content: `bun run scripts/process.ts extract file.{{ext}}`
|
||||
2. Process the JSON output
|
||||
3. Generate insights or summaries
|
||||
|
||||
### Batch Processing
|
||||
|
||||
Process multiple files:
|
||||
|
||||
```bash
|
||||
for f in *.{{ext}}; do
|
||||
bun run scripts/process.ts extract "$f" > "${f%.{{ext}}}.json"
|
||||
done
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- Bun runtime
|
||||
- {{LIBRARY_NAME}}: `bun add {{library-package}}`
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Cause | Solution |
|
||||
|-------|-------|----------|
|
||||
| File not found | Invalid path | Check file exists and path is correct |
|
||||
| Parse error | Corrupted file | Verify file is valid {{FORMAT}} |
|
||||
| Permission denied | Read/write access | Check file permissions |
|
||||
|
||||
## Tips
|
||||
|
||||
- Use `--verbose` for detailed processing info
|
||||
- Large files may take longer; use `--progress` to monitor
|
||||
- Output is JSON by default for easy parsing
|
||||
+174
@@ -0,0 +1,174 @@
|
||||
#!/usr/bin/env bun
|
||||
|
||||
/**
|
||||
* {{FORMAT}} Processor
|
||||
*
|
||||
* Usage: bun run process.ts <command> <file> [options]
|
||||
*/
|
||||
|
||||
import * as fs from "node:fs";
|
||||
|
||||
/**
|
||||
* Extracted content from a document.
|
||||
*/
|
||||
interface DocumentContent {
|
||||
/** Text content extracted from the document */
|
||||
text: string;
|
||||
/** Document metadata (path, size, custom fields) */
|
||||
metadata: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Result of a document processing operation.
|
||||
*/
|
||||
interface ProcessResult {
|
||||
/** Processing status */
|
||||
status: "success" | "error";
|
||||
/** Processed document content if successful */
|
||||
data?: DocumentContent;
|
||||
/** Error message if failed */
|
||||
error?: string;
|
||||
}
|
||||
|
||||
async function extract(filePath: string): Promise<ProcessResult> {
|
||||
if (!fs.existsSync(filePath)) {
|
||||
return { status: "error", error: `File not found: ${filePath}` };
|
||||
}
|
||||
|
||||
try {
|
||||
// TODO: Implement extraction logic for your format
|
||||
// Example: const doc = await SomeLibrary.load(filePath);
|
||||
|
||||
return {
|
||||
status: "success",
|
||||
data: {
|
||||
text: "Extracted content here",
|
||||
metadata: {
|
||||
path: filePath,
|
||||
size: fs.statSync(filePath).size,
|
||||
},
|
||||
},
|
||||
};
|
||||
} catch (e) {
|
||||
return {
|
||||
status: "error",
|
||||
error: e instanceof Error ? e.message : String(e),
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
async function transform(
|
||||
filePath: string,
|
||||
options: Record<string, string>,
|
||||
): Promise<ProcessResult> {
|
||||
if (!fs.existsSync(filePath)) {
|
||||
return { status: "error", error: `File not found: ${filePath}` };
|
||||
}
|
||||
|
||||
try {
|
||||
// TODO: Implement transformation logic
|
||||
console.error(`Transforming ${filePath} with options:`, options);
|
||||
|
||||
return { status: "success", data: { text: "Transformed", metadata: {} } };
|
||||
} catch (e) {
|
||||
return {
|
||||
status: "error",
|
||||
error: e instanceof Error ? e.message : String(e),
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
async function create(
|
||||
outputPath: string,
|
||||
dataPath: string,
|
||||
): Promise<ProcessResult> {
|
||||
if (!fs.existsSync(dataPath)) {
|
||||
return { status: "error", error: `Data file not found: ${dataPath}` };
|
||||
}
|
||||
|
||||
try {
|
||||
const _data = JSON.parse(fs.readFileSync(dataPath, "utf-8"));
|
||||
|
||||
// TODO: Implement creation logic
|
||||
// Example: const doc = SomeLibrary.create(data);
|
||||
// doc.save(outputPath);
|
||||
|
||||
return {
|
||||
status: "success",
|
||||
data: {
|
||||
text: `Created ${outputPath}`,
|
||||
metadata: { outputPath, inputData: dataPath },
|
||||
},
|
||||
};
|
||||
} catch (e) {
|
||||
return {
|
||||
status: "error",
|
||||
error: e instanceof Error ? e.message : String(e),
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// CLI handler
|
||||
async function main() {
|
||||
const [command, file, ...rest] = process.argv.slice(2);
|
||||
|
||||
// Parse --key value pairs
|
||||
const options: Record<string, string> = {};
|
||||
for (let i = 0; i < rest.length; i += 2) {
|
||||
if (rest[i]?.startsWith("--")) {
|
||||
options[rest[i].slice(2)] = rest[i + 1] || "true";
|
||||
}
|
||||
}
|
||||
|
||||
let result: ProcessResult;
|
||||
|
||||
switch (command) {
|
||||
case "extract": {
|
||||
if (!file) {
|
||||
result = { status: "error", error: "Usage: extract <file>" };
|
||||
break;
|
||||
}
|
||||
result = await extract(file);
|
||||
break;
|
||||
}
|
||||
case "transform": {
|
||||
if (!file) {
|
||||
result = {
|
||||
status: "error",
|
||||
error: "Usage: transform <file> [--options]",
|
||||
};
|
||||
break;
|
||||
}
|
||||
result = await transform(file, options);
|
||||
break;
|
||||
}
|
||||
case "create": {
|
||||
if (!file || !options.from) {
|
||||
result = {
|
||||
status: "error",
|
||||
error: "Usage: create <output> --from <data.json>",
|
||||
};
|
||||
break;
|
||||
}
|
||||
result = await create(file, options.from);
|
||||
break;
|
||||
}
|
||||
default:
|
||||
result = {
|
||||
status: "error",
|
||||
error: JSON.stringify({
|
||||
usage: "process.ts <extract|transform|create> <file> [options]",
|
||||
commands: {
|
||||
extract: "Extract content from file",
|
||||
transform: "Transform file with options",
|
||||
create: "Create new file from data",
|
||||
},
|
||||
}),
|
||||
};
|
||||
}
|
||||
|
||||
console.log(JSON.stringify(result, null, 2));
|
||||
process.exit(result.status === "success" ? 0 : 1);
|
||||
}
|
||||
|
||||
main();
|
||||
+88
@@ -0,0 +1,88 @@
|
||||
---
|
||||
name: {{TOPIC}}-research
|
||||
description: Research and synthesize information about {{TOPIC}}. Use when {{TRIGGER_CONTEXTS}}. Produces {{OUTPUT_FORMAT}} with citations.
|
||||
---
|
||||
|
||||
# {{TOPIC}} Research
|
||||
|
||||
## Source Priority
|
||||
|
||||
Check sources in this order:
|
||||
|
||||
1. **{{PRIMARY_SOURCE}}** — Authoritative for {{reason}}
|
||||
2. **{{SECONDARY_SOURCE}}** — Good for {{reason}}
|
||||
3. **General web search** — For background and recent developments
|
||||
|
||||
## Research Workflow
|
||||
|
||||
### Step 1: Scope Definition
|
||||
|
||||
Before searching, clarify:
|
||||
- What specific questions need answers?
|
||||
- What time range is relevant?
|
||||
- What level of detail is needed?
|
||||
|
||||
### Step 2: Gather Information
|
||||
|
||||
For each source:
|
||||
1. Search with specific queries
|
||||
2. Extract relevant facts
|
||||
3. Note the source URL and date
|
||||
|
||||
### Step 3: Synthesize
|
||||
|
||||
Combine findings into {{OUTPUT_FORMAT}}:
|
||||
- Lead with key findings
|
||||
- Support claims with citations
|
||||
- Note conflicting information
|
||||
- Highlight gaps
|
||||
|
||||
## Output Format
|
||||
|
||||
{{DESCRIBE_FORMAT}}
|
||||
|
||||
### Summary Structure
|
||||
|
||||
```markdown
|
||||
## Key Findings
|
||||
- [Finding 1](source_url)
|
||||
- [Finding 2](source_url)
|
||||
|
||||
## Details
|
||||
|
||||
### Topic Area 1
|
||||
[Detailed findings with inline citations]
|
||||
|
||||
### Topic Area 2
|
||||
[Detailed findings with inline citations]
|
||||
|
||||
## Gaps & Limitations
|
||||
- [What couldn't be determined]
|
||||
- [Areas needing more research]
|
||||
|
||||
## Sources
|
||||
- [Source 1 Title](url) — accessed YYYY-MM-DD
|
||||
- [Source 2 Title](url) — accessed YYYY-MM-DD
|
||||
```
|
||||
|
||||
## Citation Style
|
||||
|
||||
Use inline citations: `[claim](source_url)`
|
||||
|
||||
For multiple sources supporting one claim: `[claim](source1)` `[2](source2)`
|
||||
|
||||
## Quality Checks
|
||||
|
||||
Before delivering:
|
||||
- [ ] All claims have citations
|
||||
- [ ] Sources are authoritative and recent
|
||||
- [ ] Conflicting information is noted
|
||||
- [ ] Gaps are acknowledged
|
||||
- [ ] Format matches requested output
|
||||
|
||||
## Tips
|
||||
|
||||
- Prefer primary sources over summaries
|
||||
- Note publication dates for time-sensitive info
|
||||
- Cross-reference claims across multiple sources
|
||||
- Be explicit about uncertainty
|
||||
+52
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: {{SKILL_NAME}}
|
||||
description: {{WHAT_IT_DOES}}. Use when {{WHEN_TO_USE}}. Triggers: {{KEYWORDS}}.
|
||||
---
|
||||
|
||||
# {{SKILL_NAME}}
|
||||
|
||||
{{Brief overview of what this skill does}}
|
||||
|
||||
## Quick Start
|
||||
|
||||
{{Fastest path to value - 3-5 lines max}}
|
||||
|
||||
## Instructions
|
||||
|
||||
When this skill is activated:
|
||||
|
||||
1. **{{Step 1}}**
|
||||
- {{Detail}}
|
||||
- {{Detail}}
|
||||
|
||||
2. **{{Step 2}}**
|
||||
- {{Detail}}
|
||||
- {{Detail}}
|
||||
|
||||
3. **{{Step 3}}**
|
||||
- {{Detail}}
|
||||
- {{Detail}}
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: {{Use Case}}
|
||||
|
||||
```
|
||||
{{Example input/output}}
|
||||
```
|
||||
|
||||
### Example 2: {{Use Case}}
|
||||
|
||||
```
|
||||
{{Example input/output}}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- {{Practice 1}}
|
||||
- {{Practice 2}}
|
||||
- {{Practice 3}}
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **{{skill-name}}**: {{Brief relationship}}
|
||||
Reference in New Issue
Block a user