Initial commit
This commit is contained in:
Zhongwei Li
272
skills/skill-creator/examples/complex-skill/README.md
Normal file
272
skills/skill-creator/examples/complex-skill/README.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# Complex Skill Structure Example
|
||||
|
||||
This example shows the structure for skills with multiple operating modes or data processing capabilities.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
### Mode-Based Complex Skill
|
||||
|
||||
```
|
||||
complex-skill/
|
||||
├── SKILL.md # Agent manifest with mode detection (required)
|
||||
├── README.md # User documentation (required)
|
||||
├── plugin.json # Marketplace metadata (required)
|
||||
├── CHANGELOG.md # Version history (required)
|
||||
├── modes/ # Mode-specific workflows (required for mode-based)
|
||||
│ ├── mode1-name.md
|
||||
│ ├── mode2-name.md
|
||||
│ └── mode3-name.md
|
||||
├── data/ # Reference materials (optional)
|
||||
│ ├── best-practices.md
|
||||
│ └── troubleshooting.md
|
||||
├── examples/ # Sample outputs per mode (optional)
|
||||
│ ├── mode1-example.md
|
||||
│ └── mode2-example.md
|
||||
└── templates/ # Reusable templates (optional)
|
||||
└── output-template.md
|
||||
```
|
||||
|
||||
### Data Processing Complex Skill
|
||||
|
||||
```
|
||||
complex-skill/
|
||||
├── SKILL.md # Agent manifest (required)
|
||||
├── README.md # User documentation (required)
|
||||
├── plugin.json # Marketplace metadata (required)
|
||||
├── CHANGELOG.md # Version history (required)
|
||||
├── scripts/ # Processing scripts (required for data processing)
|
||||
│ ├── processor.py
|
||||
│ ├── indexer.py
|
||||
│ ├── query.py
|
||||
│ └── generator.py
|
||||
├── data/ # Reference materials (optional)
|
||||
│ └── config-defaults.yaml
|
||||
├── examples/ # Sample outputs (optional)
|
||||
│ └── sample-report.md
|
||||
└── templates/ # Report templates (optional)
|
||||
└── report-template.md.j2
|
||||
```
|
||||
|
||||
## When to Use Complex Structure
|
||||
|
||||
Use this structure when:
|
||||
|
||||
### Mode-Based:
|
||||
- Multiple distinct operating modes based on user intent
|
||||
- Each mode has its own workflow
|
||||
- Different outputs per mode
|
||||
- Clear mode detection logic needed
|
||||
- Example: git-worktree-setup (single/batch/cleanup/list modes)
|
||||
|
||||
### Data Processing:
|
||||
- Processes data from files or APIs
|
||||
- Performs analysis or transformation
|
||||
- Generates insights or reports
|
||||
- Needs helper scripts for processing
|
||||
- Example: cc-insights (conversation analysis)
|
||||
|
||||
## Characteristics
|
||||
|
||||
- **Complexity**: High
|
||||
- **Files**: 4 required + 4+ optional directories
|
||||
- **Pattern**: Mode-based or data-processing
|
||||
- **Modes**: Multiple distinct modes OR data pipeline
|
||||
- **Scripts**: Often needed for data processing
|
||||
- **Dependencies**: May have Python/Node dependencies
|
||||
|
||||
## SKILL.md Template (Mode-Based)
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
version: 0.1.0
|
||||
description: Multi-mode skill that handles X, Y, and Z
|
||||
author: Your Name
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
## Overview
|
||||
|
||||
This skill operates in multiple modes based on user intent.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Trigger Phrases:**
|
||||
- "mode 1 trigger"
|
||||
- "mode 2 trigger"
|
||||
- "mode 3 trigger"
|
||||
|
||||
**Use Cases:**
|
||||
- Mode 1: Use case
|
||||
- Mode 2: Use case
|
||||
- Mode 3: Use case
|
||||
|
||||
## Quick Decision Matrix
|
||||
|
||||
\`\`\`
|
||||
User Request → Mode → Action
|
||||
─────────────────────────────────────────────────
|
||||
"trigger 1" → Mode 1 → Action 1
|
||||
"trigger 2" → Mode 2 → Action 2
|
||||
"trigger 3" → Mode 3 → Action 3
|
||||
\`\`\`
|
||||
|
||||
## Mode Detection Logic
|
||||
|
||||
\`\`\`javascript
|
||||
// Mode 1: Description
|
||||
if (userMentions("keyword1")) {
|
||||
return "mode1-name";
|
||||
}
|
||||
|
||||
// Mode 2: Description
|
||||
if (userMentions("keyword2")) {
|
||||
return "mode2-name";
|
||||
}
|
||||
|
||||
// Mode 3: Description
|
||||
if (userMentions("keyword3")) {
|
||||
return "mode3-name";
|
||||
}
|
||||
|
||||
// Ambiguous - ask user
|
||||
return askForClarification();
|
||||
\`\`\`
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
### Shared Prerequisites
|
||||
- ✓ Prerequisite 1 (all modes)
|
||||
- ✓ Prerequisite 2 (all modes)
|
||||
|
||||
### Mode-Specific Workflows
|
||||
See detailed workflows in:
|
||||
- \`modes/mode1-name.md\` - Mode 1 complete workflow
|
||||
- \`modes/mode2-name.md\` - Mode 2 complete workflow
|
||||
- \`modes/mode3-name.md\` - Mode 3 complete workflow
|
||||
|
||||
## Success Criteria
|
||||
|
||||
Varies by mode - see individual mode documentation.
|
||||
```
|
||||
|
||||
## SKILL.md Template (Data Processing)
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
version: 0.1.0
|
||||
description: Processes X data to generate Y insights
|
||||
author: Your Name
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
## Overview
|
||||
|
||||
Automatically processes data from [source] to provide [capabilities].
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Trigger Phrases:**
|
||||
- "search for X"
|
||||
- "generate Y report"
|
||||
- "analyze Z data"
|
||||
|
||||
**Use Cases:**
|
||||
- Search and find
|
||||
- Generate insights
|
||||
- Track patterns
|
||||
|
||||
## Architecture
|
||||
|
||||
\`\`\`
|
||||
Input → Processing → Storage → Query/Analysis → Output
|
||||
\`\`\`
|
||||
|
||||
## Workflow
|
||||
|
||||
### Phase 1: Data Ingestion
|
||||
- Discover data sources
|
||||
- Validate format
|
||||
- Process incrementally
|
||||
|
||||
### Phase 2: Processing
|
||||
- Extract features
|
||||
- Generate embeddings (if semantic)
|
||||
- Store in database
|
||||
|
||||
### Phase 3: Query/Analysis
|
||||
- Search interface
|
||||
- Pattern detection
|
||||
- Generate reports
|
||||
|
||||
## Scripts
|
||||
|
||||
See \`scripts/\` directory:
|
||||
- \`processor.py\` - Main data processing
|
||||
- \`indexer.py\` - Build indexes
|
||||
- \`query.py\` - Query interface
|
||||
- \`generator.py\` - Report generation
|
||||
|
||||
## Performance
|
||||
|
||||
- Initial processing: [time estimate]
|
||||
- Incremental updates: [time estimate]
|
||||
- Search latency: [time estimate]
|
||||
- Memory usage: [estimate]
|
||||
```
|
||||
|
||||
## Directory Purposes
|
||||
|
||||
### modes/
|
||||
For mode-based skills, each file documents one mode:
|
||||
- Complete workflow for that mode
|
||||
- Mode-specific prerequisites
|
||||
- Mode-specific outputs
|
||||
- Mode-specific error handling
|
||||
|
||||
### scripts/
|
||||
For data processing skills:
|
||||
- Python/Node scripts for heavy processing
|
||||
- CLI interfaces for user interaction
|
||||
- Batch processors
|
||||
- Report generators
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Mode-Based Skills:
|
||||
1. **Clear mode boundaries**: Each mode is distinct
|
||||
2. **Explicit detection**: Unambiguous mode selection
|
||||
3. **Shared prerequisites**: Extract common validation
|
||||
4. **Mode independence**: Each mode works standalone
|
||||
5. **Detailed documentation**: Each mode has its own guide
|
||||
|
||||
### Data Processing Skills:
|
||||
1. **Incremental processing**: Don't reprocess everything
|
||||
2. **State tracking**: Know what's been processed
|
||||
3. **Progress indicators**: Show progress for long operations
|
||||
4. **Error recovery**: Handle failures gracefully
|
||||
5. **Performance docs**: Document expected performance
|
||||
6. **Script documentation**: Each script has clear --help
|
||||
|
||||
## Examples of Complex Skills
|
||||
|
||||
### Mode-Based:
|
||||
- **git-worktree-setup**: Single/Batch/Cleanup/List modes
|
||||
- **Multi-format converter**: Different output formats
|
||||
- **Environment manager**: Create/Update/Delete/List
|
||||
|
||||
### Data Processing:
|
||||
- **cc-insights**: Conversation analysis with RAG search
|
||||
- **Log analyzer**: Parse logs, detect patterns, generate reports
|
||||
- **Metrics aggregator**: Collect data, analyze trends, visualize
|
||||
|
||||
## When NOT to Use Complex Structure
|
||||
|
||||
Avoid over-engineering:
|
||||
- Don't create modes if phases suffice
|
||||
- Don't add scripts if pure LLM can handle it
|
||||
- Don't add directories you won't populate
|
||||
- Start minimal, grow as needed
|
||||
91
skills/skill-creator/examples/minimal-skill/README.md
Normal file
91
skills/skill-creator/examples/minimal-skill/README.md
Normal file
@@ -0,0 +1,91 @@
|
||||
# Minimal Skill Structure Example
|
||||
|
||||
This example shows the minimal required structure for a simple skill.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
minimal-skill/
|
||||
├── SKILL.md # Agent manifest (required)
|
||||
├── README.md # User documentation (required)
|
||||
├── plugin.json # Marketplace metadata (required)
|
||||
└── CHANGELOG.md # Version history (required)
|
||||
```
|
||||
|
||||
## When to Use Minimal Structure
|
||||
|
||||
Use this structure when:
|
||||
- Skill has a single straightforward workflow
|
||||
- No multiple modes or complex branching
|
||||
- Minimal configuration needed
|
||||
- No external dependencies or scripts
|
||||
- Simple automation or transformation task
|
||||
|
||||
## Examples of Minimal Skills
|
||||
|
||||
- **Code Formatter**: Applies consistent formatting to code files
|
||||
- **Template Generator**: Creates files from simple templates
|
||||
- **Single-Purpose Validator**: Checks one specific thing
|
||||
|
||||
## Characteristics
|
||||
|
||||
- **Complexity**: Low
|
||||
- **Files**: 4 required only
|
||||
- **Pattern**: Usually phase-based with 2-3 simple phases
|
||||
- **Modes**: None (single workflow)
|
||||
- **Scripts**: None
|
||||
- **Dependencies**: None or minimal
|
||||
|
||||
## SKILL.md Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
version: 0.1.0
|
||||
description: Brief description of what this skill does
|
||||
author: Your Name
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
## Overview
|
||||
|
||||
What this skill does in detail.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Trigger Phrases:**
|
||||
- "phrase 1"
|
||||
- "phrase 2"
|
||||
|
||||
**Use Cases:**
|
||||
- Use case 1
|
||||
- Use case 2
|
||||
|
||||
## Workflow
|
||||
|
||||
### Phase 1: Setup
|
||||
1. Validate inputs
|
||||
2. Gather context
|
||||
|
||||
### Phase 2: Execute
|
||||
1. Perform main action
|
||||
2. Verify result
|
||||
|
||||
### Phase 3: Completion
|
||||
1. Report results
|
||||
2. Provide next steps
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Keep it simple**: Don't add structure you don't need
|
||||
2. **Clear workflow**: 2-4 phases maximum
|
||||
3. **Explicit success criteria**: User knows when it's done
|
||||
4. **Good examples**: Show concrete usage in README
|
||||
5. **Test thoroughly**: Minimal doesn't mean untested
|
||||
142
skills/skill-creator/examples/standard-skill/README.md
Normal file
142
skills/skill-creator/examples/standard-skill/README.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# Standard Skill Structure Example
|
||||
|
||||
This example shows the standard structure used by most skills in the marketplace.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
standard-skill/
|
||||
├── SKILL.md # Agent manifest (required)
|
||||
├── README.md # User documentation (required)
|
||||
├── plugin.json # Marketplace metadata (required)
|
||||
├── CHANGELOG.md # Version history (required)
|
||||
├── data/ # Reference materials, standards (optional)
|
||||
│ ├── best-practices.md
|
||||
│ ├── standards.yaml
|
||||
│ └── references.md
|
||||
├── examples/ # Sample outputs (optional)
|
||||
│ ├── example-1.md
|
||||
│ └── example-2.md
|
||||
└── templates/ # Reusable templates (optional)
|
||||
├── report-template.md
|
||||
└── output-template.json
|
||||
```
|
||||
|
||||
## When to Use Standard Structure
|
||||
|
||||
Use this structure when:
|
||||
- Sequential workflow with clear phases
|
||||
- Needs reference materials or standards
|
||||
- Provides templates for outputs
|
||||
- Examples help users understand
|
||||
- Medium complexity
|
||||
|
||||
## Examples of Standard Skills
|
||||
|
||||
- **Codebase Auditor**: Analyzes code against standards
|
||||
- **CLAUDE.md Auditor**: Validates configuration files
|
||||
- **Documentation Generator**: Creates docs from code
|
||||
|
||||
## Characteristics
|
||||
|
||||
- **Complexity**: Medium
|
||||
- **Files**: 4 required + 3 optional directories
|
||||
- **Pattern**: Phase-based or validation
|
||||
- **Modes**: Usually single mode, sequential phases
|
||||
- **Scripts**: Rarely needed (pure LLM skill)
|
||||
- **Dependencies**: Minimal
|
||||
|
||||
## SKILL.md Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
version: 0.1.0
|
||||
description: Brief description of what this skill does
|
||||
author: Your Name
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
## Overview
|
||||
|
||||
Detailed description of capabilities.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Trigger Phrases:**
|
||||
- "phrase 1"
|
||||
- "phrase 2"
|
||||
- "phrase 3"
|
||||
|
||||
**Use Cases:**
|
||||
- Use case 1
|
||||
- Use case 2
|
||||
- Use case 3
|
||||
|
||||
## Workflow
|
||||
|
||||
### Phase 1: Discovery
|
||||
- Identify scope
|
||||
- Gather context
|
||||
- Validate prerequisites
|
||||
|
||||
### Phase 2: Analysis
|
||||
- Apply standards from data/
|
||||
- Check compliance
|
||||
- Detect issues
|
||||
|
||||
### Phase 3: Reporting
|
||||
- Generate report using templates/
|
||||
- Provide examples from examples/
|
||||
- Offer recommendations
|
||||
|
||||
### Phase 4: Remediation
|
||||
- Guide user through fixes
|
||||
- Verify improvements
|
||||
- Update documentation
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] All phases completed
|
||||
- [ ] Report generated
|
||||
- [ ] Recommendations provided
|
||||
|
||||
## Reference Materials
|
||||
|
||||
- `data/` - Standards and best practices
|
||||
- `examples/` - Sample outputs
|
||||
- `templates/` - Reusable templates
|
||||
```
|
||||
|
||||
## Directory Purposes
|
||||
|
||||
### data/
|
||||
Contains reference materials the skill consults:
|
||||
- Standards documents (YAML, MD)
|
||||
- Best practices guides
|
||||
- Lookup tables
|
||||
- Configuration defaults
|
||||
|
||||
### examples/
|
||||
Shows users what to expect:
|
||||
- Sample outputs
|
||||
- Before/after comparisons
|
||||
- Success stories
|
||||
- Common scenarios
|
||||
|
||||
### templates/
|
||||
Reusable output formats:
|
||||
- Report templates (Jinja2 or Markdown)
|
||||
- JSON schemas
|
||||
- Configuration files
|
||||
- Document structures
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Organized references**: Put all standards in data/
|
||||
2. **Concrete examples**: Show real usage in examples/
|
||||
3. **Reusable templates**: DRY principle for outputs
|
||||
4. **Progressive disclosure**: Start simple, add detail as needed
|
||||
5. **Clear phases**: Each phase has specific purpose
|
||||
6. **Documentation**: Reference materials are well-documented
|
||||
Reference in New Issue
Block a user