Initial commit
This commit is contained in:
Zhongwei Li
15
skills/skill-creator/CHANGELOG.md
Normal file
15
skills/skill-creator/CHANGELOG.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# Changelog
|
||||
|
||||
## 0.2.0
|
||||
|
||||
- Refactored to Anthropic progressive disclosure pattern
|
||||
- Updated description with "Use PROACTIVELY when..." format
|
||||
- Removed version/author from frontmatter
|
||||
|
||||
## 0.1.0
|
||||
|
||||
- Initial release with guided skill creation workflow
|
||||
- Four modes: Guided, Quick Start, Clone, Validate
|
||||
- Jinja2 template system for SKILL.md, README.md, CHANGELOG.md
|
||||
- Pattern library: mode-based, phase-based, validation, data-processing
|
||||
- Quality validation with A-F grade scoring
|
||||
328
skills/skill-creator/README.md
Normal file
328
skills/skill-creator/README.md
Normal file
@@ -0,0 +1,328 @@
|
||||
# Skill Creator
|
||||
|
||||
Automated skill generation tool that creates production-ready Claude Code skills following Claudex marketplace standards with intelligent templates, pattern detection, and quality validation.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```
|
||||
User: "Create a new skill for validating API responses"
|
||||
```
|
||||
|
||||
Claude will:
|
||||
1. Guide you through interactive questions
|
||||
2. Detect appropriate skill type and pattern
|
||||
3. Generate all required files with templates
|
||||
4. Install to ~/.claude/skills/
|
||||
5. Provide testing guidance and next steps
|
||||
|
||||
## Features
|
||||
|
||||
### Feature 1: Intelligent Skill Generation
|
||||
- Interactive guided creation with smart defaults
|
||||
- Automatic skill type detection (minimal/standard/complex)
|
||||
- Pattern selection based on skill purpose
|
||||
- Jinja2-based template population
|
||||
- Quality validation before finalization
|
||||
|
||||
### Feature 2: Multiple Creation Modes
|
||||
- **Guided Creation**: Full interactive process with questions
|
||||
- **Quick Start**: Template-based for fast setup
|
||||
- **Clone & Modify**: Base on existing skill patterns
|
||||
- **Validation Only**: Check existing skill quality
|
||||
|
||||
### Feature 3: Comprehensive Structure
|
||||
- All required files (SKILL.md, README.md, plugin.json, CHANGELOG.md)
|
||||
- Optional directories based on complexity (data/, examples/, templates/, modes/, scripts/)
|
||||
- Pattern-specific templates and guidance
|
||||
- Clear TODO markers for customization
|
||||
|
||||
### Feature 4: Quality Assurance
|
||||
- Built-in quality checklist validation
|
||||
- Security checks (no secrets or sensitive data)
|
||||
- Syntax validation (YAML, JSON, Markdown)
|
||||
- Naming convention enforcement
|
||||
- Grade-based scoring (A-F)
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Already installed in your .claude directory!
|
||||
# Located at: ~/.claude/skills/skill-creator/
|
||||
```
|
||||
|
||||
Or install manually:
|
||||
|
||||
```bash
|
||||
cp -r skill-creator ~/.claude/skills/
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Example 1: Create Analysis Skill
|
||||
|
||||
**Scenario:** Create a skill that audits React components for performance issues
|
||||
|
||||
```
|
||||
User: "Create a new skill for auditing React components"
|
||||
```
|
||||
|
||||
**Claude will ask:**
|
||||
1. Skill name: "react-performance-auditor"
|
||||
2. Description: "Analyzes React components for performance anti-patterns"
|
||||
3. Category: analysis (auto-suggested)
|
||||
4. Trigger phrases: (auto-generated + user confirms)
|
||||
5. Complexity: Standard (has reference materials)
|
||||
|
||||
**Result:**
|
||||
- Complete skill directory created
|
||||
- Standard structure with data/ for anti-patterns reference
|
||||
- Validation pattern applied
|
||||
- Quality report: Grade A
|
||||
- Ready for customization
|
||||
|
||||
### Example 2: Create Multi-Mode Skill
|
||||
|
||||
**Scenario:** Create a skill that manages environment variables (create/update/delete/list)
|
||||
|
||||
```
|
||||
User: "Create a skill for managing environment variables with multiple modes"
|
||||
```
|
||||
|
||||
**Claude will ask:**
|
||||
1. Basic info (name, description, author)
|
||||
2. Confirms: Complex skill with modes
|
||||
3. How many modes? 4 (create, update, delete, list)
|
||||
4. For each mode: name and trigger phrase
|
||||
5. Structure: Creates modes/ directory
|
||||
|
||||
**Result:**
|
||||
- Complex skill with mode-based pattern
|
||||
- Separate workflow files for each mode
|
||||
- Mode detection logic in SKILL.md
|
||||
- Quick decision matrix included
|
||||
- Ready for mode-specific customization
|
||||
|
||||
### Example 3: Create Data Processing Skill
|
||||
|
||||
**Scenario:** Create a skill that analyzes git commit history
|
||||
|
||||
```
|
||||
User: "Create a skill that analyzes git commit patterns"
|
||||
```
|
||||
|
||||
**Claude will detect:**
|
||||
- Data processing skill (analyzes git data)
|
||||
- Needs scripts/ directory
|
||||
- Should generate reports
|
||||
|
||||
**Result:**
|
||||
- Complex data-processing structure
|
||||
- scripts/ directory with placeholder scripts
|
||||
- Data pipeline architecture documented
|
||||
- Report templates included
|
||||
- Performance characteristics section
|
||||
|
||||
### Example 4: Quick Start with Template
|
||||
|
||||
**Scenario:** Quickly scaffold a minimal skill
|
||||
|
||||
```
|
||||
User: "Create a minimal skill called code-formatter"
|
||||
```
|
||||
|
||||
**Claude will:**
|
||||
1. Recognize "minimal" keyword
|
||||
2. Ask only essential questions (name, description)
|
||||
3. Use minimal template from examples/
|
||||
4. Generate with defaults
|
||||
5. Flag customization points
|
||||
|
||||
**Result:**
|
||||
- Minimal structure (4 required files only)
|
||||
- Fast generation (<1 minute)
|
||||
- All customization points marked with TODO
|
||||
- Simple phase-based workflow template
|
||||
|
||||
### Example 5: Clone Existing Pattern
|
||||
|
||||
**Scenario:** Create skill with same structure as codebase-auditor
|
||||
|
||||
```
|
||||
User: "Create a skill similar to codebase-auditor for database schemas"
|
||||
```
|
||||
|
||||
**Claude will:**
|
||||
1. Read codebase-auditor structure
|
||||
2. Extract pattern (validation, phase-based)
|
||||
3. Ask for new skill details
|
||||
4. Generate with same organizational structure
|
||||
5. Clear codebase-specific content
|
||||
|
||||
**Result:**
|
||||
- Same directory structure as codebase-auditor
|
||||
- Validation pattern applied
|
||||
- data/ and examples/ directories included
|
||||
- Content cleared, ready for customization
|
||||
|
||||
### Example 6: Validate Existing Skill
|
||||
|
||||
**Scenario:** Check quality of skill you're working on
|
||||
|
||||
```
|
||||
User: "Validate my custom-skill"
|
||||
```
|
||||
|
||||
**Claude will:**
|
||||
1. Locate skill at ~/.claude/skills/custom-skill/
|
||||
2. Run quality checklist
|
||||
3. Check all files and syntax
|
||||
4. Generate detailed report
|
||||
5. Provide remediation steps
|
||||
|
||||
**Result:**
|
||||
```markdown
|
||||
# Quality Report: custom-skill
|
||||
|
||||
## Grade: B (85/100)
|
||||
|
||||
### Issues Found:
|
||||
⚠️ HIGH: Missing usage examples in README.md
|
||||
📋 MEDIUM: Could use more trigger phrases (only 2, recommend 3-5)
|
||||
ℹ️ LOW: CHANGELOG could include more detail
|
||||
|
||||
### Remediation:
|
||||
1. Add 2-3 concrete examples to README.md
|
||||
2. Add 1-2 more trigger phrases to SKILL.md
|
||||
3. Expand CHANGELOG Added section
|
||||
|
||||
### Security: ✅ PASS (no issues)
|
||||
### Syntax: ✅ PASS (all valid)
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- Claude Code with Skills support
|
||||
- Write access to ~/.claude/skills/ directory
|
||||
- Python 3.8+ (for Jinja2 templates, if using scripts)
|
||||
|
||||
## Configuration
|
||||
|
||||
No additional configuration required. The skill uses:
|
||||
- Built-in templates from `templates/`
|
||||
- Pattern libraries from `patterns/`
|
||||
- Reference data from `data/`
|
||||
- Examples from `examples/`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue 1: Skill name already exists
|
||||
**Problem:** Directory ~/.claude/skills/[name]/ already exists
|
||||
**Solution:**
|
||||
- Choose a different name, or
|
||||
- Backup existing skill and remove directory, or
|
||||
- Use validation mode to check existing skill instead
|
||||
|
||||
### Issue 2: Permission denied
|
||||
**Problem:** Cannot write to ~/.claude/skills/
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check permissions
|
||||
ls -la ~/.claude/
|
||||
|
||||
# Fix permissions if needed
|
||||
chmod 755 ~/.claude/skills/
|
||||
|
||||
# Verify
|
||||
ls -la ~/.claude/skills/
|
||||
```
|
||||
|
||||
### Issue 3: Generated skill won't load
|
||||
**Problem:** Claude Code doesn't recognize new skill
|
||||
**Solution:**
|
||||
1. Check YAML frontmatter syntax in SKILL.md
|
||||
2. Verify plugin.json is valid JSON
|
||||
3. Restart Claude Code session
|
||||
4. Check skill appears in skill list
|
||||
|
||||
### Issue 4: Templates not rendering
|
||||
**Problem:** Jinja2 template errors during generation
|
||||
**Solution:**
|
||||
- Verify templates/ directory exists
|
||||
- Check template syntax
|
||||
- Report issue with specific error message
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start Simple**: Use minimal structure, grow as needed
|
||||
2. **Clear Trigger Phrases**: Make them intuitive and specific
|
||||
3. **Concrete Examples**: Show real usage scenarios in README
|
||||
4. **Test Early**: Try trigger phrases immediately after generation
|
||||
5. **Iterate**: Customize, test, refine workflow
|
||||
6. **Validate Often**: Run validation after changes
|
||||
7. **Reference Examples**: Look at existing skills for inspiration
|
||||
8. **Document Well**: Future you will thank you
|
||||
|
||||
## Limitations
|
||||
|
||||
- Cannot automatically implement skill logic (only scaffolding)
|
||||
- Jinja2 templates are opinionated (based on Claudex standards)
|
||||
- Assumes standard skill structure (may not fit all use cases)
|
||||
- Quality validation is structural (doesn't test functionality)
|
||||
- Mode detection requires clear user intent
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](https://github.com/cskiro/claudex/blob/main/CONTRIBUTING.md) for contribution guidelines.
|
||||
|
||||
## License
|
||||
|
||||
Apache 2.0
|
||||
|
||||
## Version History
|
||||
|
||||
See [CHANGELOG.md](./CHANGELOG.md) for version history.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Skill Types
|
||||
- **Minimal**: Simple automation, single workflow (4 files)
|
||||
- **Standard**: Sequential phases, reference materials (4 files + 3 dirs)
|
||||
- **Complex (Mode-Based)**: Multiple distinct modes (4 files + modes/)
|
||||
- **Complex (Data Processing)**: Data analysis, reports (4 files + scripts/)
|
||||
|
||||
### Patterns
|
||||
- **Phase-Based**: Sequential workflow with clear stages
|
||||
- **Mode-Based**: Multiple workflows based on user intent
|
||||
- **Validation**: Audit/compliance checking pattern
|
||||
- **Data Processing**: Ingest → Process → Analyze → Report
|
||||
|
||||
### Categories
|
||||
- **analysis**: Code analysis, auditing, quality checking
|
||||
- **tooling**: Development tools, configuration validators
|
||||
- **productivity**: Workflow, automation, insights
|
||||
- **devops**: Infrastructure, deployment, monitoring
|
||||
|
||||
### Creation Modes
|
||||
- **Guided**: Full interactive (most control)
|
||||
- **Quick Start**: Template-based (fastest)
|
||||
- **Clone**: Copy existing pattern (proven structure)
|
||||
- **Validate**: Check existing quality (QA)
|
||||
|
||||
## Support
|
||||
|
||||
For questions or issues:
|
||||
1. Check this README for common scenarios
|
||||
2. Review examples/ directory for structure guidance
|
||||
3. Consult patterns/ for pattern-specific guidance
|
||||
4. Read data/quality-checklist.md for validation criteria
|
||||
5. Open a discussion on GitHub
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **claude-md-auditor**: Validates SKILL.md files specifically
|
||||
- **codebase-auditor**: General code quality analysis
|
||||
- All skills in ~/.claude/skills/ serve as examples
|
||||
|
||||
---
|
||||
|
||||
**Remember**: This skill handles the boring scaffolding work so you can focus on the creative and domain-specific parts of your skill!
|
||||
182
skills/skill-creator/SKILL.md
Normal file
182
skills/skill-creator/SKILL.md
Normal file
@@ -0,0 +1,182 @@
|
||||
---
|
||||
name: skill-creator
|
||||
description: Use PROACTIVELY when creating new Claude Code skills from scratch. Automated generation tool following Claudex marketplace standards with intelligent templates, pattern detection, and quality validation. Supports guided creation, quick start templates, clone-and-modify, and validation-only modes. Not for modifying existing skills or non-skill Claude Code configurations.
|
||||
---
|
||||
|
||||
# Skill Creator
|
||||
|
||||
Automates creation of Claude Code skills through interactive guidance, template generation, and quality validation.
|
||||
|
||||
## When to Use
|
||||
|
||||
**Trigger Phrases**:
|
||||
- "create a new skill for [purpose]"
|
||||
- "generate a skill called [name]"
|
||||
- "scaffold a [type] skill"
|
||||
- "set up a new skill"
|
||||
|
||||
**Use Cases**:
|
||||
- Creating new skills from scratch
|
||||
- Following Claudex marketplace standards
|
||||
- Learning skill structure through examples
|
||||
|
||||
## Quick Decision Matrix
|
||||
|
||||
| User Request | Mode | Action |
|
||||
|--------------|------|--------|
|
||||
| "create skill for [purpose]" | Guided | Interactive creation |
|
||||
| "create [type] skill" | Quick Start | Template-based |
|
||||
| "skill like [existing]" | Clone | Copy pattern |
|
||||
| "validate skill" | Validate | Quality check |
|
||||
|
||||
## Mode 1: Guided Creation (Default)
|
||||
|
||||
**Use when**: User wants full guidance and customization
|
||||
|
||||
**Process**:
|
||||
1. Gather basic info (name, description, author)
|
||||
2. Define purpose, category, triggers
|
||||
3. Assess complexity → determine skill type
|
||||
4. Customize directory structure
|
||||
5. Select pattern (mode-based, phase-based, validation, data-processing)
|
||||
6. Generate files from templates
|
||||
7. Run quality validation
|
||||
8. Provide installation and next steps
|
||||
|
||||
**Workflow**: `workflow/guided-creation.md`
|
||||
|
||||
## Mode 2: Quick Start
|
||||
|
||||
**Use when**: User specifies skill type directly (minimal, standard, complex)
|
||||
|
||||
**Process**:
|
||||
1. Confirm skill type
|
||||
2. Gather minimal required info
|
||||
3. Generate with standardized defaults
|
||||
4. Flag ALL customization points
|
||||
|
||||
**Advantages**: Fast, minimal questions
|
||||
**Trade-off**: More TODO sections to customize
|
||||
|
||||
## Mode 3: Clone & Modify
|
||||
|
||||
**Use when**: User wants to base skill on existing one
|
||||
|
||||
**Process**:
|
||||
1. Read existing skill's structure
|
||||
2. Extract organizational pattern (not content)
|
||||
3. Generate new skill with same structure
|
||||
4. Clear example-specific content
|
||||
|
||||
**Advantages**: Proven structure, familiar patterns
|
||||
|
||||
## Mode 4: Validation Only
|
||||
|
||||
**Use when**: User wants to check existing skill quality
|
||||
|
||||
**Process**:
|
||||
1. Read existing skill files
|
||||
2. Run quality checklist
|
||||
3. Generate validation report
|
||||
4. Offer to fix issues automatically
|
||||
|
||||
**Use Case**: Before submission, after modifications
|
||||
|
||||
## Skill Types
|
||||
|
||||
| Type | Complexity | Directories | Pattern |
|
||||
|------|------------|-------------|---------|
|
||||
| Minimal | Low | SKILL.md, README.md only | phase-based |
|
||||
| Standard | Medium | + data/, examples/ | phase-based or validation |
|
||||
| Complex (mode) | High | + modes/, templates/ | mode-based |
|
||||
| Complex (data) | High | + scripts/, data/ | data-processing |
|
||||
|
||||
## Generated Files
|
||||
|
||||
**Required** (all skills):
|
||||
- `SKILL.md` - Main skill manifest
|
||||
- `README.md` - User documentation
|
||||
- `plugin.json` - Marketplace metadata
|
||||
- `CHANGELOG.md` - Version history
|
||||
|
||||
**Optional** (based on type):
|
||||
- `modes/` - Mode-specific workflows
|
||||
- `data/` - Reference materials
|
||||
- `examples/` - Example outputs
|
||||
- `templates/` - Reusable templates
|
||||
- `scripts/` - Automation scripts
|
||||
|
||||
## Quality Validation
|
||||
|
||||
Validates against `data/quality-checklist.md`:
|
||||
|
||||
- File existence (all required files)
|
||||
- Syntax (YAML frontmatter, JSON)
|
||||
- Content completeness
|
||||
- Security (no secrets)
|
||||
- Naming conventions (kebab-case)
|
||||
- Quality grade (A-F)
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] All required files generated
|
||||
- [ ] Valid YAML frontmatter
|
||||
- [ ] Valid JSON in plugin.json
|
||||
- [ ] No security issues
|
||||
- [ ] Kebab-case naming
|
||||
- [ ] Version 0.1.0 for new skills
|
||||
- [ ] At least 3 trigger phrases
|
||||
- [ ] Quality grade C or better
|
||||
|
||||
## Reference Materials
|
||||
|
||||
### Templates
|
||||
- `templates/SKILL.md.j2` - Main manifest
|
||||
- `templates/README.md.j2` - Documentation
|
||||
- `templates/plugin.json.j2` - Metadata
|
||||
- `templates/CHANGELOG.md.j2` - History
|
||||
|
||||
### Patterns
|
||||
- `patterns/mode-based.md` - Multi-mode skills
|
||||
- `patterns/phase-based.md` - Sequential workflows
|
||||
- `patterns/validation.md` - Audit skills
|
||||
- `patterns/data-processing.md` - Data analysis
|
||||
|
||||
### Reference Data
|
||||
- `data/categories.yaml` - Valid categories
|
||||
- `data/skill-types.yaml` - Type definitions
|
||||
- `data/quality-checklist.md` - Validation criteria
|
||||
|
||||
### Examples
|
||||
- `examples/minimal-skill/`
|
||||
- `examples/standard-skill/`
|
||||
- `examples/complex-skill/`
|
||||
|
||||
## Quick Commands
|
||||
|
||||
```bash
|
||||
# Check existing skills
|
||||
ls ~/.claude/skills/
|
||||
|
||||
# View skill structure
|
||||
tree ~/.claude/skills/[skill-name]/
|
||||
|
||||
# Validate frontmatter
|
||||
head -20 ~/.claude/skills/[skill-name]/SKILL.md
|
||||
|
||||
# Validate JSON
|
||||
python -m json.tool ~/.claude/skills/[skill-name]/plugin.json
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Solution |
|
||||
|-------|----------|
|
||||
| Name exists | Suggest alternatives or confirm overwrite |
|
||||
| Invalid name | Explain kebab-case, provide corrected suggestion |
|
||||
| Permission denied | Check ~/.claude/skills/ write access |
|
||||
| Template fails | Fallback to manual creation with guidance |
|
||||
|
||||
---
|
||||
|
||||
**Version**: 0.1.0 | **Author**: Connor
|
||||
54
skills/skill-creator/data/categories.yaml
Normal file
54
skills/skill-creator/data/categories.yaml
Normal file
@@ -0,0 +1,54 @@
|
||||
# Valid skill categories for Claudex marketplace
|
||||
# Each category has a name, description, and example skills
|
||||
|
||||
categories:
|
||||
analysis:
|
||||
name: "analysis"
|
||||
description: "Code analysis, auditing, quality checking"
|
||||
examples:
|
||||
- "codebase-auditor"
|
||||
- "claude-md-auditor"
|
||||
- "bulletproof-react-auditor"
|
||||
use_when:
|
||||
- "Skill validates or audits code/configuration"
|
||||
- "Skill detects issues and provides remediation"
|
||||
- "Skill checks compliance against standards"
|
||||
|
||||
tooling:
|
||||
name: "tooling"
|
||||
description: "Development tools, configuration validators"
|
||||
examples:
|
||||
- "git-worktree-setup"
|
||||
use_when:
|
||||
- "Skill automates development workflows"
|
||||
- "Skill manages development environment"
|
||||
- "Skill provides developer utilities"
|
||||
|
||||
productivity:
|
||||
name: "productivity"
|
||||
description: "Developer workflow, automation, insights"
|
||||
examples:
|
||||
- "cc-insights"
|
||||
use_when:
|
||||
- "Skill improves developer efficiency"
|
||||
- "Skill provides insights from data"
|
||||
- "Skill automates repetitive tasks"
|
||||
|
||||
devops:
|
||||
name: "devops"
|
||||
description: "Infrastructure, deployment, monitoring"
|
||||
examples:
|
||||
- "claude-code-otel-setup"
|
||||
use_when:
|
||||
- "Skill manages infrastructure"
|
||||
- "Skill handles deployment pipelines"
|
||||
- "Skill sets up monitoring/observability"
|
||||
|
||||
# Selection guidance
|
||||
selection_tips:
|
||||
- "Choose the category that best describes the PRIMARY purpose"
|
||||
- "If skill fits multiple categories, choose the most specific"
|
||||
- "Analysis: Focus on checking/validating"
|
||||
- "Tooling: Focus on developer workflows"
|
||||
- "Productivity: Focus on insights and efficiency"
|
||||
- "DevOps: Focus on infrastructure and deployment"
|
||||
211
skills/skill-creator/data/quality-checklist.md
Normal file
211
skills/skill-creator/data/quality-checklist.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# Skill Quality Checklist
|
||||
|
||||
Use this checklist to validate skill quality before submission or installation.
|
||||
|
||||
## Required Files (Critical)
|
||||
|
||||
- [ ] `SKILL.md` exists with valid YAML frontmatter
|
||||
- [ ] `README.md` exists with usage examples
|
||||
- [ ] `plugin.json` exists with valid JSON
|
||||
- [ ] `CHANGELOG.md` exists with v0.1.0 entry
|
||||
|
||||
## SKILL.md Validation
|
||||
|
||||
### Frontmatter
|
||||
- [ ] `name` field present (kebab-case)
|
||||
- [ ] `version` field present (0.1.0 for new skills)
|
||||
- [ ] `description` field present (1-2 sentences)
|
||||
- [ ] `author` field present
|
||||
|
||||
### Required Sections
|
||||
- [ ] "Overview" section describes skill capabilities
|
||||
- [ ] "When to Use This Skill" with trigger phrases
|
||||
- [ ] "When to Use This Skill" with use cases (3-5 items)
|
||||
- [ ] "Core Responsibilities" or "Workflow" section
|
||||
- [ ] "Success Criteria" or similar completion checklist
|
||||
|
||||
### Content Quality
|
||||
- [ ] No placeholder text like "[TODO]" or "[FILL IN]" (unless marked for user customization)
|
||||
- [ ] Trigger phrases are specific and actionable
|
||||
- [ ] Use cases clearly describe when to activate skill
|
||||
- [ ] Workflow or responsibilities are detailed
|
||||
- [ ] No generic programming advice (Claude already knows this)
|
||||
|
||||
## README.md Validation
|
||||
|
||||
### Structure
|
||||
- [ ] Title matches skill name
|
||||
- [ ] Brief description (1-2 sentences) at top
|
||||
- [ ] "Quick Start" section with example
|
||||
- [ ] "Installation" instructions
|
||||
- [ ] At least 2 usage examples
|
||||
|
||||
### Content Quality
|
||||
- [ ] Examples are concrete and actionable
|
||||
- [ ] Installation instructions are clear
|
||||
- [ ] Requirements section lists dependencies
|
||||
- [ ] Troubleshooting section addresses common issues
|
||||
|
||||
## plugin.json Validation
|
||||
|
||||
### Required Fields
|
||||
- [ ] `name` matches skill directory name
|
||||
- [ ] `version` is valid semver (0.1.0 for new skills)
|
||||
- [ ] `description` matches SKILL.md frontmatter
|
||||
- [ ] `author` present
|
||||
- [ ] `license` is "Apache-2.0"
|
||||
- [ ] `homepage` URL is correct
|
||||
- [ ] `repository` object present with type and url
|
||||
|
||||
### Components
|
||||
- [ ] `components.agents` array present
|
||||
- [ ] At least one agent with `name` and `manifestPath`
|
||||
- [ ] `manifestPath` points to "SKILL.md"
|
||||
|
||||
### Metadata
|
||||
- [ ] `metadata.category` is one of: analysis, tooling, productivity, devops
|
||||
- [ ] `metadata.status` is "proof-of-concept" for new skills
|
||||
- [ ] `metadata.tested` describes testing scope
|
||||
|
||||
### Keywords
|
||||
- [ ] At least 3 keywords present
|
||||
- [ ] Keywords are relevant and specific
|
||||
- [ ] Keywords aid discoverability (not too generic)
|
||||
|
||||
## CHANGELOG.md Validation
|
||||
|
||||
- [ ] Follows "Keep a Changelog" format
|
||||
- [ ] Has section for version 0.1.0
|
||||
- [ ] Date is present and correct
|
||||
- [ ] "Added" section lists initial features
|
||||
- [ ] Status section describes testing level
|
||||
- [ ] Link to release tag at bottom
|
||||
|
||||
## Security Validation (Critical)
|
||||
|
||||
- [ ] No API keys, tokens, or passwords in any file
|
||||
- [ ] No database connection strings with credentials
|
||||
- [ ] No private keys (PEM format)
|
||||
- [ ] No internal IP addresses or infrastructure details
|
||||
- [ ] No hardcoded secrets of any kind
|
||||
|
||||
## Version Control
|
||||
|
||||
- [ ] `.gitignore` present if skill generates files (like .processed/)
|
||||
- [ ] No generated files committed (build artifacts, logs, etc.)
|
||||
- [ ] No large binary files (> 1MB)
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
- [ ] Skill name is kebab-case (e.g., "skill-name")
|
||||
- [ ] Directory name matches skill name
|
||||
- [ ] No spaces in names
|
||||
- [ ] Name is descriptive and not too generic
|
||||
|
||||
## Documentation Quality
|
||||
|
||||
- [ ] All sections are complete (no stubs)
|
||||
- [ ] Examples are realistic and helpful
|
||||
- [ ] Technical terms are explained or linked
|
||||
- [ ] Grammar and spelling are correct
|
||||
- [ ] Markdown formatting is valid
|
||||
|
||||
## Pattern Consistency
|
||||
|
||||
If skill uses specific pattern:
|
||||
|
||||
### Mode-Based Skills
|
||||
- [ ] "Quick Decision Matrix" present
|
||||
- [ ] "Mode Detection Logic" present
|
||||
- [ ] Each mode has clear trigger phrases
|
||||
- [ ] Modes are distinct and non-overlapping
|
||||
|
||||
### Phase-Based Skills
|
||||
- [ ] Phases are numbered and named
|
||||
- [ ] Each phase has clear purpose
|
||||
- [ ] Dependencies between phases are documented
|
||||
- [ ] Transition criteria are explicit
|
||||
|
||||
### Validation Skills
|
||||
- [ ] Validation sources are documented
|
||||
- [ ] Finding structure is consistent
|
||||
- [ ] Severity levels are defined
|
||||
- [ ] Score calculation is explained
|
||||
|
||||
### Data Processing Skills
|
||||
- [ ] Data flow architecture is documented
|
||||
- [ ] Storage strategy is explained
|
||||
- [ ] Performance characteristics are listed
|
||||
- [ ] Helper scripts are provided
|
||||
|
||||
## Testing Validation
|
||||
|
||||
- [ ] Skill can be loaded without errors
|
||||
- [ ] Trigger phrases activate the skill
|
||||
- [ ] Example workflows complete successfully
|
||||
- [ ] No obvious bugs or crashes
|
||||
|
||||
## User Experience
|
||||
|
||||
- [ ] Skill purpose is immediately clear
|
||||
- [ ] Trigger phrases are intuitive
|
||||
- [ ] Workflow is logical and easy to follow
|
||||
- [ ] Error messages are helpful
|
||||
- [ ] Success criteria are measurable
|
||||
|
||||
## Scoring
|
||||
|
||||
**Critical Issues** (Must fix before use):
|
||||
- Missing required files
|
||||
- Invalid JSON/YAML
|
||||
- Security issues (exposed secrets)
|
||||
- Skill fails to load
|
||||
|
||||
**High Priority** (Fix before submission):
|
||||
- Incomplete documentation
|
||||
- Missing examples
|
||||
- Unclear trigger phrases
|
||||
- Invalid metadata
|
||||
|
||||
**Medium Priority** (Improve when possible):
|
||||
- Inconsistent formatting
|
||||
- Missing optional sections
|
||||
- Could use more examples
|
||||
- Documentation could be clearer
|
||||
|
||||
**Low Priority** (Nice to have):
|
||||
- Additional examples
|
||||
- More detailed explanations
|
||||
- Enhanced formatting
|
||||
- Extra reference materials
|
||||
|
||||
## Overall Quality Score
|
||||
|
||||
Calculate a quality score:
|
||||
|
||||
```
|
||||
Critical Issues: 0 required (any critical issue = fail)
|
||||
High Priority: 0-2 acceptable (> 2 needs work)
|
||||
Medium Priority: 0-5 acceptable (> 5 needs improvement)
|
||||
Low Priority: Any number acceptable
|
||||
|
||||
Overall Grade:
|
||||
- A (90-100): Production ready, excellent quality
|
||||
- B (80-89): Good quality, minor improvements
|
||||
- C (70-79): Acceptable, some improvements needed
|
||||
- D (60-69): Needs work before submission
|
||||
- F (< 60): Significant issues, do not submit
|
||||
```
|
||||
|
||||
## Pre-Submission Final Check
|
||||
|
||||
Before submitting to marketplace:
|
||||
|
||||
1. [ ] Run through entire checklist
|
||||
2. [ ] Test in fresh Claude Code session
|
||||
3. [ ] Get peer review if possible
|
||||
4. [ ] Verify all links work
|
||||
5. [ ] Check for typos and errors
|
||||
6. [ ] Confirm no sensitive data
|
||||
7. [ ] Verify version is correct
|
||||
8. [ ] Update CHANGELOG if needed
|
||||
121
skills/skill-creator/data/skill-types.yaml
Normal file
121
skills/skill-creator/data/skill-types.yaml
Normal file
@@ -0,0 +1,121 @@
|
||||
# Skill type definitions for determining structure and patterns
|
||||
# Each type maps to a complexity level and recommended pattern
|
||||
|
||||
skill_types:
|
||||
minimal:
|
||||
name: "Minimal"
|
||||
description: "Simple automation with single workflow"
|
||||
complexity: "low"
|
||||
structure:
|
||||
required:
|
||||
- "SKILL.md"
|
||||
- "README.md"
|
||||
- "plugin.json"
|
||||
- "CHANGELOG.md"
|
||||
optional: []
|
||||
pattern: "phase-based"
|
||||
use_when:
|
||||
- "Single straightforward workflow"
|
||||
- "No multiple modes or complex branching"
|
||||
- "Minimal configuration needed"
|
||||
examples:
|
||||
- "Simple file formatters"
|
||||
- "Basic code generators"
|
||||
- "Single-purpose validators"
|
||||
|
||||
standard:
|
||||
name: "Standard"
|
||||
description: "Most common skills with reference materials"
|
||||
complexity: "medium"
|
||||
structure:
|
||||
required:
|
||||
- "SKILL.md"
|
||||
- "README.md"
|
||||
- "plugin.json"
|
||||
- "CHANGELOG.md"
|
||||
optional:
|
||||
- "data/"
|
||||
- "examples/"
|
||||
- "templates/"
|
||||
pattern: "phase-based"
|
||||
use_when:
|
||||
- "Sequential workflow with phases"
|
||||
- "Needs reference materials"
|
||||
- "Provides templates or examples"
|
||||
examples:
|
||||
- "codebase-auditor"
|
||||
- "claude-md-auditor"
|
||||
|
||||
complex:
|
||||
name: "Complex"
|
||||
description: "Multiple modes with separate workflows"
|
||||
complexity: "high"
|
||||
structure:
|
||||
required:
|
||||
- "SKILL.md"
|
||||
- "README.md"
|
||||
- "plugin.json"
|
||||
- "CHANGELOG.md"
|
||||
- "modes/"
|
||||
optional:
|
||||
- "data/"
|
||||
- "examples/"
|
||||
- "templates/"
|
||||
- "scripts/"
|
||||
pattern: "mode-based"
|
||||
use_when:
|
||||
- "Multiple distinct operating modes"
|
||||
- "Different workflows based on user intent"
|
||||
- "Complex decision logic needed"
|
||||
examples:
|
||||
- "git-worktree-setup (single/batch/cleanup/list)"
|
||||
- "Skills with multiple output formats"
|
||||
|
||||
data_processing:
|
||||
name: "Data Processing"
|
||||
description: "Skills that process, analyze, or transform data"
|
||||
complexity: "high"
|
||||
structure:
|
||||
required:
|
||||
- "SKILL.md"
|
||||
- "README.md"
|
||||
- "plugin.json"
|
||||
- "CHANGELOG.md"
|
||||
- "scripts/"
|
||||
optional:
|
||||
- "data/"
|
||||
- "examples/"
|
||||
- "templates/"
|
||||
- "dashboard/" # optional web UI
|
||||
pattern: "data-processing"
|
||||
use_when:
|
||||
- "Ingests data from files or APIs"
|
||||
- "Performs analysis or transformation"
|
||||
- "Generates insights or reports"
|
||||
- "Needs helper scripts for processing"
|
||||
examples:
|
||||
- "cc-insights"
|
||||
- "Log analyzers"
|
||||
- "Metrics aggregators"
|
||||
|
||||
# Pattern recommendations by skill purpose
|
||||
pattern_recommendations:
|
||||
validation_audit:
|
||||
primary_pattern: "validation"
|
||||
secondary_pattern: "phase-based"
|
||||
notes: "Use validation pattern for compliance checking, phase-based for workflow"
|
||||
|
||||
workflow_automation:
|
||||
primary_pattern: "phase-based"
|
||||
secondary_pattern: "mode-based"
|
||||
notes: "Use phase-based for sequential steps, mode-based if multiple workflows"
|
||||
|
||||
multi_mode_operation:
|
||||
primary_pattern: "mode-based"
|
||||
secondary_pattern: null
|
||||
notes: "Clear mode detection is critical for user experience"
|
||||
|
||||
data_analysis:
|
||||
primary_pattern: "data-processing"
|
||||
secondary_pattern: "phase-based"
|
||||
notes: "Use data-processing for pipelines, phase-based for analysis stages"
|
||||
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
|
||||
247
skills/skill-creator/patterns/data-processing.md
Normal file
247
skills/skill-creator/patterns/data-processing.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# Data Processing Skill Pattern
|
||||
|
||||
Use this pattern when your skill **processes, analyzes, or transforms** data to extract insights.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Skill ingests data from files or APIs
|
||||
- Performs analysis or transformation
|
||||
- Generates insights, reports, or visualizations
|
||||
- Examples: cc-insights (conversation analysis)
|
||||
|
||||
## Structure
|
||||
|
||||
### Data Flow Architecture
|
||||
|
||||
Define clear data pipeline:
|
||||
|
||||
```
|
||||
Input Sources → Processing → Storage → Query/Analysis → Output
|
||||
```
|
||||
|
||||
Example:
|
||||
```
|
||||
JSONL files → Parser → SQLite + Vector DB → Search/Analytics → Reports/Dashboard
|
||||
```
|
||||
|
||||
### Processing Modes
|
||||
|
||||
**Batch Processing:**
|
||||
- Process all data at once
|
||||
- Good for: Initial setup, complete reprocessing
|
||||
- Trade-off: Slow startup, complete data
|
||||
|
||||
**Incremental Processing:**
|
||||
- Process only new/changed data
|
||||
- Good for: Regular updates, performance
|
||||
- Trade-off: Complex state tracking
|
||||
|
||||
**Streaming Processing:**
|
||||
- Process data as it arrives
|
||||
- Good for: Real-time updates
|
||||
- Trade-off: Complex implementation
|
||||
|
||||
### Storage Strategy
|
||||
|
||||
Choose appropriate storage:
|
||||
|
||||
**SQLite:**
|
||||
- Structured metadata
|
||||
- Fast queries
|
||||
- Relational data
|
||||
- Good for: Indexes, aggregations
|
||||
|
||||
**Vector Database (ChromaDB):**
|
||||
- Semantic embeddings
|
||||
- Similarity search
|
||||
- Good for: RAG, semantic queries
|
||||
|
||||
**File System:**
|
||||
- Raw data
|
||||
- Large blobs
|
||||
- Good for: Backups, archives
|
||||
|
||||
## Example: CC Insights
|
||||
|
||||
**Input**: Claude Code conversation JSONL files
|
||||
|
||||
**Processing Pipeline:**
|
||||
1. JSONL Parser - Decode base64, extract messages
|
||||
2. Metadata Extractor - Timestamps, files, tools
|
||||
3. Embeddings Generator - Vector representations
|
||||
4. Pattern Detector - Identify trends
|
||||
|
||||
**Storage:**
|
||||
- SQLite: Conversation metadata, fast queries
|
||||
- ChromaDB: Vector embeddings, semantic search
|
||||
- Cache: Processed conversation data
|
||||
|
||||
**Query Interfaces:**
|
||||
1. CLI Search - Command-line semantic search
|
||||
2. Insight Generator - Pattern-based reports
|
||||
3. Dashboard - Interactive web UI
|
||||
|
||||
**Outputs:**
|
||||
- Search results with similarity scores
|
||||
- Weekly activity reports
|
||||
- File heatmaps
|
||||
- Tool usage analytics
|
||||
|
||||
## Data Processing Workflow
|
||||
|
||||
### Phase 1: Ingestion
|
||||
```markdown
|
||||
1. **Discover Data Sources**
|
||||
- Locate input files/APIs
|
||||
- Validate accessibility
|
||||
- Calculate scope (file count, size)
|
||||
|
||||
2. **Initial Validation**
|
||||
- Check format validity
|
||||
- Verify schema compliance
|
||||
- Estimate processing time
|
||||
|
||||
3. **State Management**
|
||||
- Track what's been processed
|
||||
- Support incremental updates
|
||||
- Handle failures gracefully
|
||||
```
|
||||
|
||||
### Phase 2: Processing
|
||||
```markdown
|
||||
1. **Parse/Transform**
|
||||
- Read raw data
|
||||
- Apply transformations
|
||||
- Handle errors and edge cases
|
||||
|
||||
2. **Extract Features**
|
||||
- Generate metadata
|
||||
- Calculate metrics
|
||||
- Create embeddings (if semantic search)
|
||||
|
||||
3. **Store Results**
|
||||
- Write to database(s)
|
||||
- Update indexes
|
||||
- Maintain consistency
|
||||
```
|
||||
|
||||
### Phase 3: Analysis
|
||||
```markdown
|
||||
1. **Query Interface**
|
||||
- Support multiple query types
|
||||
- Optimize for common patterns
|
||||
- Return ranked results
|
||||
|
||||
2. **Pattern Detection**
|
||||
- Aggregate data
|
||||
- Identify trends
|
||||
- Generate insights
|
||||
|
||||
3. **Visualization**
|
||||
- Format for human consumption
|
||||
- Support multiple output formats
|
||||
- Interactive when possible
|
||||
```
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
Document expected performance:
|
||||
|
||||
```markdown
|
||||
### Performance Characteristics
|
||||
|
||||
- **Initial indexing**: ~1-2 minutes for 100 records
|
||||
- **Incremental updates**: <5 seconds for new records
|
||||
- **Search latency**: <1 second for queries
|
||||
- **Report generation**: <10 seconds for standard reports
|
||||
- **Memory usage**: ~200MB for 1000 records
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Incremental Processing**: Don't reprocess everything on each run
|
||||
2. **State Tracking**: Track what's been processed to avoid duplicates
|
||||
3. **Batch Operations**: Process in batches for memory efficiency
|
||||
4. **Progress Indicators**: Show progress for long operations
|
||||
5. **Error Recovery**: Handle failures gracefully, resume where left off
|
||||
6. **Data Validation**: Validate inputs before expensive processing
|
||||
7. **Index Optimization**: Optimize databases for common queries
|
||||
8. **Memory Management**: Stream large files, don't load everything
|
||||
9. **Parallel Processing**: Use parallelism when possible
|
||||
10. **Cache Wisely**: Cache expensive computations
|
||||
|
||||
## Scripts Structure
|
||||
|
||||
For data processing skills, provide helper scripts:
|
||||
|
||||
```
|
||||
scripts/
|
||||
├── processor.py # Main data processing script
|
||||
├── indexer.py # Build indexes/embeddings
|
||||
├── query.py # Query interface (CLI)
|
||||
└── generator.py # Report/insight generation
|
||||
```
|
||||
|
||||
### Script Best Practices
|
||||
|
||||
```python
|
||||
# Good patterns for processing scripts:
|
||||
|
||||
# 1. Use click for CLI
|
||||
import click
|
||||
|
||||
@click.command()
|
||||
@click.option('--input', help='Input path')
|
||||
@click.option('--reindex', is_flag=True)
|
||||
def process(input, reindex):
|
||||
"""Process data from input source."""
|
||||
pass
|
||||
|
||||
# 2. Show progress
|
||||
from tqdm import tqdm
|
||||
for item in tqdm(items, desc="Processing"):
|
||||
process_item(item)
|
||||
|
||||
# 3. Handle errors gracefully
|
||||
try:
|
||||
result = process_item(item)
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to process {item}: {e}")
|
||||
continue # Continue with next item
|
||||
|
||||
# 4. Support incremental updates
|
||||
if not reindex and is_already_processed(item):
|
||||
continue
|
||||
|
||||
# 5. Use batch processing
|
||||
for batch in chunks(items, batch_size=32):
|
||||
process_batch(batch)
|
||||
```
|
||||
|
||||
## Storage Schema
|
||||
|
||||
Document your data schema:
|
||||
|
||||
```sql
|
||||
-- Example SQLite schema
|
||||
CREATE TABLE conversations (
|
||||
id TEXT PRIMARY KEY,
|
||||
timestamp INTEGER,
|
||||
message_count INTEGER,
|
||||
files_modified TEXT, -- JSON array
|
||||
tools_used TEXT -- JSON array
|
||||
);
|
||||
|
||||
CREATE INDEX idx_timestamp ON conversations(timestamp);
|
||||
CREATE INDEX idx_files ON conversations(files_modified);
|
||||
```
|
||||
|
||||
## Output Formats
|
||||
|
||||
Support multiple output formats:
|
||||
|
||||
1. **Markdown**: Human-readable reports
|
||||
2. **JSON**: Machine-readable for integration
|
||||
3. **CSV**: Spreadsheet-compatible data
|
||||
4. **HTML**: Styled reports with charts
|
||||
5. **Interactive**: Web dashboards (optional)
|
||||
78
skills/skill-creator/patterns/mode-based.md
Normal file
78
skills/skill-creator/patterns/mode-based.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# Mode-Based Skill Pattern
|
||||
|
||||
Use this pattern when your skill has **multiple distinct operating modes** based on user intent.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Skill performs fundamentally different operations based on context
|
||||
- Each mode has its own workflow and outputs
|
||||
- User intent determines which mode to activate
|
||||
- Examples: git-worktree-setup (single/batch/cleanup/list modes)
|
||||
|
||||
## Structure
|
||||
|
||||
### Quick Decision Matrix
|
||||
|
||||
Create a clear mapping of user requests to modes:
|
||||
|
||||
```
|
||||
User Request → Mode → Action
|
||||
───────────────────────────────────────────────────────────
|
||||
"trigger phrase 1" → Mode 1 → High-level action
|
||||
"trigger phrase 2" → Mode 2 → High-level action
|
||||
"trigger phrase 3" → Mode 3 → High-level action
|
||||
```
|
||||
|
||||
### Mode Detection Logic
|
||||
|
||||
Provide clear logic for mode selection:
|
||||
|
||||
```javascript
|
||||
// Mode 1: [Name]
|
||||
if (userMentions("keyword1", "keyword2")) {
|
||||
return "mode1-name";
|
||||
}
|
||||
|
||||
// Mode 2: [Name]
|
||||
if (userMentions("keyword3", "keyword4")) {
|
||||
return "mode2-name";
|
||||
}
|
||||
|
||||
// Ambiguous - ask user
|
||||
return askForClarification();
|
||||
```
|
||||
|
||||
### Separate Mode Documentation
|
||||
|
||||
For complex skills, create separate files for each mode:
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # Overview and mode detection
|
||||
├── modes/
|
||||
│ ├── mode1-name.md # Detailed workflow for mode 1
|
||||
│ ├── mode2-name.md # Detailed workflow for mode 2
|
||||
│ └── mode3-name.md # Detailed workflow for mode 3
|
||||
```
|
||||
|
||||
## Example: Git Worktree Setup
|
||||
|
||||
**Modes:**
|
||||
1. Single Worktree - Create one worktree
|
||||
2. Batch Worktrees - Create multiple worktrees
|
||||
3. Cleanup - Remove worktrees
|
||||
4. List/Manage - Show worktree status
|
||||
|
||||
**Detection Logic:**
|
||||
- "create worktree for X" → Single mode
|
||||
- "create worktrees for A, B, C" → Batch mode
|
||||
- "remove worktree" → Cleanup mode
|
||||
- "list worktrees" → List mode
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Clear Mode Boundaries**: Each mode should be distinct and non-overlapping
|
||||
2. **Explicit Detection**: Provide clear rules for mode selection
|
||||
3. **Clarification Path**: Always have a fallback to ask user when ambiguous
|
||||
4. **Mode Independence**: Each mode should work standalone
|
||||
5. **Shared Prerequisites**: Extract common validation to reduce duplication
|
||||
115
skills/skill-creator/patterns/phase-based.md
Normal file
115
skills/skill-creator/patterns/phase-based.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# Phase-Based Skill Pattern
|
||||
|
||||
Use this pattern when your skill follows **sequential phases** that build on each other.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Skill has a linear workflow with clear stages
|
||||
- Each phase depends on the previous phase
|
||||
- Progressive disclosure of complexity
|
||||
- Examples: codebase-auditor (discovery → analysis → reporting → remediation)
|
||||
|
||||
## Structure
|
||||
|
||||
### Phase Overview
|
||||
|
||||
Define clear phases with dependencies:
|
||||
|
||||
```
|
||||
Phase 1: Discovery
|
||||
↓
|
||||
Phase 2: Analysis
|
||||
↓
|
||||
Phase 3: Reporting
|
||||
↓
|
||||
Phase 4: Action/Remediation
|
||||
```
|
||||
|
||||
### Phase Workflow Template
|
||||
|
||||
```markdown
|
||||
## Workflow
|
||||
|
||||
### Phase 1: [Name]
|
||||
|
||||
**Purpose**: [What this phase accomplishes]
|
||||
|
||||
**Steps:**
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
**Output**: [What information is produced]
|
||||
|
||||
**Transition**: [When to move to next phase]
|
||||
|
||||
### Phase 2: [Name]
|
||||
|
||||
**Purpose**: [What this phase accomplishes]
|
||||
|
||||
**Inputs**: [Required from previous phase]
|
||||
|
||||
**Steps:**
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
|
||||
**Output**: [What information is produced]
|
||||
```
|
||||
|
||||
## Example: Codebase Auditor
|
||||
|
||||
**Phase 1: Initial Assessment** (Progressive Disclosure)
|
||||
- Lightweight scan to understand codebase
|
||||
- Identify tech stack and structure
|
||||
- Quick health check
|
||||
- **Output**: Project profile and initial findings
|
||||
|
||||
**Phase 2: Deep Analysis** (Load on Demand)
|
||||
- Based on Phase 1, perform targeted analysis
|
||||
- Code quality, security, testing, etc.
|
||||
- **Output**: Detailed findings with severity
|
||||
|
||||
**Phase 3: Report Generation**
|
||||
- Aggregate findings from Phase 2
|
||||
- Calculate scores and metrics
|
||||
- **Output**: Comprehensive audit report
|
||||
|
||||
**Phase 4: Remediation Planning**
|
||||
- Prioritize findings by severity
|
||||
- Generate action plan
|
||||
- **Output**: Prioritized task list
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Progressive Disclosure**: Start lightweight, go deep only when needed
|
||||
2. **Clear Transitions**: Explicitly state when moving between phases
|
||||
3. **Phase Independence**: Each phase should have clear inputs/outputs
|
||||
4. **Checkpoint Validation**: Verify prerequisites before advancing
|
||||
5. **Early Exit**: Allow stopping after any phase if user only needs partial analysis
|
||||
6. **Incremental Value**: Each phase should provide standalone value
|
||||
|
||||
## Phase Characteristics
|
||||
|
||||
### Discovery Phase
|
||||
- Fast and lightweight
|
||||
- Gather context and identify scope
|
||||
- No expensive operations
|
||||
- Output guides subsequent phases
|
||||
|
||||
### Analysis Phase
|
||||
- Deep dive based on discovery
|
||||
- Resource-intensive operations
|
||||
- Parallel processing when possible
|
||||
- Structured output for reporting
|
||||
|
||||
### Reporting Phase
|
||||
- Aggregate and synthesize data
|
||||
- Calculate metrics and scores
|
||||
- Generate human-readable output
|
||||
- Support multiple formats
|
||||
|
||||
### Action Phase
|
||||
- Provide recommendations
|
||||
- Generate implementation guidance
|
||||
- Offer to perform actions
|
||||
- Track completion
|
||||
174
skills/skill-creator/patterns/validation.md
Normal file
174
skills/skill-creator/patterns/validation.md
Normal file
@@ -0,0 +1,174 @@
|
||||
# Validation/Audit Skill Pattern
|
||||
|
||||
Use this pattern when your skill **validates, audits, or checks** artifacts against standards.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Skill checks compliance against defined standards
|
||||
- Detects issues and provides remediation guidance
|
||||
- Generates reports with severity levels
|
||||
- Examples: claude-md-auditor, codebase-auditor
|
||||
|
||||
## Structure
|
||||
|
||||
### Validation Sources
|
||||
|
||||
Clearly define what you're validating against:
|
||||
|
||||
```markdown
|
||||
## Validation Sources
|
||||
|
||||
### 1. ✅ Official Standards
|
||||
- **Source**: [Authority/documentation]
|
||||
- **Authority**: Highest (requirements)
|
||||
- **Examples**: [List key standards]
|
||||
|
||||
### 2. 💡 Best Practices
|
||||
- **Source**: Community/field experience
|
||||
- **Authority**: Medium (recommendations)
|
||||
- **Examples**: [List practices]
|
||||
|
||||
### 3. 🔬 Research/Optimization
|
||||
- **Source**: Academic research
|
||||
- **Authority**: Medium (evidence-based)
|
||||
- **Examples**: [List findings]
|
||||
```
|
||||
|
||||
### Finding Structure
|
||||
|
||||
Use consistent structure for all findings:
|
||||
|
||||
```markdown
|
||||
**Severity**: Critical | High | Medium | Low
|
||||
**Category**: [Type of issue]
|
||||
**Location**: [File:line or context]
|
||||
**Description**: [What the issue is]
|
||||
**Impact**: [Why it matters]
|
||||
**Remediation**: [How to fix]
|
||||
**Effort**: [Time estimate]
|
||||
**Source**: Official | Community | Research
|
||||
```
|
||||
|
||||
### Severity Levels
|
||||
|
||||
Define clear severity criteria:
|
||||
|
||||
- **Critical**: Security risk, production-blocking (fix immediately)
|
||||
- **High**: Significant quality issue (fix this sprint)
|
||||
- **Medium**: Moderate improvement (schedule for next quarter)
|
||||
- **Low**: Minor optimization (backlog)
|
||||
|
||||
### Score Calculation
|
||||
|
||||
Provide quantitative scoring:
|
||||
|
||||
```
|
||||
Overall Health Score (0-100):
|
||||
- 90-100: Excellent
|
||||
- 75-89: Good
|
||||
- 60-74: Fair
|
||||
- 40-59: Poor
|
||||
- 0-39: Critical
|
||||
|
||||
Category Scores:
|
||||
- Security: Should always be 100
|
||||
- Compliance: Aim for 80+
|
||||
- Best Practices: 70+ is good
|
||||
```
|
||||
|
||||
## Example: CLAUDE.md Auditor
|
||||
|
||||
**Validation Against:**
|
||||
1. Official Anthropic documentation (docs.claude.com)
|
||||
2. Community best practices (field experience)
|
||||
3. Academic research (LLM context optimization)
|
||||
|
||||
**Finding Categories:**
|
||||
- Security (secrets, sensitive data)
|
||||
- Official Compliance (Anthropic guidelines)
|
||||
- Best Practices (community recommendations)
|
||||
- Structure (organization, formatting)
|
||||
|
||||
**Output Modes:**
|
||||
1. Audit Report - Detailed findings
|
||||
2. JSON Report - Machine-readable for CI/CD
|
||||
3. Refactored File - Production-ready output
|
||||
|
||||
## Validation Workflow
|
||||
|
||||
### Step 1: Discovery
|
||||
- Locate target artifact(s)
|
||||
- Calculate metrics (size, complexity)
|
||||
- Read content for analysis
|
||||
|
||||
### Step 2: Analysis
|
||||
Run validators in priority order:
|
||||
1. Security Validation (CRITICAL)
|
||||
2. Official Compliance
|
||||
3. Best Practices
|
||||
4. Optimization Opportunities
|
||||
|
||||
### Step 3: Scoring
|
||||
- Calculate overall health score
|
||||
- Generate category-specific scores
|
||||
- Count findings by severity
|
||||
|
||||
### Step 4: Reporting
|
||||
- Generate human-readable report
|
||||
- Provide machine-readable output
|
||||
- Offer remediation options
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Prioritize Security**: Always check security first
|
||||
2. **Source Attribution**: Label each finding with its source
|
||||
3. **Actionable Remediation**: Provide specific fix instructions
|
||||
4. **Multiple Output Formats**: Support markdown, JSON, HTML
|
||||
5. **Incremental Improvement**: Don't overwhelm with all issues
|
||||
6. **Track Over Time**: Support baseline comparisons
|
||||
7. **CI/CD Integration**: Provide exit codes and JSON output
|
||||
|
||||
## Report Structure
|
||||
|
||||
```markdown
|
||||
# [Artifact] Audit Report
|
||||
|
||||
## Executive Summary
|
||||
- Overall health score: [X/100]
|
||||
- Critical findings: [count]
|
||||
- High findings: [count]
|
||||
- Top 3 priorities
|
||||
|
||||
## File Metrics
|
||||
- [Relevant size/complexity metrics]
|
||||
|
||||
## Detailed Findings
|
||||
|
||||
### Critical Issues
|
||||
[Grouped by category]
|
||||
|
||||
### High Priority Issues
|
||||
[Grouped by category]
|
||||
|
||||
### Medium Priority Issues
|
||||
[Grouped by category]
|
||||
|
||||
## Remediation Plan
|
||||
- P0: IMMEDIATE (critical)
|
||||
- P1: THIS SPRINT (high)
|
||||
- P2: NEXT QUARTER (medium)
|
||||
- P3: BACKLOG (low)
|
||||
```
|
||||
|
||||
## Success Criteria Template
|
||||
|
||||
```markdown
|
||||
A well-validated [artifact] should achieve:
|
||||
|
||||
- ✅ Security Score: 100/100
|
||||
- ✅ Compliance Score: 80+/100
|
||||
- ✅ Overall Health: 75+/100
|
||||
- ✅ Zero CRITICAL findings
|
||||
- ✅ < 3 HIGH findings
|
||||
- ✅ [Artifact-specific criteria]
|
||||
```
|
||||
26
skills/skill-creator/templates/CHANGELOG.md.j2
Normal file
26
skills/skill-creator/templates/CHANGELOG.md.j2
Normal file
@@ -0,0 +1,26 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to the {{ skill_name }} skill will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [{{ version }}] - {{ date }}
|
||||
|
||||
### Added
|
||||
- Initial release of {{ skill_name }}
|
||||
{% for feature in initial_features -%}
|
||||
- {{ feature }}
|
||||
{% endfor %}
|
||||
|
||||
### Features
|
||||
{% for feature in key_features -%}
|
||||
- **{{ feature.name }}**: {{ feature.description }}
|
||||
{% endfor %}
|
||||
|
||||
### Status
|
||||
- Proof of concept
|
||||
- Tested locally on 1-2 projects
|
||||
- Ready for community feedback and testing
|
||||
|
||||
[{{ version }}]: https://github.com/cskiro/claudex/releases/tag/{{ skill_name }}@{{ version }}
|
||||
109
skills/skill-creator/templates/README.md.j2
Normal file
109
skills/skill-creator/templates/README.md.j2
Normal file
@@ -0,0 +1,109 @@
|
||||
# {{ skill_title }}
|
||||
|
||||
{{ description }}
|
||||
|
||||
## Quick Start
|
||||
|
||||
```
|
||||
User: "{{ trigger_phrases[0] }}"
|
||||
```
|
||||
|
||||
Claude will:
|
||||
1. [Action 1]
|
||||
2. [Action 2]
|
||||
3. [Action 3]
|
||||
|
||||
## Features
|
||||
|
||||
### Feature 1: [Feature Name]
|
||||
- [Capability 1]
|
||||
- [Capability 2]
|
||||
- [Capability 3]
|
||||
|
||||
### Feature 2: [Feature Name]
|
||||
- [Capability 1]
|
||||
- [Capability 2]
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
/plugin install {{ skill_name }}@claudex
|
||||
```
|
||||
|
||||
Or manually:
|
||||
|
||||
```bash
|
||||
cp -r {{ skill_name }} ~/.claude/skills/
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Example 1: [Scenario Name]
|
||||
|
||||
**Scenario:** [Description of scenario]
|
||||
|
||||
```
|
||||
User: "{{ trigger_phrases[0] }}"
|
||||
```
|
||||
|
||||
**Result:**
|
||||
- [Outcome 1]
|
||||
- [Outcome 2]
|
||||
|
||||
### Example 2: [Another Scenario]
|
||||
|
||||
**Scenario:** [Description of scenario]
|
||||
|
||||
```
|
||||
User: "{{ trigger_phrases[1] if trigger_phrases|length > 1 else trigger_phrases[0] }}"
|
||||
```
|
||||
|
||||
**Result:**
|
||||
- [Outcome 1]
|
||||
- [Outcome 2]
|
||||
|
||||
## Requirements
|
||||
|
||||
- [Requirement 1]
|
||||
- [Requirement 2]
|
||||
|
||||
## Configuration
|
||||
|
||||
{% if has_config %}
|
||||
[TODO: Describe configuration options]
|
||||
{% else %}
|
||||
No additional configuration required.
|
||||
{% endif %}
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue 1: [Issue Name]
|
||||
**Problem:** [Description]
|
||||
**Solution:** [Steps to resolve]
|
||||
|
||||
### Issue 2: [Issue Name]
|
||||
**Problem:** [Description]
|
||||
**Solution:** [Steps to resolve]
|
||||
|
||||
## Best Practices
|
||||
|
||||
- [Practice 1]
|
||||
- [Practice 2]
|
||||
- [Practice 3]
|
||||
|
||||
## Limitations
|
||||
|
||||
- [Limitation 1]
|
||||
- [Limitation 2]
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](https://github.com/cskiro/claudex/blob/main/CONTRIBUTING.md) for contribution guidelines.
|
||||
|
||||
## License
|
||||
|
||||
Apache 2.0
|
||||
|
||||
## Version History
|
||||
|
||||
See [CHANGELOG.md](./CHANGELOG.md) for version history.
|
||||
124
skills/skill-creator/templates/SKILL.md.j2
Normal file
124
skills/skill-creator/templates/SKILL.md.j2
Normal file
@@ -0,0 +1,124 @@
|
||||
---
|
||||
name: {{ skill_name }}
|
||||
version: {{ version }}
|
||||
description: {{ description }}
|
||||
author: {{ author }}
|
||||
---
|
||||
|
||||
# {{ skill_title }}
|
||||
|
||||
## Overview
|
||||
|
||||
{{ detailed_description }}
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Trigger Phrases:**
|
||||
{% for phrase in trigger_phrases -%}
|
||||
- "{{ phrase }}"
|
||||
{% endfor %}
|
||||
**Use Cases:**
|
||||
{% for use_case in use_cases -%}
|
||||
- {{ use_case }}
|
||||
{% endfor %}
|
||||
|
||||
## Response Style
|
||||
|
||||
- **Characteristic 1**: [TODO: Define first response characteristic]
|
||||
- **Characteristic 2**: [TODO: Define second response characteristic]
|
||||
- **Characteristic 3**: [TODO: Define third response characteristic]
|
||||
|
||||
{% if has_modes %}
|
||||
## Quick Decision Matrix
|
||||
|
||||
```
|
||||
User Request → Mode → Action
|
||||
───────────────────────────────────────────────────────────
|
||||
{% for mode in modes -%}
|
||||
"{{ mode.trigger }}" → {{ mode.name }} → {{ mode.action }}
|
||||
{% endfor -%}
|
||||
```
|
||||
|
||||
## Mode Detection Logic
|
||||
|
||||
```javascript
|
||||
{% for mode in modes -%}
|
||||
// Mode {{ loop.index }}: {{ mode.name }}
|
||||
if (userMentions("{{ mode.keyword }}")) {
|
||||
return "{{ mode.name|lower|replace(' ', '-') }}";
|
||||
}
|
||||
|
||||
{% endfor -%}
|
||||
// Ambiguous - ask user
|
||||
return askForClarification();
|
||||
```
|
||||
|
||||
{% endif %}
|
||||
## Core Responsibilities
|
||||
|
||||
### 1. [First Responsibility]
|
||||
- ✓ [Detail 1]
|
||||
- ✓ [Detail 2]
|
||||
- ✓ [Detail 3]
|
||||
|
||||
### 2. [Second Responsibility]
|
||||
- ✓ [Detail 1]
|
||||
- ✓ [Detail 2]
|
||||
|
||||
## Workflow
|
||||
|
||||
{% if has_phases %}
|
||||
{% for phase in phases %}
|
||||
### Phase {{ loop.index }}: {{ phase.name }}
|
||||
{% for step in phase.steps -%}
|
||||
{{ loop.index }}. {{ step }}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
{% else %}
|
||||
### Phase 1: Initial Assessment
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
### Phase 2: Main Operation
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
|
||||
### Phase 3: Verification
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
{% endif %}
|
||||
|
||||
## Error Handling
|
||||
|
||||
Common issues and how to handle them:
|
||||
- **Error 1**: [Solution]
|
||||
- **Error 2**: [Solution]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
- [ ] [Criterion 3]
|
||||
|
||||
{% if has_reference_materials %}
|
||||
## Reference Materials
|
||||
|
||||
See additional documentation in:
|
||||
{% if has_data_dir -%}
|
||||
- `data/` - Best practices and standards
|
||||
{% endif -%}
|
||||
{% if has_modes_dir -%}
|
||||
- `modes/` - Detailed mode workflows
|
||||
{% endif -%}
|
||||
{% if has_examples_dir -%}
|
||||
- `examples/` - Sample outputs
|
||||
{% endif -%}
|
||||
{% if has_templates_dir -%}
|
||||
- `templates/` - Reusable templates
|
||||
{% endif -%}
|
||||
{% endif %}
|
||||
|
||||
---
|
||||
|
||||
**Remember:** [TODO: Add key reminder about using this skill effectively]
|
||||
39
skills/skill-creator/templates/plugin.json.j2
Normal file
39
skills/skill-creator/templates/plugin.json.j2
Normal file
@@ -0,0 +1,39 @@
|
||||
{
|
||||
"name": "{{ skill_name }}",
|
||||
"version": "{{ version }}",
|
||||
"description": "{{ description }}",
|
||||
"author": "{{ author }}",
|
||||
"license": "Apache-2.0",
|
||||
"homepage": "https://github.com/cskiro/claudex/tree/main/{{ skill_name }}",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/cskiro/claudex"
|
||||
},
|
||||
"keywords": [
|
||||
{% for keyword in keywords -%}
|
||||
"{{ keyword }}"{% if not loop.last %},{% endif %}
|
||||
|
||||
{% endfor -%}
|
||||
],
|
||||
{% if has_requirements -%}
|
||||
"requirements": {
|
||||
{% for req, version in requirements.items() -%}
|
||||
"{{ req }}": "{{ version }}"{% if not loop.last %},{% endif %}
|
||||
|
||||
{% endfor -%}
|
||||
},
|
||||
{% endif -%}
|
||||
"components": {
|
||||
"agents": [
|
||||
{
|
||||
"name": "{{ skill_name }}",
|
||||
"manifestPath": "SKILL.md"
|
||||
}
|
||||
]
|
||||
},
|
||||
"metadata": {
|
||||
"category": "{{ category }}",
|
||||
"status": "proof-of-concept",
|
||||
"tested": "1-2 projects locally"
|
||||
}
|
||||
}
|
||||
212
skills/skill-creator/workflow/guided-creation.md
Normal file
212
skills/skill-creator/workflow/guided-creation.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# Guided Creation Workflow
|
||||
|
||||
Detailed step-by-step process for Mode 1: Interactive skill creation.
|
||||
|
||||
## Step 1: Basic Information
|
||||
|
||||
Ask user for:
|
||||
|
||||
### Skill Name
|
||||
- Format: kebab-case (lowercase, hyphens)
|
||||
- Validate: no spaces, descriptive
|
||||
- Examples: "code-formatter", "test-generator", "api-validator"
|
||||
- Check: name doesn't conflict with existing skills
|
||||
|
||||
### Brief Description
|
||||
- 1-2 sentences for metadata
|
||||
- Used in plugin.json and SKILL.md frontmatter
|
||||
- Should clearly state what skill does
|
||||
|
||||
### Author Name
|
||||
- Default: Connor
|
||||
- Used in all metadata files
|
||||
|
||||
## Step 2: Skill Purpose & Category
|
||||
|
||||
### Detailed Description
|
||||
- 2-4 sentences for SKILL.md Overview
|
||||
- Explains full capabilities
|
||||
|
||||
### Category Selection
|
||||
Present options from `data/categories.yaml`:
|
||||
- **analysis**: Code analysis, auditing, quality checking
|
||||
- **tooling**: Development tools, configuration validators
|
||||
- **productivity**: Developer workflow, automation, insights
|
||||
- **devops**: Infrastructure, deployment, monitoring
|
||||
|
||||
Suggest category based on skill purpose, allow user to confirm/change.
|
||||
|
||||
### Trigger Phrases
|
||||
- Ask for 3-5 phrases users might say
|
||||
- Provide examples based on similar skills
|
||||
- Generate suggestions if needed
|
||||
|
||||
### Use Cases
|
||||
- 3-5 concrete scenarios
|
||||
- Specific, actionable situations
|
||||
|
||||
## Step 3: Complexity Assessment
|
||||
|
||||
Determine skill type through questions:
|
||||
|
||||
**Question 1**: "Does this skill have multiple distinct modes or workflows?"
|
||||
- Yes → Complex (mode-based)
|
||||
- No → Continue
|
||||
|
||||
**Question 2**: "Does this skill process data from files or generate reports?"
|
||||
- Yes → Complex (data-processing)
|
||||
- No → Continue
|
||||
|
||||
**Question 3**: "Does this skill need reference materials?"
|
||||
- Yes → Standard
|
||||
- No → Minimal
|
||||
|
||||
Reference: `data/skill-types.yaml`
|
||||
|
||||
## Step 4: Structure Customization
|
||||
|
||||
Based on type, ask about optional directories:
|
||||
|
||||
### For Standard or Complex skills:
|
||||
- "Will you need reference data files?" → create data/
|
||||
- "Will you need example outputs?" → create examples/
|
||||
- "Will you need reusable templates?" → create templates/
|
||||
|
||||
### For Complex (mode-based) skills:
|
||||
- "How many modes does this skill have?" (2-5 typical)
|
||||
- For each mode:
|
||||
- Mode name
|
||||
- When to use (trigger phrases)
|
||||
- Primary action
|
||||
|
||||
### For Complex (data-processing) skills:
|
||||
- "What data sources will you process?"
|
||||
- "What output formats do you need?"
|
||||
- Always create scripts/ directory
|
||||
|
||||
## Step 5: Pattern Selection
|
||||
|
||||
Select from `patterns/` based on skill type:
|
||||
- Minimal → phase-based.md
|
||||
- Standard → phase-based.md or validation.md
|
||||
- Complex (mode-based) → mode-based.md
|
||||
- Complex (data-processing) → data-processing.md
|
||||
|
||||
Present pattern to user: "I'll use the [pattern] pattern, which means..."
|
||||
|
||||
## Step 6: Generation
|
||||
|
||||
### Create Directory Structure
|
||||
```bash
|
||||
mkdir -p ~/.claude/skills/[skill-name]/{required,optional-dirs}
|
||||
```
|
||||
|
||||
### Generate Files from Templates
|
||||
Using Jinja2 templates:
|
||||
- SKILL.md from `templates/SKILL.md.j2`
|
||||
- README.md from `templates/README.md.j2`
|
||||
- plugin.json from `templates/plugin.json.j2`
|
||||
- CHANGELOG.md from `templates/CHANGELOG.md.j2`
|
||||
|
||||
### Apply Pattern-Specific Content
|
||||
- Include pattern guidance in sections
|
||||
- Add pattern templates if needed
|
||||
- Create mode files if mode-based
|
||||
|
||||
### Mark Customization Points
|
||||
- Add TODO comments where needed
|
||||
- Provide inline guidance
|
||||
- Reference examples/
|
||||
|
||||
## Step 7: Quality Validation
|
||||
|
||||
Run validation using `data/quality-checklist.md`:
|
||||
|
||||
1. **File Existence**: Verify all required files
|
||||
2. **Syntax Validation**: Check YAML/JSON
|
||||
3. **Content Completeness**: No empty required sections
|
||||
4. **Security Check**: No secrets
|
||||
5. **Naming Conventions**: Verify kebab-case
|
||||
6. **Quality Score**: Calculate A-F grade
|
||||
|
||||
### Validation Report Format
|
||||
|
||||
```markdown
|
||||
# Skill Quality Report: [skill-name]
|
||||
|
||||
## Status: [PASS/NEEDS WORK]
|
||||
|
||||
### Files Generated
|
||||
✅ SKILL.md
|
||||
✅ README.md
|
||||
✅ plugin.json
|
||||
✅ CHANGELOG.md
|
||||
|
||||
### Quality Score: [Grade]
|
||||
|
||||
### Items Needing Customization
|
||||
- [ ] SKILL.md: Complete "Response Style" section
|
||||
- [ ] SKILL.md: Fill in workflow details
|
||||
- [ ] README.md: Add concrete usage examples
|
||||
|
||||
### Validation Results
|
||||
✅ No security issues
|
||||
✅ Valid YAML frontmatter
|
||||
✅ Valid JSON in plugin.json
|
||||
✅ Proper naming conventions
|
||||
```
|
||||
|
||||
## Step 8: Installation & Next Steps
|
||||
|
||||
### Verify Installation
|
||||
```bash
|
||||
ls -la ~/.claude/skills/[skill-name]/
|
||||
```
|
||||
|
||||
### Testing Guidance
|
||||
```markdown
|
||||
## Test Your Skill
|
||||
|
||||
Try these trigger phrases in a new Claude session:
|
||||
1. "[trigger-phrase-1]"
|
||||
2. "[trigger-phrase-2]"
|
||||
3. "[trigger-phrase-3]"
|
||||
|
||||
Expected behavior: [What should happen]
|
||||
```
|
||||
|
||||
### Customization TODO List
|
||||
- List all sections marked with TODO
|
||||
- Prioritize by importance
|
||||
- Provide examples for each
|
||||
|
||||
### Next Steps
|
||||
```markdown
|
||||
## Next Steps
|
||||
|
||||
1. Review generated files in ~/.claude/skills/[skill-name]/
|
||||
2. Customize sections marked with TODO
|
||||
3. Add reference materials to data/ (if applicable)
|
||||
4. Create example outputs in examples/ (if applicable)
|
||||
5. Test trigger phrases in new Claude session
|
||||
6. Iterate on description and workflow
|
||||
7. Run validation again
|
||||
8. Ready to use or submit to marketplace!
|
||||
```
|
||||
|
||||
## Information Summary
|
||||
|
||||
By end of guided creation, you should have:
|
||||
|
||||
| Field | Source | Used In |
|
||||
|-------|--------|---------|
|
||||
| Skill name | User input | Directory, all files |
|
||||
| Brief description | User input | plugin.json, frontmatter |
|
||||
| Detailed description | User input | SKILL.md Overview |
|
||||
| Author | User input (default: Connor) | All metadata |
|
||||
| Category | User selection | plugin.json |
|
||||
| Trigger phrases | User input | SKILL.md |
|
||||
| Use cases | User input | SKILL.md |
|
||||
| Skill type | Assessment | Structure decisions |
|
||||
| Pattern | Auto-selected | SKILL.md structure |
|
||||
| Optional dirs | User input | Directory structure |
|
||||
Reference in New Issue
Block a user