Initial commit
This commit is contained in:
Zhongwei Li
11
.claude-plugin/plugin.json
Normal file
11
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"name": "skill-creator",
|
||||
"description": "Create and edit Claude Code skills using Test-Driven Development. Runs baseline tests first, then writes minimal skills addressing observed failures. Includes validation, formatting guidance, and best practices for both new and existing skills.",
|
||||
"version": "2.0.0",
|
||||
"author": {
|
||||
"name": "Claude Code Community"
|
||||
},
|
||||
"skills": [
|
||||
"./skills"
|
||||
]
|
||||
}
|
||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# skill-creator
|
||||
|
||||
Create and edit Claude Code skills using Test-Driven Development. Runs baseline tests first, then writes minimal skills addressing observed failures. Includes validation, formatting guidance, and best practices for both new and existing skills.
|
||||
61
plugin.lock.json
Normal file
61
plugin.lock.json
Normal file
@@ -0,0 +1,61 @@
|
||||
{
|
||||
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||
"pluginId": "gh:m-brady/claude-plugins:plugins/skill-creator-plugin",
|
||||
"normalized": {
|
||||
"repo": null,
|
||||
"ref": "refs/tags/v20251128.0",
|
||||
"commit": "fe3dabd873939ec7523b0a7ef03ea69a5d3b5713",
|
||||
"treeHash": "3111b0e0dbc844951f3f55541c77f0f808289540705d317e98510835b893dec9",
|
||||
"generatedAt": "2025-11-28T10:26:59.837276Z",
|
||||
"toolVersion": "publish_plugins.py@0.2.0"
|
||||
},
|
||||
"origin": {
|
||||
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||
"branch": "master",
|
||||
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||
},
|
||||
"manifest": {
|
||||
"name": "skill-creator",
|
||||
"description": "Create and edit Claude Code skills using Test-Driven Development. Runs baseline tests first, then writes minimal skills addressing observed failures. Includes validation, formatting guidance, and best practices for both new and existing skills.",
|
||||
"version": "2.0.0"
|
||||
},
|
||||
"content": {
|
||||
"files": [
|
||||
{
|
||||
"path": "README.md",
|
||||
"sha256": "c5afb630b46e8b80050230ce6bb16783468d32cb8cb4c8acdee03cdf28e68650"
|
||||
},
|
||||
{
|
||||
"path": ".claude-plugin/plugin.json",
|
||||
"sha256": "8340463fabc3a25e366c6eedeaf147eb95d9d73f6fe6fa3638d0af3ff0fb402b"
|
||||
},
|
||||
{
|
||||
"path": "skills/skill-creator/REFERENCE.md",
|
||||
"sha256": "2d5749e8b975547d8bdd07f9ad9580be3cbebb78e2249ec453fb027e50f7db02"
|
||||
},
|
||||
{
|
||||
"path": "skills/skill-creator/SKILL.md",
|
||||
"sha256": "ea26355503bb8fe469dd17755002320ccc27617c439e89a3ca18025ba9960919"
|
||||
},
|
||||
{
|
||||
"path": "skills/skill-creator/scripts/validate-skill.py",
|
||||
"sha256": "217f1b48cc5ffe6fdf462b3f91264bfdcb003a64aebe8f917b6793a680a7d80b"
|
||||
},
|
||||
{
|
||||
"path": "skills/skill-creator/templates/readonly-skill-template.md",
|
||||
"sha256": "7d1eea469b2d8182e8163b188811f94ce5fde553e83a17b0b9ed17c4418917fe"
|
||||
},
|
||||
{
|
||||
"path": "skills/skill-creator/templates/basic-skill-template.md",
|
||||
"sha256": "85a56d34ed1c88e8153061c55f2e21e426b1a64a0207f36d5c50500e4e919e5c"
|
||||
}
|
||||
],
|
||||
"dirSha256": "3111b0e0dbc844951f3f55541c77f0f808289540705d317e98510835b893dec9"
|
||||
},
|
||||
"security": {
|
||||
"scannedAt": null,
|
||||
"scannerVersion": null,
|
||||
"flags": []
|
||||
}
|
||||
}
|
||||
498
skills/skill-creator/REFERENCE.md
Normal file
498
skills/skill-creator/REFERENCE.md
Normal file
@@ -0,0 +1,498 @@
|
||||
# Skill Creator Reference
|
||||
|
||||
Comprehensive reference for creating Claude Code skills.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Validation Rules](#validation-rules)
|
||||
- [YAML Frontmatter Specification](#yaml-frontmatter-specification)
|
||||
- [Description Best Practices](#description-best-practices)
|
||||
- [File Organization](#file-organization)
|
||||
- [Tool Restrictions](#tool-restrictions)
|
||||
- [Testing Skills](#testing-skills)
|
||||
|
||||
## Validation Rules
|
||||
|
||||
### Name Requirements
|
||||
|
||||
**Format**: `^[a-z0-9-]+$`
|
||||
|
||||
- Only lowercase letters (a-z)
|
||||
- Numbers (0-9)
|
||||
- Hyphens (-)
|
||||
- No spaces, underscores, or special characters
|
||||
- Maximum length: 64 characters
|
||||
|
||||
**Valid examples**:
|
||||
- `pdf-processor`
|
||||
- `commit-helper`
|
||||
- `log-analyzer-2`
|
||||
- `api-client-gen`
|
||||
|
||||
**Invalid examples**:
|
||||
- `PDF_Processor` (uppercase and underscore)
|
||||
- `commit helper` (space)
|
||||
- `log.analyzer` (period)
|
||||
- `api-client!` (special character)
|
||||
|
||||
### Description Requirements
|
||||
|
||||
**Length**: Maximum 1024 characters
|
||||
|
||||
**Must include**:
|
||||
1. What the skill does (capabilities)
|
||||
2. When to use it (triggers)
|
||||
3. Key terms for discovery
|
||||
|
||||
**Structure**:
|
||||
```
|
||||
[What it does]. [When to use it]. [Optional: Requirements].
|
||||
```
|
||||
|
||||
**Good example**:
|
||||
```
|
||||
Extract text and tables from PDF files, fill forms, merge documents.
|
||||
Use when working with PDF files, forms, or document extraction.
|
||||
Requires pypdf and pdfplumber packages.
|
||||
```
|
||||
|
||||
**Poor example**:
|
||||
```
|
||||
Helps with documents.
|
||||
```
|
||||
|
||||
### YAML Frontmatter Rules
|
||||
|
||||
**Structure**:
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: Skill description
|
||||
allowed-tools: Tool1, Tool2, Tool3 # Optional
|
||||
---
|
||||
```
|
||||
|
||||
**Rules**:
|
||||
- Must start with `---` on line 1
|
||||
- Must end with `---` before content starts
|
||||
- Use spaces, not tabs
|
||||
- Required fields: `name`, `description`
|
||||
- Optional fields: `allowed-tools`
|
||||
- Follow YAML syntax strictly
|
||||
|
||||
**Common errors**:
|
||||
```yaml
|
||||
# Error: Missing opening ---
|
||||
name: skill-name
|
||||
---
|
||||
|
||||
# Error: Tab character instead of spaces
|
||||
---
|
||||
name: skill-name # <- Tab here
|
||||
---
|
||||
|
||||
# Error: Unquoted string with special chars
|
||||
---
|
||||
description: It's a skill # <- Apostrophe breaks YAML
|
||||
---
|
||||
|
||||
# Fix: Quote strings with special chars
|
||||
---
|
||||
description: "It's a skill"
|
||||
---
|
||||
```
|
||||
|
||||
## YAML Frontmatter Specification
|
||||
|
||||
### Required Fields
|
||||
|
||||
#### name
|
||||
- Type: String
|
||||
- Format: `^[a-z0-9-]+$`
|
||||
- Max length: 64 characters
|
||||
- Must be unique within the skill directory
|
||||
|
||||
#### description
|
||||
- Type: String
|
||||
- Max length: 1024 characters
|
||||
- Should be descriptive and include triggers
|
||||
|
||||
### Optional Fields
|
||||
|
||||
#### allowed-tools
|
||||
- Type: String (comma-separated) or Array
|
||||
- Valid tools: Read, Write, Edit, Glob, Grep, Bash, etc.
|
||||
- Restricts which tools Claude can use with this skill
|
||||
|
||||
**String format**:
|
||||
```yaml
|
||||
allowed-tools: Read, Grep, Glob
|
||||
```
|
||||
|
||||
**Array format**:
|
||||
```yaml
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Grep
|
||||
- Glob
|
||||
```
|
||||
|
||||
## Description Best Practices
|
||||
|
||||
### Include What and When
|
||||
|
||||
**Structure**: `[Capabilities]. [When to use]. [Requirements].`
|
||||
|
||||
### Use Specific Triggers
|
||||
|
||||
Include terms users would actually say:
|
||||
|
||||
**Good**:
|
||||
- "working with Excel files"
|
||||
- "analyzing log files"
|
||||
- "creating API clients"
|
||||
- "when the user mentions PDFs"
|
||||
|
||||
**Poor**:
|
||||
- "for data"
|
||||
- "helps with files"
|
||||
- "general purpose"
|
||||
|
||||
### Examples by Domain
|
||||
|
||||
#### File Processing
|
||||
```
|
||||
Process and analyze [file type] files, [specific operations].
|
||||
Use when working with [file extensions], [user terms], or [tasks].
|
||||
```
|
||||
|
||||
#### Development Tools
|
||||
```
|
||||
[Action] for [technology/framework], [specific features].
|
||||
Use when [development task], [user scenario], or [technical context].
|
||||
```
|
||||
|
||||
#### Analysis Skills
|
||||
```
|
||||
Analyze [data type] for [patterns/metrics], [output format].
|
||||
Use when [analysis task], [debugging scenario], or [investigation type].
|
||||
```
|
||||
|
||||
## File Organization
|
||||
|
||||
### Basic Structure
|
||||
|
||||
```
|
||||
skill-name/
|
||||
└── SKILL.md (required)
|
||||
```
|
||||
|
||||
### With Supporting Files
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md (required)
|
||||
├── REFERENCE.md (optional - detailed docs)
|
||||
├── EXAMPLES.md (optional - more examples)
|
||||
├── scripts/
|
||||
│ ├── helper.py
|
||||
│ └── validator.js
|
||||
└── templates/
|
||||
├── template1.txt
|
||||
└── template2.md
|
||||
```
|
||||
|
||||
### File Naming Conventions
|
||||
|
||||
- Use lowercase
|
||||
- Use hyphens for spaces
|
||||
- Use descriptive names
|
||||
- Group by type in subdirectories
|
||||
|
||||
**Good**:
|
||||
- `scripts/validate-input.py`
|
||||
- `templates/api-client-template.ts`
|
||||
- `docs/advanced-usage.md`
|
||||
|
||||
**Poor**:
|
||||
- `Scripts/ValidateInput.py`
|
||||
- `template.txt`
|
||||
- `file1.md`
|
||||
|
||||
### Referencing Files
|
||||
|
||||
Use relative paths from SKILL.md:
|
||||
|
||||
```markdown
|
||||
See [detailed documentation](REFERENCE.md).
|
||||
For examples, check [EXAMPLES.md](EXAMPLES.md).
|
||||
|
||||
Run the helper:
|
||||
```bash
|
||||
python scripts/helper.py
|
||||
```
|
||||
```
|
||||
|
||||
## Tool Restrictions
|
||||
|
||||
Use `allowed-tools` to limit tool access for safety and focus.
|
||||
|
||||
### Common Patterns
|
||||
|
||||
#### Read-Only Skills
|
||||
```yaml
|
||||
allowed-tools: Read, Grep, Glob
|
||||
```
|
||||
|
||||
Use for:
|
||||
- Analysis tasks
|
||||
- Log investigation
|
||||
- Code review
|
||||
- Documentation reading
|
||||
|
||||
#### Analysis with Execution
|
||||
```yaml
|
||||
allowed-tools: Read, Grep, Glob, Bash
|
||||
```
|
||||
|
||||
Use for:
|
||||
- Data analysis that needs computation
|
||||
- Test execution
|
||||
- Build analysis
|
||||
|
||||
#### Limited Write Access
|
||||
```yaml
|
||||
allowed-tools: Read, Write, Grep, Glob
|
||||
```
|
||||
|
||||
Use for:
|
||||
- Report generation
|
||||
- Template expansion
|
||||
- Safe file creation
|
||||
|
||||
### Available Tools
|
||||
|
||||
Common tools you can restrict to:
|
||||
- **Read**: Read file contents
|
||||
- **Write**: Create new files
|
||||
- **Edit**: Modify existing files
|
||||
- **Glob**: Find files by pattern
|
||||
- **Grep**: Search file contents
|
||||
- **Bash**: Execute shell commands
|
||||
- **WebFetch**: Fetch web content
|
||||
- **WebSearch**: Search the web
|
||||
|
||||
### When to Use Tool Restrictions
|
||||
|
||||
**Use restrictions when**:
|
||||
- Skill should be read-only
|
||||
- Skill has limited scope
|
||||
- Security is important
|
||||
- You want to prevent accidental modifications
|
||||
|
||||
**Don't restrict when**:
|
||||
- Skill needs full flexibility
|
||||
- Multiple operations required
|
||||
- User might need varied access
|
||||
|
||||
## Testing Skills
|
||||
|
||||
### Pre-Testing Checklist
|
||||
|
||||
Before testing a new skill:
|
||||
|
||||
1. **Validate YAML**:
|
||||
```bash
|
||||
head -n 20 SKILL.md
|
||||
# Check frontmatter format
|
||||
```
|
||||
|
||||
2. **Check file location**:
|
||||
```bash
|
||||
# Personal
|
||||
ls ~/.claude/skills/skill-name/SKILL.md
|
||||
|
||||
# Project
|
||||
ls .claude/skills/skill-name/SKILL.md
|
||||
|
||||
# Plugin
|
||||
ls plugin-name/skills/skill-name/SKILL.md
|
||||
```
|
||||
|
||||
3. **Verify name format**:
|
||||
- Lowercase, numbers, hyphens only
|
||||
- No spaces or special characters
|
||||
|
||||
4. **Check description**:
|
||||
- Includes what and when
|
||||
- Contains trigger terms
|
||||
- Under 1024 characters
|
||||
|
||||
### Testing Process
|
||||
|
||||
1. **Restart Claude Code**:
|
||||
```bash
|
||||
# Skills load at startup
|
||||
claude
|
||||
```
|
||||
|
||||
2. **Test with trigger phrases**:
|
||||
- Use terms from your description
|
||||
- Ask questions that match "when to use"
|
||||
- Vary phrasing to test discovery
|
||||
|
||||
3. **Verify activation**:
|
||||
- Skill should activate automatically
|
||||
- Claude should follow instructions
|
||||
- Supporting files should load when referenced
|
||||
|
||||
4. **Test edge cases**:
|
||||
- Invalid inputs
|
||||
- Missing dependencies
|
||||
- Error conditions
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Run with debug flag to see skill loading:
|
||||
|
||||
```bash
|
||||
claude --debug
|
||||
```
|
||||
|
||||
Look for:
|
||||
- Skill discovery messages
|
||||
- Loading errors
|
||||
- YAML parse errors
|
||||
- File not found errors
|
||||
|
||||
### Common Test Scenarios
|
||||
|
||||
#### Scenario 1: Does it activate?
|
||||
```
|
||||
User: [Use trigger phrase from description]
|
||||
Expected: Skill activates and provides help
|
||||
```
|
||||
|
||||
#### Scenario 2: Are restrictions working?
|
||||
```
|
||||
User: [Request that needs restricted tool]
|
||||
Expected: Permission denied or alternative approach
|
||||
```
|
||||
|
||||
#### Scenario 3: Do supporting files load?
|
||||
```
|
||||
User: [Ask question requiring reference docs]
|
||||
Expected: Claude references the supporting file
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Skill Doesn't Activate
|
||||
|
||||
**Check**: Description specificity
|
||||
- Add more trigger terms
|
||||
- Be more explicit about when to use
|
||||
- Include user vocabulary
|
||||
|
||||
**Check**: YAML validity
|
||||
```bash
|
||||
# View frontmatter
|
||||
cat SKILL.md | head -n 10
|
||||
```
|
||||
|
||||
**Check**: File location
|
||||
```bash
|
||||
# Verify SKILL.md exists in correct location
|
||||
ls [path]/SKILL.md
|
||||
```
|
||||
|
||||
### YAML Parse Errors
|
||||
|
||||
**Common causes**:
|
||||
- Tabs instead of spaces
|
||||
- Missing quotes around special characters
|
||||
- Invalid structure
|
||||
- Missing opening/closing `---`
|
||||
|
||||
**Fix**:
|
||||
```yaml
|
||||
# Before (broken)
|
||||
---
|
||||
description: It's broken
|
||||
---
|
||||
|
||||
# After (fixed)
|
||||
---
|
||||
description: "It's fixed"
|
||||
---
|
||||
```
|
||||
|
||||
### Tool Restrictions Not Working
|
||||
|
||||
**Verify syntax**:
|
||||
```yaml
|
||||
# Correct
|
||||
allowed-tools: Read, Grep, Glob
|
||||
|
||||
# Also correct
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Grep
|
||||
- Glob
|
||||
```
|
||||
|
||||
**Check tool names**:
|
||||
- Use exact tool names (case-sensitive)
|
||||
- Common names: Read, Write, Edit, Bash, Grep, Glob
|
||||
- Separate with commas in string format
|
||||
|
||||
### Supporting Files Not Loading
|
||||
|
||||
**Check paths**:
|
||||
- Use relative paths from SKILL.md
|
||||
- Use forward slashes (/)
|
||||
- Don't use absolute paths
|
||||
|
||||
**Check file exists**:
|
||||
```bash
|
||||
cd skill-directory
|
||||
ls -la
|
||||
# Verify all referenced files exist
|
||||
```
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
### DO
|
||||
|
||||
- Keep skills focused on one capability
|
||||
- Write specific, detailed descriptions
|
||||
- Include trigger terms users would say
|
||||
- Use tool restrictions for safety
|
||||
- Provide concrete examples
|
||||
- Test thoroughly before sharing
|
||||
- Document requirements clearly
|
||||
- Use progressive disclosure (supporting files)
|
||||
|
||||
### DON'T
|
||||
|
||||
- Create vague, generic descriptions
|
||||
- Use invalid characters in names
|
||||
- Make skills too broad
|
||||
- Forget to include "when to use"
|
||||
- Skip validation before testing
|
||||
- Use absolute paths for supporting files
|
||||
- Mix tabs and spaces in YAML
|
||||
- Omit error handling guidance
|
||||
|
||||
## Version History
|
||||
|
||||
When documenting skill changes, use semantic versioning:
|
||||
|
||||
```markdown
|
||||
## Version History
|
||||
- v2.0.0 (2025-11-07): Breaking changes to API
|
||||
- v1.1.0 (2025-10-15): Added new features
|
||||
- v1.0.0 (2025-10-01): Initial release
|
||||
```
|
||||
|
||||
This helps team members understand what changed between versions.
|
||||
435
skills/skill-creator/SKILL.md
Normal file
435
skills/skill-creator/SKILL.md
Normal file
@@ -0,0 +1,435 @@
|
||||
---
|
||||
name: skill-creator
|
||||
description: Use when creating new skills, editing existing skills, or improving skill documentation. Applies Test-Driven Development to process documentation - run baseline tests without the skill first, then write minimal skill addressing failures. Mentions of skill files, SKILL.md, skill testing, or skill improvement trigger this.
|
||||
---
|
||||
|
||||
# Skill Creator
|
||||
|
||||
Writing skills IS Test-Driven Development applied to process documentation.
|
||||
|
||||
Skills are reusable reference guides that teach Claude how to perform specific tasks. This skill helps you create or edit skills using a test-driven approach.
|
||||
|
||||
## The Iron Law
|
||||
|
||||
**No skill deploys without a failing test first.** This applies to both new skills and edits to existing skills.
|
||||
|
||||
If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
|
||||
|
||||
## Instructions
|
||||
|
||||
Follow the RED-GREEN-REFACTOR cycle when creating or editing skills:
|
||||
|
||||
### RED: Run Baseline Tests Without the Skill
|
||||
|
||||
Before writing or editing ANY skill:
|
||||
|
||||
1. **Identify test scenarios**: What specific tasks should this skill help with?
|
||||
2. **Run baseline tests**: Test Claude WITHOUT the skill (or with the old version)
|
||||
3. **Document failures**: Record exactly how Claude fails, what it misses, or what it does wrong
|
||||
4. **Capture natural behavior**: Note rationalizations, workarounds, or shortcuts Claude attempts
|
||||
|
||||
Ask yourself:
|
||||
- What specific errors or mistakes happen without this skill?
|
||||
- What does Claude try to do instead?
|
||||
- What shortcuts does Claude rationalize?
|
||||
- What edge cases does Claude miss?
|
||||
|
||||
**This is not optional.** If you skip baseline testing, you're guessing what to teach.
|
||||
|
||||
### GREEN: Write Minimal Skill Addressing Failures
|
||||
|
||||
Now write (or edit) the skill to address the specific failures you observed:
|
||||
|
||||
#### 1. Gather Requirements
|
||||
|
||||
For NEW skills, ask about:
|
||||
- **Skill name**: What should the skill be called?
|
||||
- Must use lowercase letters, numbers, and hyphens only
|
||||
- Maximum 64 characters
|
||||
- Example: `pdf-processor`, `commit-helper`, `code-reviewer`
|
||||
|
||||
- **Location**: Where should the skill be created?
|
||||
- Personal skill: `~/.claude/skills/skill-name/`
|
||||
- Project skill: `.claude/skills/skill-name/`
|
||||
- Plugin skill: `plugin-name/skills/skill-name/`
|
||||
|
||||
For EDITING existing skills:
|
||||
- What specific failures did baseline testing reveal?
|
||||
- What new scenarios need coverage?
|
||||
- What loopholes appeared during testing?
|
||||
|
||||
#### 2. Write the Description
|
||||
|
||||
The description is critical for discovery. Write it to match how Claude would search:
|
||||
|
||||
**Format**: Start with "Use when..." and include specific triggers
|
||||
|
||||
**Optimize for search**:
|
||||
- Include concrete symptoms and error messages
|
||||
- Mention specific tools or commands
|
||||
- Use problem-focused language, not technology names
|
||||
- Include keywords users would actually say
|
||||
|
||||
**Good example**:
|
||||
```
|
||||
Use when creating skills, editing SKILL.md files, or improving skill documentation.
|
||||
Applies Test-Driven Development to process documentation. Mentions of failing tests,
|
||||
baseline scenarios, skill validation, or skill improvement trigger this.
|
||||
```
|
||||
|
||||
**Poor example**:
|
||||
```
|
||||
Helps with skill development and documentation.
|
||||
```
|
||||
|
||||
#### 3. Validate Inputs
|
||||
|
||||
Before creating the skill, validate:
|
||||
- Name uses only lowercase letters, numbers, and hyphens
|
||||
- Name is under 64 characters
|
||||
- Description is under 1024 characters
|
||||
- Description includes both what the skill does AND when to use it
|
||||
- Location path is valid and accessible
|
||||
|
||||
#### 4. Create Directory Structure
|
||||
|
||||
```bash
|
||||
# For personal skills
|
||||
mkdir -p ~/.claude/skills/skill-name
|
||||
|
||||
# For project skills
|
||||
mkdir -p .claude/skills/skill-name
|
||||
|
||||
# For plugin skills
|
||||
mkdir -p plugin-name/skills/skill-name
|
||||
```
|
||||
|
||||
#### 5. Write the SKILL.md Content
|
||||
|
||||
**YAML Frontmatter** (required):
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: Use when [trigger]. [What it does]. [When to use specifics].
|
||||
# Optional: restrict tool access
|
||||
# allowed-tools: Read, Grep, Glob
|
||||
---
|
||||
```
|
||||
|
||||
**Content Structure** - Address the failures you observed:
|
||||
|
||||
```markdown
|
||||
# Skill Name
|
||||
|
||||
Brief statement of purpose.
|
||||
|
||||
## Instructions
|
||||
|
||||
Write instructions that directly counter the failures from your baseline tests:
|
||||
|
||||
1. If Claude skipped validation → Add explicit validation step
|
||||
2. If Claude rationalized shortcuts → List those rationalizations as anti-patterns
|
||||
3. If Claude missed edge cases → Call out those edge cases explicitly
|
||||
4. If Claude used wrong approach → Show the correct approach
|
||||
|
||||
Be specific. Reference the actual failures you saw.
|
||||
|
||||
## Examples
|
||||
|
||||
**One excellent example beats three mediocre ones.**
|
||||
|
||||
Show a concrete example that demonstrates the correct behavior:
|
||||
- Use realistic code/data
|
||||
- Show expected output
|
||||
- Highlight what makes this correct
|
||||
|
||||
## Anti-Patterns (for discipline skills)
|
||||
|
||||
If this skill enforces discipline, explicitly list rationalizations to reject:
|
||||
|
||||
**Red Flags**:
|
||||
- "This is a simple case, so I'll skip..."
|
||||
- "The user didn't explicitly ask for..."
|
||||
- "I can optimize by..."
|
||||
|
||||
**Why these fail**: [Explain the consequences]
|
||||
|
||||
## Requirements
|
||||
|
||||
If external dependencies are needed:
|
||||
- List required packages
|
||||
- Note installation requirements
|
||||
- Specify version constraints if critical
|
||||
```
|
||||
|
||||
**Organization tip**: Keep content inline unless you have 100+ lines of reference material or reusable tools. Progressive disclosure via supporting files is good, but most skills should be self-contained.
|
||||
|
||||
#### 6. Create Supporting Files (if needed)
|
||||
|
||||
Only create supporting files for:
|
||||
- **Heavy reference** (100+ lines): API docs, extensive tables, detailed specs
|
||||
- **Reusable tools**: Scripts that multiple skills could use
|
||||
- **Not needed**: Examples, brief guidance, troubleshooting
|
||||
|
||||
Organize like this:
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md (required, self-contained)
|
||||
├── reference.md (only if 100+ lines)
|
||||
└── scripts/
|
||||
└── helper.py (only if reusable)
|
||||
```
|
||||
|
||||
### REFACTOR: Close Loopholes Through Testing
|
||||
|
||||
After writing/editing the skill, test it to find loopholes:
|
||||
|
||||
#### 1. Test with the Skill Active
|
||||
|
||||
Run the same scenarios from your baseline tests, but now WITH the skill:
|
||||
- Does Claude follow the instructions?
|
||||
- Does Claude still find rationalizations?
|
||||
- Are there new ways to skip steps?
|
||||
|
||||
#### 2. Identify New Rationalizations
|
||||
|
||||
Watch for:
|
||||
- "I can skip X because..."
|
||||
- "This scenario is different because..."
|
||||
- "The user probably meant..."
|
||||
|
||||
These are loopholes. Add them to your Anti-Patterns section.
|
||||
|
||||
#### 3. Test Variations
|
||||
|
||||
Try different phrasings, contexts, and edge cases:
|
||||
- Does it work under pressure (multiple competing priorities)?
|
||||
- Does it work with ambiguous requirements?
|
||||
- Does it work when the easy path is tempting?
|
||||
|
||||
#### 4. Iterate
|
||||
|
||||
Update the skill to close loopholes:
|
||||
- Add explicit counters to new rationalizations
|
||||
- Strengthen language around discipline requirements
|
||||
- Add examples showing the loophole scenarios
|
||||
|
||||
**Repeat RED-GREEN-REFACTOR until the skill reliably prevents failures.**
|
||||
|
||||
### Skill Testing Checklist
|
||||
|
||||
Before deploying a new or edited skill:
|
||||
|
||||
**RED Phase**:
|
||||
- [ ] Identified 3+ realistic test scenarios
|
||||
- [ ] Ran baseline tests WITHOUT the skill
|
||||
- [ ] Documented specific failures and rationalizations
|
||||
- [ ] Captured what Claude tried to do instead
|
||||
|
||||
**GREEN Phase**:
|
||||
- [ ] YAML frontmatter is valid (name, description)
|
||||
- [ ] Description starts with "Use when..."
|
||||
- [ ] Description includes search-optimized triggers
|
||||
- [ ] Instructions directly address observed failures
|
||||
- [ ] Included one excellent example (not multiple mediocre ones)
|
||||
- [ ] Added Anti-Patterns section (for discipline skills)
|
||||
- [ ] Content is self-contained (minimal supporting files)
|
||||
|
||||
**REFACTOR Phase**:
|
||||
- [ ] Tested WITH the skill active
|
||||
- [ ] Identified new rationalizations or loopholes
|
||||
- [ ] Updated skill to close loopholes
|
||||
- [ ] Tested variations and edge cases
|
||||
- [ ] Skill reliably prevents the original failures
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Discipline Skill with TDD
|
||||
|
||||
**RED Phase** - Baseline failures observed:
|
||||
- Claude analyzed logs but missed correlating errors across files
|
||||
- Claude skipped checking timestamps for patterns
|
||||
- Claude gave surface-level analysis without root cause investigation
|
||||
|
||||
**GREEN Phase** - Skill addressing failures:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: log-analyzer
|
||||
description: Use when debugging application errors, investigating log files, or analyzing system failures. Correlates errors across multiple files, identifies patterns over time, and suggests root causes. Mentions of logs, errors, stack traces, or debugging trigger this.
|
||||
allowed-tools: Read, Grep, Glob
|
||||
---
|
||||
|
||||
# Log Analyzer
|
||||
|
||||
Analyze application logs systematically to identify root causes, not just symptoms.
|
||||
|
||||
## Instructions
|
||||
|
||||
1. **Find all relevant logs**: Use Glob to find log files matching the timeframe
|
||||
2. **Extract error context**: Use Grep with -C 5 to get surrounding context
|
||||
3. **Build timeline**: Sort errors chronologically across ALL files
|
||||
4. **Correlate patterns**: Look for errors that occur together
|
||||
5. **Identify root cause**: Trace back to the first error in the sequence
|
||||
6. **Summarize findings**: Include timestamps, affected components, and likely cause
|
||||
|
||||
## Example
|
||||
|
||||
```bash
|
||||
# Find all logs from the last hour
|
||||
glob "**/*.log"
|
||||
|
||||
# Search for errors with context
|
||||
grep -C 5 "ERROR|FATAL|Exception" app.log
|
||||
|
||||
# Check timestamps across files
|
||||
grep "2025-11-07 14:" *.log | sort
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
14:23:45 database.log: Connection timeout
|
||||
14:23:47 app.log: ERROR: Failed to fetch user data
|
||||
14:23:48 api.log: Exception: Database unavailable
|
||||
```
|
||||
|
||||
Root cause: Database connection timeout cascaded to application and API errors.
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
**Red Flags**:
|
||||
- "I found an error in app.log" ← Did you check other logs?
|
||||
- "There are multiple ERROR entries" ← What's the root cause?
|
||||
- "The logs show issues" ← What's the timeline and correlation?
|
||||
|
||||
**Why these fail**: Surface-level analysis misses the actual problem and wastes debugging time.
|
||||
```
|
||||
|
||||
**REFACTOR Phase** - Loopholes closed:
|
||||
- Added explicit correlation requirement
|
||||
- Added timeline sorting step
|
||||
- Added Anti-Patterns section to prevent shallow analysis
|
||||
|
||||
### Example 2: Editing an Existing Skill
|
||||
|
||||
**Scenario**: The `database-migration` skill exists but users reported it doesn't enforce testing rollbacks.
|
||||
|
||||
**RED Phase** - Test WITHOUT the rollback requirement:
|
||||
- Claude created migrations with up/down scripts
|
||||
- Claude skipped actually testing the rollback
|
||||
- Claude rationalized: "The down migration looks correct"
|
||||
|
||||
**GREEN Phase** - Edit the skill to address failures:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: database-migration
|
||||
description: Use when creating database migrations, schema changes, or rollback scripts. Enforces testing both up AND down migrations before deployment. Mentions of migrations, schema changes, or database updates trigger this.
|
||||
---
|
||||
|
||||
# Database Migration Helper
|
||||
|
||||
Create safe, reversible database migrations with tested rollbacks.
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Analyze the schema change needed
|
||||
2. Generate migration file with timestamp
|
||||
3. Write BOTH up and down migrations
|
||||
4. **Test the up migration** on a test database
|
||||
5. **Test the down migration** to verify rollback works
|
||||
6. Document any data transformations or breaking changes
|
||||
|
||||
## Example
|
||||
|
||||
```sql
|
||||
-- Up migration
|
||||
CREATE TABLE users (
|
||||
id SERIAL PRIMARY KEY,
|
||||
email VARCHAR(255) UNIQUE NOT NULL
|
||||
);
|
||||
|
||||
-- Down migration
|
||||
DROP TABLE users;
|
||||
```
|
||||
|
||||
**Testing sequence**:
|
||||
```bash
|
||||
# Test up
|
||||
psql test_db -f migrations/001_up.sql
|
||||
# Verify schema exists
|
||||
|
||||
# Test down
|
||||
psql test_db -f migrations/001_down.sql
|
||||
# Verify schema is gone
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
**Red Flags**:
|
||||
- "The down migration looks correct" ← Did you actually test it?
|
||||
- "I'll skip testing since this is simple" ← Simple migrations can still break
|
||||
- "Testing rollback isn't needed for this change" ← It's always needed
|
||||
|
||||
**Why these fail**: Untested rollbacks fail in production when you need them most.
|
||||
```
|
||||
|
||||
**REFACTOR Phase**:
|
||||
- Added explicit testing steps (not just writing)
|
||||
- Added Anti-Patterns for the rationalization we observed
|
||||
- Changed description to emphasize enforcement of testing
|
||||
|
||||
## Validation Quick Reference
|
||||
|
||||
### Name Format
|
||||
- Lowercase letters, numbers, hyphens only: `^[a-z0-9-]+$`
|
||||
- Maximum 64 characters
|
||||
- Examples: `log-analyzer`, `pdf-processor`, `commit-helper`
|
||||
|
||||
### Description Format
|
||||
- Start with "Use when..."
|
||||
- Include specific triggers (error messages, tool names, symptoms)
|
||||
- Maximum 1024 characters
|
||||
- Optimize for how Claude would search
|
||||
|
||||
### YAML Frontmatter
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: Use when [trigger]. [What it does]. [Specifics].
|
||||
# Optional
|
||||
# allowed-tools: Read, Grep, Glob
|
||||
---
|
||||
```
|
||||
|
||||
### Common Mistakes
|
||||
|
||||
**Skipping baseline tests** → You're guessing what to teach
|
||||
- Fix: Always run RED phase first
|
||||
|
||||
**Vague descriptions** → Skill won't activate when needed
|
||||
- Bad: "Helps with data"
|
||||
- Good: "Use when analyzing CSV files, detecting outliers, or generating statistics from spreadsheet data."
|
||||
|
||||
**Missing Anti-Patterns** → Claude will find rationalizations
|
||||
- Fix: Add Red Flags section listing rationalizations you observed
|
||||
|
||||
**Too many supporting files** → Content should be self-contained
|
||||
- Fix: Keep content in SKILL.md unless you have 100+ lines of reference
|
||||
|
||||
## Tool Restrictions
|
||||
|
||||
Use `allowed-tools` to limit scope and increase safety:
|
||||
|
||||
```yaml
|
||||
# Read-only analysis
|
||||
allowed-tools: Read, Grep, Glob
|
||||
|
||||
# Analysis with execution
|
||||
allowed-tools: Read, Grep, Glob, Bash
|
||||
|
||||
# Minimal write access
|
||||
allowed-tools: Read, Write, Glob
|
||||
```
|
||||
|
||||
For detailed reference on validation rules, file organization, and troubleshooting, see [REFERENCE.md](REFERENCE.md).
|
||||
268
skills/skill-creator/scripts/validate-skill.py
Executable file
268
skills/skill-creator/scripts/validate-skill.py
Executable file
@@ -0,0 +1,268 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Validate a Claude Code SKILL.md file.
|
||||
|
||||
Usage:
|
||||
python validate-skill.py path/to/SKILL.md
|
||||
"""
|
||||
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from typing import Tuple, List
|
||||
|
||||
# Validation rules
|
||||
NAME_PATTERN = re.compile(r'^[a-z0-9-]+$')
|
||||
MAX_NAME_LENGTH = 64
|
||||
MAX_DESCRIPTION_LENGTH = 1024
|
||||
|
||||
def validate_yaml_frontmatter(content: str) -> Tuple[bool, List[str], dict]:
|
||||
"""
|
||||
Validate YAML frontmatter in SKILL.md.
|
||||
|
||||
Returns:
|
||||
Tuple of (is_valid, errors, frontmatter_data)
|
||||
"""
|
||||
errors = []
|
||||
frontmatter_data = {}
|
||||
|
||||
lines = content.split('\n')
|
||||
|
||||
# Check first line is ---
|
||||
if not lines or lines[0].strip() != '---':
|
||||
errors.append("YAML frontmatter must start with '---' on line 1")
|
||||
return False, errors, frontmatter_data
|
||||
|
||||
# Find closing ---
|
||||
closing_idx = None
|
||||
for i, line in enumerate(lines[1:], start=1):
|
||||
if line.strip() == '---':
|
||||
closing_idx = i
|
||||
break
|
||||
|
||||
if closing_idx is None:
|
||||
errors.append("YAML frontmatter must end with '---'")
|
||||
return False, errors, frontmatter_data
|
||||
|
||||
# Extract frontmatter
|
||||
frontmatter_lines = lines[1:closing_idx]
|
||||
|
||||
# Parse YAML (simple parsing for validation)
|
||||
for line in frontmatter_lines:
|
||||
if ':' in line:
|
||||
key, value = line.split(':', 1)
|
||||
key = key.strip()
|
||||
value = value.strip()
|
||||
|
||||
# Remove quotes if present
|
||||
if value.startswith('"') and value.endswith('"'):
|
||||
value = value[1:-1]
|
||||
elif value.startswith("'") and value.endswith("'"):
|
||||
value = value[1:-1]
|
||||
|
||||
frontmatter_data[key] = value
|
||||
|
||||
# Check required fields
|
||||
if 'name' not in frontmatter_data:
|
||||
errors.append("Missing required field: 'name'")
|
||||
|
||||
if 'description' not in frontmatter_data:
|
||||
errors.append("Missing required field: 'description'")
|
||||
|
||||
return len(errors) == 0, errors, frontmatter_data
|
||||
|
||||
|
||||
def validate_name(name: str) -> Tuple[bool, List[str]]:
|
||||
"""Validate skill name."""
|
||||
errors = []
|
||||
|
||||
if not name:
|
||||
errors.append("Name cannot be empty")
|
||||
return False, errors
|
||||
|
||||
if len(name) > MAX_NAME_LENGTH:
|
||||
errors.append(f"Name exceeds maximum length of {MAX_NAME_LENGTH} characters (got {len(name)})")
|
||||
|
||||
if not NAME_PATTERN.match(name):
|
||||
errors.append(f"Name must contain only lowercase letters, numbers, and hyphens (got: '{name}')")
|
||||
|
||||
# Provide specific feedback
|
||||
if any(c.isupper() for c in name):
|
||||
errors.append(" - Contains uppercase letters (use lowercase only)")
|
||||
if '_' in name:
|
||||
errors.append(" - Contains underscores (use hyphens instead)")
|
||||
if ' ' in name:
|
||||
errors.append(" - Contains spaces (use hyphens instead)")
|
||||
if any(c in name for c in '!@#$%^&*()+=[]{}|\\;:\'",.<>?/'):
|
||||
errors.append(" - Contains special characters (only hyphens allowed)")
|
||||
|
||||
return len(errors) == 0, errors
|
||||
|
||||
|
||||
def validate_description(description: str) -> Tuple[bool, List[str]]:
|
||||
"""Validate skill description."""
|
||||
errors = []
|
||||
warnings = []
|
||||
|
||||
if not description:
|
||||
errors.append("Description cannot be empty")
|
||||
return False, errors
|
||||
|
||||
if len(description) > MAX_DESCRIPTION_LENGTH:
|
||||
errors.append(f"Description exceeds maximum length of {MAX_DESCRIPTION_LENGTH} characters (got {len(description)})")
|
||||
|
||||
# Check for best practices (warnings, not errors)
|
||||
description_lower = description.lower()
|
||||
|
||||
if 'use when' not in description_lower:
|
||||
warnings.append("Description should include 'Use when' to indicate when to activate this skill")
|
||||
|
||||
if len(description) < 50:
|
||||
warnings.append("Description is quite short - consider adding more detail about what it does and when to use it")
|
||||
|
||||
# Check for vague terms
|
||||
vague_terms = ['helps', 'assists', 'general', 'various', 'stuff', 'things']
|
||||
found_vague = [term for term in vague_terms if term in description_lower]
|
||||
if found_vague:
|
||||
warnings.append(f"Description contains vague terms: {', '.join(found_vague)}. Be more specific.")
|
||||
|
||||
if warnings:
|
||||
print("\n⚠️ Warnings (not errors, but consider addressing):")
|
||||
for warning in warnings:
|
||||
print(f" - {warning}")
|
||||
|
||||
return len(errors) == 0, errors
|
||||
|
||||
|
||||
def validate_file_structure(skill_path: Path) -> Tuple[bool, List[str]]:
|
||||
"""Validate the skill file structure."""
|
||||
errors = []
|
||||
warnings = []
|
||||
|
||||
skill_md = skill_path
|
||||
skill_dir = skill_path.parent
|
||||
|
||||
if not skill_md.exists():
|
||||
errors.append(f"SKILL.md not found at {skill_md}")
|
||||
return False, errors
|
||||
|
||||
# Check for supporting files referenced in SKILL.md
|
||||
content = skill_md.read_text()
|
||||
|
||||
# Find markdown links and code references
|
||||
link_pattern = re.compile(r'\[([^\]]+)\]\(([^\)]+)\)')
|
||||
matches = link_pattern.findall(content)
|
||||
|
||||
for link_text, link_path in matches:
|
||||
# Skip external links
|
||||
if link_path.startswith('http://') or link_path.startswith('https://'):
|
||||
continue
|
||||
|
||||
# Check if referenced file exists
|
||||
referenced_file = skill_dir / link_path
|
||||
if not referenced_file.exists():
|
||||
warnings.append(f"Referenced file not found: {link_path}")
|
||||
|
||||
if warnings:
|
||||
print("\n⚠️ File Structure Warnings:")
|
||||
for warning in warnings:
|
||||
print(f" - {warning}")
|
||||
|
||||
return len(errors) == 0, errors
|
||||
|
||||
|
||||
def validate_skill_file(skill_path: Path) -> bool:
|
||||
"""
|
||||
Validate a complete SKILL.md file.
|
||||
|
||||
Returns:
|
||||
True if valid, False otherwise
|
||||
"""
|
||||
print(f"Validating: {skill_path}\n")
|
||||
|
||||
if not skill_path.exists():
|
||||
print(f"❌ Error: File not found: {skill_path}")
|
||||
return False
|
||||
|
||||
content = skill_path.read_text()
|
||||
all_valid = True
|
||||
|
||||
# Validate YAML frontmatter
|
||||
print("Checking YAML frontmatter...")
|
||||
valid_yaml, yaml_errors, frontmatter = validate_yaml_frontmatter(content)
|
||||
|
||||
if not valid_yaml:
|
||||
print("❌ YAML frontmatter errors:")
|
||||
for error in yaml_errors:
|
||||
print(f" - {error}")
|
||||
all_valid = False
|
||||
else:
|
||||
print("✅ YAML frontmatter is valid")
|
||||
|
||||
# Validate name
|
||||
if 'name' in frontmatter:
|
||||
print("\nChecking name...")
|
||||
valid_name, name_errors = validate_name(frontmatter['name'])
|
||||
if not valid_name:
|
||||
print("❌ Name validation errors:")
|
||||
for error in name_errors:
|
||||
print(f" - {error}")
|
||||
all_valid = False
|
||||
else:
|
||||
print(f"✅ Name is valid: '{frontmatter['name']}'")
|
||||
|
||||
# Validate description
|
||||
if 'description' in frontmatter:
|
||||
print("\nChecking description...")
|
||||
valid_desc, desc_errors = validate_description(frontmatter['description'])
|
||||
if not valid_desc:
|
||||
print("❌ Description validation errors:")
|
||||
for error in desc_errors:
|
||||
print(f" - {error}")
|
||||
all_valid = False
|
||||
else:
|
||||
print(f"✅ Description is valid ({len(frontmatter['description'])} characters)")
|
||||
|
||||
# Validate allowed-tools if present
|
||||
if 'allowed-tools' in frontmatter:
|
||||
print("\nChecking allowed-tools...")
|
||||
print(f"✅ Tool restrictions found: {frontmatter['allowed-tools']}")
|
||||
|
||||
# Validate file structure
|
||||
print("\nChecking file structure...")
|
||||
valid_structure, structure_errors = validate_file_structure(skill_path)
|
||||
if not valid_structure:
|
||||
print("❌ File structure errors:")
|
||||
for error in structure_errors:
|
||||
print(f" - {error}")
|
||||
all_valid = False
|
||||
else:
|
||||
print("✅ File structure is valid")
|
||||
|
||||
# Summary
|
||||
print("\n" + "="*60)
|
||||
if all_valid:
|
||||
print("✅ Skill validation PASSED")
|
||||
print("\nYour skill is ready to use!")
|
||||
print("Remember to restart Claude Code to load the new skill.")
|
||||
else:
|
||||
print("❌ Skill validation FAILED")
|
||||
print("\nPlease fix the errors above and try again.")
|
||||
print("="*60)
|
||||
|
||||
return all_valid
|
||||
|
||||
|
||||
def main():
|
||||
if len(sys.argv) != 2:
|
||||
print("Usage: python validate-skill.py path/to/SKILL.md")
|
||||
sys.exit(1)
|
||||
|
||||
skill_path = Path(sys.argv[1])
|
||||
valid = validate_skill_file(skill_path)
|
||||
|
||||
sys.exit(0 if valid else 1)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
51
skills/skill-creator/templates/basic-skill-template.md
Normal file
51
skills/skill-creator/templates/basic-skill-template.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
name: skill-name
|
||||
description: Use when [specific trigger]. [What it does]. [When to use specifics]. Mentions of [keywords], [error messages], or [tools] trigger this.
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
Brief statement of purpose - what problem does this solve?
|
||||
|
||||
## Instructions
|
||||
|
||||
Write instructions that address the specific failures you observed in baseline testing:
|
||||
|
||||
1. **First critical step** - Counter the first observed failure
|
||||
2. **Second critical step** - Address the rationalization you saw
|
||||
3. **Third critical step** - Handle the edge case that was missed
|
||||
4. **Final step** - Ensure clear, actionable output
|
||||
|
||||
Be specific. Reference actual behaviors you want to change.
|
||||
|
||||
## Example
|
||||
|
||||
**One excellent example beats three mediocre ones.**
|
||||
|
||||
```bash
|
||||
# Show a realistic, concrete example
|
||||
command --with-real-options actual-file.txt
|
||||
|
||||
# Show what happens
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
Show the exact result with explanation of what makes this correct
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
**Red Flags** (rationalizations to reject):
|
||||
- "This is simple, so I'll skip..." ← Why this fails
|
||||
- "The user didn't explicitly ask for..." ← Why this fails
|
||||
- "I can optimize by skipping..." ← Why this fails
|
||||
|
||||
**Why these fail**: Explain the consequences of taking shortcuts
|
||||
|
||||
## Requirements
|
||||
|
||||
If external dependencies are needed:
|
||||
- Required packages: `pip install package1 package2`
|
||||
- Version constraints (if critical): `package1>=2.0.0`
|
||||
- System requirements: OS, tools, configurations
|
||||
60
skills/skill-creator/templates/readonly-skill-template.md
Normal file
60
skills/skill-creator/templates/readonly-skill-template.md
Normal file
@@ -0,0 +1,60 @@
|
||||
---
|
||||
name: skill-name
|
||||
description: Use when [analyzing/investigating/reviewing] [specific thing]. Read-only analysis that finds [patterns/issues/metrics]. Mentions of [keywords], [error types], or [analysis needs] trigger this.
|
||||
allowed-tools: Read, Grep, Glob
|
||||
---
|
||||
|
||||
# Skill Name (Read-Only Analysis)
|
||||
|
||||
Brief statement of purpose - what does this analyze and why?
|
||||
|
||||
## Instructions
|
||||
|
||||
This is a read-only skill. Follow these steps to provide thorough analysis:
|
||||
|
||||
1. **Find all relevant files**: Use Glob to locate files matching the criteria
|
||||
2. **Search for patterns**: Use Grep with context (-C flag) to find issues
|
||||
3. **Read detailed content**: Use Read on specific files for deeper analysis
|
||||
4. **Correlate findings**: Connect patterns across multiple files
|
||||
5. **Summarize with evidence**: Provide findings with file paths and line numbers
|
||||
|
||||
## Example
|
||||
|
||||
```bash
|
||||
# Find all relevant files
|
||||
glob "**/*.log"
|
||||
|
||||
# Search with context
|
||||
grep -C 5 "ERROR|WARN" application.log
|
||||
|
||||
# Read specific file for details
|
||||
read config/settings.json
|
||||
```
|
||||
|
||||
Expected analysis:
|
||||
```
|
||||
Found 3 ERROR entries in application.log:
|
||||
- Line 42: Database connection timeout
|
||||
- Line 156: Failed authentication attempt
|
||||
- Line 289: Memory allocation error
|
||||
|
||||
Root cause: Database connection timeout at line 42 triggered cascade of errors.
|
||||
Recommendation: Investigate database connection pool settings.
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
**Red Flags**:
|
||||
- "I found some errors" ← Where? Which files? What lines?
|
||||
- "The logs show issues" ← What specific issues? How do they correlate?
|
||||
- "I'll just check one file" ← Did you search all relevant files?
|
||||
|
||||
**Why these fail**: Incomplete analysis misses context and root causes.
|
||||
|
||||
## Tool Restrictions
|
||||
|
||||
This skill is read-only by design:
|
||||
- ✓ Can: Read files, search content, find patterns
|
||||
- ✗ Cannot: Modify files, execute commands, write files
|
||||
|
||||
If modifications are needed, recommend creating a separate skill or getting user permission.
|
||||
Reference in New Issue
Block a user