✨ feat: add commit_message and bdd_testing skills
- Create commit_message skill with Gitmoji validation and templates - Update bdd_testing skill to match validated BDD implementation - Add comprehensive documentation and validation scripts - Ensure all skills follow AGENTS.md conventions Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
782
.vibe/skills/skill_creator/references/ADVANCED_FEATURES.md
Normal file
782
.vibe/skills/skill_creator/references/ADVANCED_FEATURES.md
Normal file
@@ -0,0 +1,782 @@
|
||||
# Advanced Skill Creator Features
|
||||
|
||||
## Skill Versioning and Updates
|
||||
|
||||
### Version Management
|
||||
|
||||
```markdown
|
||||
## Version History
|
||||
|
||||
### v1.0.0 (Current)
|
||||
- Initial release
|
||||
- Basic skill scaffold generation
|
||||
- Specification validation
|
||||
- Best practices guide
|
||||
|
||||
### v1.1.0 (Planned)
|
||||
- Skill versioning support
|
||||
- Update notification system
|
||||
- Deprecation warnings
|
||||
- Migration guides
|
||||
|
||||
### v2.0.0 (Future)
|
||||
- Interactive skill creation
|
||||
- Visual skill editor
|
||||
- AI-assisted skill generation
|
||||
- Team collaboration features
|
||||
```
|
||||
|
||||
### Versioning Strategy
|
||||
|
||||
**Semantic Versioning:** `MAJOR.MINOR.PATCH`
|
||||
- **MAJOR**: Breaking changes
|
||||
- **MINOR**: New features (backward compatible)
|
||||
- **PATCH**: Bug fixes (backward compatible)
|
||||
|
||||
**Version Fields:**
|
||||
```yaml
|
||||
# SKILL.md
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
compatibility: ">=1.0.0"
|
||||
deprecated: false
|
||||
successor: ""
|
||||
```
|
||||
|
||||
## Skill Dependencies
|
||||
|
||||
### Dependency Management
|
||||
|
||||
```markdown
|
||||
## Dependencies
|
||||
|
||||
### Required Skills
|
||||
- `skill_creator` (this skill) v1.0.0+
|
||||
|
||||
### Optional Skills
|
||||
- `bdd_testing` v1.0.0+ (for BDD testing)
|
||||
- `documentation` v1.0.0+ (for doc generation)
|
||||
|
||||
### System Requirements
|
||||
- Go 1.26+
|
||||
- Bash 4.0+
|
||||
- Git 2.0+
|
||||
```
|
||||
|
||||
### Dependency Specification
|
||||
|
||||
```yaml
|
||||
# SKILL.md
|
||||
metadata:
|
||||
dependencies:
|
||||
required:
|
||||
- name: skill_creator
|
||||
version: ">=1.0.0"
|
||||
optional:
|
||||
- name: bdd_testing
|
||||
version: ">=1.0.0"
|
||||
system:
|
||||
- name: go
|
||||
version: ">=1.26"
|
||||
- name: bash
|
||||
version: ">=4.0"
|
||||
```
|
||||
|
||||
## Skill Lifecycle Management
|
||||
|
||||
### Skill States
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Draft] -->|Validate| B[Active]
|
||||
B -->|Deprecate| C[Deprecated]
|
||||
C -->|Remove| D[Archived]
|
||||
```
|
||||
|
||||
**State Transitions:**
|
||||
|
||||
```markdown
|
||||
### Skill Lifecycle
|
||||
|
||||
1. **Draft**: Under development, not ready for use
|
||||
- Prefix: `draft-`
|
||||
- Example: `draft-my-skill`
|
||||
|
||||
2. **Active**: Production-ready, actively maintained
|
||||
- No prefix
|
||||
- Example: `my-skill`
|
||||
|
||||
3. **Deprecated**: Replaced by newer version
|
||||
- Metadata: `deprecated: true`
|
||||
- Metadata: `successor: "new-skill"`
|
||||
|
||||
4. **Archived**: No longer maintained
|
||||
- Move to `archived/` directory
|
||||
- Example: `.vibe/skills/archived/old-skill/`
|
||||
```
|
||||
|
||||
## Advanced Skill Patterns
|
||||
|
||||
### Composite Skills
|
||||
|
||||
```markdown
|
||||
## Composite Skill Pattern
|
||||
|
||||
Combine multiple skills for complex workflows.
|
||||
|
||||
### Example: Full-Stack Testing
|
||||
|
||||
```yaml
|
||||
# SKILL.md
|
||||
name: fullstack-testing
|
||||
description: Combines BDD, unit, and integration testing
|
||||
metadata:
|
||||
composes:
|
||||
- bdd_testing
|
||||
- unit_testing
|
||||
- integration_testing
|
||||
```
|
||||
|
||||
### Implementation
|
||||
|
||||
```bash
|
||||
# Create composite skill
|
||||
.vibe/skills/skill_creator/scripts/create_composite_skill.sh fullstack-testing \
|
||||
bdd_testing unit_testing integration_testing
|
||||
```
|
||||
|
||||
### Workflow
|
||||
|
||||
```markdown
|
||||
## Testing Workflow
|
||||
|
||||
1. **BDD Tests**: Validate external behavior
|
||||
2. **Unit Tests**: Verify individual components
|
||||
3. **Integration Tests**: Check component interactions
|
||||
4. **Report**: Combine all test results
|
||||
```
|
||||
```
|
||||
|
||||
## Skill Testing and Validation
|
||||
|
||||
### Test Coverage
|
||||
|
||||
```markdown
|
||||
## Test Coverage
|
||||
|
||||
### Unit Tests
|
||||
- Validate individual skill components
|
||||
- Test scripts, templates, and utilities
|
||||
|
||||
### Integration Tests
|
||||
- Verify skill works with other skills
|
||||
- Test dependency resolution
|
||||
- Validate workflow execution
|
||||
|
||||
### End-to-End Tests
|
||||
- Complete skill lifecycle testing
|
||||
- Creation → Validation → Usage → Update → Deprecation
|
||||
```
|
||||
|
||||
### Test Automation
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# scripts/test-skill.sh
|
||||
|
||||
set -e
|
||||
|
||||
echo "Testing skill: $1"
|
||||
|
||||
# Validate structure
|
||||
.vibe/skills/skill_creator/scripts/validate_skill.sh "$1"
|
||||
|
||||
# Run unit tests if present
|
||||
if [ -f "$1/tests/unit_test.sh" ]; then
|
||||
echo "Running unit tests..."
|
||||
"$1/tests/unit_test.sh"
|
||||
fi
|
||||
|
||||
# Run integration tests if present
|
||||
if [ -f "$1/tests/integration_test.sh" ]; then
|
||||
echo "Running integration tests..."
|
||||
"$1/tests/integration_test.sh"
|
||||
fi
|
||||
|
||||
echo "✅ All tests passed for skill: $1"
|
||||
```
|
||||
|
||||
## Skill Documentation Standards
|
||||
|
||||
### Documentation Levels
|
||||
|
||||
```markdown
|
||||
## Documentation Maturity Levels
|
||||
|
||||
### Level 1: Basic
|
||||
- SKILL.md with essential fields
|
||||
- Basic README
|
||||
- Simple examples
|
||||
|
||||
### Level 2: Standard
|
||||
- Complete SKILL.md
|
||||
- Comprehensive README
|
||||
- Usage examples
|
||||
- Troubleshooting guide
|
||||
|
||||
### Level 3: Advanced
|
||||
- Best practices guide
|
||||
- Architecture diagrams
|
||||
- API reference
|
||||
- Video tutorials
|
||||
|
||||
### Level 4: Expert
|
||||
- Interactive documentation
|
||||
- AI-assisted guidance
|
||||
- Community contributions
|
||||
- Versioned documentation
|
||||
```
|
||||
|
||||
### Documentation Checklist
|
||||
|
||||
```markdown
|
||||
### Documentation Completeness Checklist
|
||||
|
||||
- [ ] SKILL.md with all required fields
|
||||
- [ ] Clear and specific description
|
||||
- [ ] Usage examples with code
|
||||
- [ ] Installation instructions
|
||||
- [ ] Configuration options
|
||||
- [ ] Troubleshooting guide
|
||||
- [ ] Best practices
|
||||
- [ ] API reference (if applicable)
|
||||
- [ ] Architecture overview
|
||||
- [ ] Contribution guidelines
|
||||
- [ ] License information
|
||||
- [ ] Change log
|
||||
- [ ] FAQ
|
||||
```
|
||||
|
||||
## Skill Discovery and Organization
|
||||
|
||||
### Skill Categorization
|
||||
|
||||
```markdown
|
||||
## Skill Categories
|
||||
|
||||
### By Domain
|
||||
- **Testing**: bdd_testing, unit_testing
|
||||
- **Development**: code_generation, refactoring
|
||||
- **Operations**: deployment, monitoring
|
||||
- **Documentation**: doc_generation, wiki_management
|
||||
|
||||
### By Technology
|
||||
- **Go**: go_best_practices, go_testing
|
||||
- **Web**: api_design, frontend_testing
|
||||
- **DevOps**: ci_cd, containerization
|
||||
|
||||
### By Purpose
|
||||
- **Productivity**: skill_creator, templates
|
||||
- **Quality**: testing, validation
|
||||
- **Collaboration**: code_review, documentation
|
||||
```
|
||||
|
||||
### Skill Index
|
||||
|
||||
```yaml
|
||||
# .vibe/skills/SKILL_INDEX.md
|
||||
---
|
||||
title: Skill Index
|
||||
description: Complete list of available skills
|
||||
---
|
||||
|
||||
# Available Skills
|
||||
|
||||
## Core Skills
|
||||
- [skill_creator](skill_creator/SKILL.md) - Create and manage skills
|
||||
- [bdd_testing](bdd_testing/SKILL.md) - BDD testing framework
|
||||
|
||||
## Testing Skills
|
||||
- [bdd_testing](bdd_testing/SKILL.md) - Behavior-Driven Development
|
||||
- [unit_testing](unit_testing/SKILL.md) - Unit testing patterns
|
||||
- [integration_testing](integration_testing/SKILL.md) - Integration testing
|
||||
|
||||
## Development Skills
|
||||
- [api_design](api_design/SKILL.md) - REST API design patterns
|
||||
- [error_handling](error_handling/SKILL.md) - Robust error handling
|
||||
- [performance_optimization](performance_optimization/SKILL.md) - Performance tuning
|
||||
```
|
||||
|
||||
## Skill Governance
|
||||
|
||||
### Ownership Model
|
||||
|
||||
```markdown
|
||||
## Skill Ownership
|
||||
|
||||
### Roles
|
||||
|
||||
1. **Skill Author**: Creates the initial skill
|
||||
2. **Skill Maintainer**: Responsible for updates and support
|
||||
3. **Skill Reviewer**: Approves changes and updates
|
||||
4. **Skill User**: Uses the skill in their work
|
||||
|
||||
### Responsibilities
|
||||
|
||||
| Role | Responsibilities |
|
||||
|------|------------------|
|
||||
| Author | Initial creation, documentation |
|
||||
| Maintainer | Updates, bug fixes, support |
|
||||
| Reviewer | Quality assurance, approvals |
|
||||
| User | Feedback, issue reporting |
|
||||
|
||||
### Ownership Metadata
|
||||
|
||||
```yaml
|
||||
# SKILL.md
|
||||
metadata:
|
||||
author: "Jane Doe <jane@example.com>"
|
||||
maintainer: "John Smith <john@example.com>"
|
||||
reviewers:
|
||||
- "Alice Brown <alice@example.com>"
|
||||
status: "active"
|
||||
support: "https://github.com/org/repo/issues"
|
||||
```
|
||||
|
||||
## Advanced Validation
|
||||
|
||||
### Validation Levels
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# scripts/validate-advanced.sh
|
||||
|
||||
set -e
|
||||
|
||||
SKILL_DIR=$1
|
||||
LEVEL=${2:-standard} # basic, standard, advanced, expert
|
||||
|
||||
echo "Validating skill at level: $LEVEL"
|
||||
|
||||
# Basic validation (always required)
|
||||
.vibe/skills/skill_creator/scripts/validate_skill.sh "$SKILL_DIR"
|
||||
|
||||
# Standard validation
|
||||
if [ "$LEVEL" != "basic" ]; then
|
||||
echo "Checking standard requirements..."
|
||||
# Check for README
|
||||
if [ ! -f "$SKILL_DIR/README.md" ]; then
|
||||
echo "⚠️ WARNING: README.md recommended for standard level"
|
||||
fi
|
||||
|
||||
# Check for examples
|
||||
if ! grep -q "## Usage" "$SKILL_DIR/SKILL.md"; then
|
||||
echo "⚠️ WARNING: Usage examples recommended for standard level"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Advanced validation
|
||||
if [ "$LEVEL" = "advanced" ] || [ "$LEVEL" = "expert" ]; then
|
||||
echo "Checking advanced requirements..."
|
||||
|
||||
# Check for best practices
|
||||
if [ ! -f "$SKILL_DIR/references/BEST_PRACTICES.md" ]; then
|
||||
echo "⚠️ WARNING: BEST_PRACTICES.md recommended for advanced level"
|
||||
fi
|
||||
|
||||
# Check for troubleshooting
|
||||
if ! grep -q "## Troubleshooting" "$SKILL_DIR/SKILL.md"; then
|
||||
echo "⚠️ WARNING: Troubleshooting section recommended for advanced level"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Expert validation
|
||||
if [ "$LEVEL" = "expert" ]; then
|
||||
echo "Checking expert requirements..."
|
||||
|
||||
# Check for architecture diagrams
|
||||
if [ ! -f "$SKILL_DIR/references/ARCHITECTURE.md" ]; then
|
||||
echo "⚠️ WARNING: ARCHITECTURE.md recommended for expert level"
|
||||
fi
|
||||
|
||||
# Check for API reference
|
||||
if [ ! -f "$SKILL_DIR/references/API.md" ]; then
|
||||
echo "⚠️ WARNING: API.md recommended for expert level"
|
||||
fi
|
||||
fi
|
||||
|
||||
echo "✅ Validation complete for level: $LEVEL"
|
||||
```
|
||||
|
||||
## Skill Metrics and Analytics
|
||||
|
||||
### Usage Tracking
|
||||
|
||||
```markdown
|
||||
## Skill Metrics
|
||||
|
||||
### Usage Tracking
|
||||
|
||||
Track skill adoption and effectiveness:
|
||||
|
||||
```yaml
|
||||
# SKILL.md
|
||||
metadata:
|
||||
analytics:
|
||||
enabled: true
|
||||
tracking_id: "skill-bdd-testing-v1"
|
||||
```
|
||||
|
||||
### Metrics to Track
|
||||
|
||||
1. **Adoption Rate**: Number of teams using the skill
|
||||
2. **Usage Frequency**: How often the skill is used
|
||||
3. **Success Rate**: Percentage of successful executions
|
||||
4. **Error Rate**: Frequency of issues encountered
|
||||
5. **Time Saved**: Estimated productivity improvements
|
||||
6. **User Satisfaction**: Feedback and ratings
|
||||
|
||||
### Analytics Implementation
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# scripts/track-usage.sh
|
||||
|
||||
SKILL_NAME=$1
|
||||
ACTION=$2 # create, use, update, deprecate
|
||||
|
||||
# Log to analytics system
|
||||
curl -X POST "https://analytics.example.com/skills" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{
|
||||
\"skill\": \"$SKILL_NAME\",
|
||||
\"action\": \"$ACTION\",
|
||||
\"timestamp\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",
|
||||
\"version\": \"1.0.0\"
|
||||
}"
|
||||
|
||||
echo "Usage tracked: $SKILL_NAME - $ACTION"
|
||||
```
|
||||
|
||||
## Skill Improvement Process
|
||||
|
||||
### Continuous Improvement Workflow
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Identify Issue] --> B[Create Improvement]
|
||||
B --> C[Test Locally]
|
||||
C --> D[Submit PR]
|
||||
D --> E[Review]
|
||||
E -->|Approved| F[Merge]
|
||||
E -->|Rejected| B
|
||||
F --> G[Update Documentation]
|
||||
G --> H[Announce Changes]
|
||||
H --> I[Monitor Impact]
|
||||
```
|
||||
|
||||
### Improvement Checklist
|
||||
|
||||
```markdown
|
||||
### Skill Improvement Checklist
|
||||
|
||||
1. **Identify the issue**
|
||||
- [ ] Clear problem statement
|
||||
- [ ] Reproduction steps
|
||||
- [ ] Impact assessment
|
||||
|
||||
2. **Design solution**
|
||||
- [ ] Proposed changes
|
||||
- [ ] Backward compatibility
|
||||
- [ ] Test plan
|
||||
|
||||
3. **Implement changes**
|
||||
- [ ] Code changes
|
||||
- [ ] Documentation updates
|
||||
- [ ] Example updates
|
||||
|
||||
4. **Test thoroughly**
|
||||
- [ ] Unit tests pass
|
||||
- [ ] Integration tests pass
|
||||
- [ ] Manual testing complete
|
||||
|
||||
5. **Review and merge**
|
||||
- [ ] Peer review completed
|
||||
- [ ] All feedback addressed
|
||||
- [ ] Merge to main branch
|
||||
|
||||
6. **Communicate changes**
|
||||
- [ ] Release notes updated
|
||||
- [ ] Team notified
|
||||
- [ ] Documentation published
|
||||
|
||||
7. **Monitor impact**
|
||||
- [ ] Usage metrics tracked
|
||||
- [ ] User feedback collected
|
||||
- [ ] Issues resolved
|
||||
```
|
||||
|
||||
## Advanced Scripting
|
||||
|
||||
### Script Templates
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# scripts/advanced-script-template.sh
|
||||
|
||||
# Advanced script template with error handling, logging, and validation
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# Configuration
|
||||
SCRIPT_NAME=$(basename "$0")
|
||||
LOG_LEVEL=${LOG_LEVEL:-info}
|
||||
VERBOSE=${VERBOSE:-false}
|
||||
|
||||
# Logging functions
|
||||
log_info() { echo "[INFO] $*"; }
|
||||
log_warn() { echo "[WARN] $*" >&2; }
|
||||
log_error() { echo "[ERROR] $*" >&2; }
|
||||
log_debug() { if [ "$VERBOSE" = true ]; then echo "[DEBUG] $*"; fi }
|
||||
|
||||
# Error handling
|
||||
handle_error() {
|
||||
local exit_code=$1
|
||||
local line_number=$2
|
||||
log_error "Error in $SCRIPT_NAME at line $line_number with exit code $exit_code"
|
||||
exit $exit_code
|
||||
}
|
||||
trap 'handle_error $? $LINENO' ERR
|
||||
|
||||
# Validation
|
||||
validate_input() {
|
||||
if [ -z "${1:-}" ]; then
|
||||
log_error "Missing required argument"
|
||||
usage
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
# Main function
|
||||
main() {
|
||||
log_info "Starting $SCRIPT_NAME"
|
||||
|
||||
# Parse arguments
|
||||
while getopts "v" opt; do
|
||||
case $opt in
|
||||
v) VERBOSE=true ;;
|
||||
*) usage ;;
|
||||
esac
|
||||
done
|
||||
shift $((OPTIND-1))
|
||||
|
||||
# Validate input
|
||||
validate_input "$1"
|
||||
|
||||
# Business logic here
|
||||
log_info "Processing: $1"
|
||||
|
||||
# Success
|
||||
log_info "Completed successfully"
|
||||
}
|
||||
|
||||
# Usage
|
||||
usage() {
|
||||
cat <<EOF
|
||||
Usage: $SCRIPT_NAME [options] <argument>
|
||||
|
||||
Options:
|
||||
-v Verbose output
|
||||
-h Show this help
|
||||
|
||||
Arguments:
|
||||
<argument> Required input
|
||||
|
||||
Examples:
|
||||
$SCRIPT_NAME input_value
|
||||
$SCRIPT_NAME -v input_value
|
||||
EOF
|
||||
}
|
||||
|
||||
# Run main function
|
||||
main "$@"
|
||||
```
|
||||
|
||||
### Script Best Practices
|
||||
|
||||
```markdown
|
||||
## Advanced Scripting Best Practices
|
||||
|
||||
### 1. Error Handling
|
||||
- Use `set -euo pipefail` for strict error handling
|
||||
- Implement `trap` for error recovery
|
||||
- Provide meaningful error messages
|
||||
|
||||
### 2. Logging
|
||||
- Standardize log levels (INFO, WARN, ERROR, DEBUG)
|
||||
- Include timestamps for production scripts
|
||||
- Log to both console and files for important scripts
|
||||
|
||||
### 3. Input Validation
|
||||
- Validate all inputs and arguments
|
||||
- Provide clear error messages
|
||||
- Show usage examples on error
|
||||
|
||||
### 4. Configuration
|
||||
- Support environment variables
|
||||
- Allow command-line overrides
|
||||
- Provide sensible defaults
|
||||
|
||||
### 5. Testing
|
||||
- Test edge cases and error conditions
|
||||
- Validate script output
|
||||
- Test performance with large inputs
|
||||
|
||||
### 6. Documentation
|
||||
- Include usage examples
|
||||
- Document all options and arguments
|
||||
- Provide example output
|
||||
|
||||
### 7. Performance
|
||||
- Minimize external dependencies
|
||||
- Optimize I/O operations
|
||||
- Use efficient algorithms
|
||||
|
||||
### 8. Security
|
||||
- Validate all external inputs
|
||||
- Use temporary files securely
|
||||
- Avoid shell injection vulnerabilities
|
||||
```
|
||||
|
||||
## Skill Publishing and Distribution
|
||||
|
||||
### Publication Workflow
|
||||
|
||||
```markdown
|
||||
## Skill Publication Process
|
||||
|
||||
### 1. Development
|
||||
- Create skill using skill_creator
|
||||
- Implement functionality
|
||||
- Write documentation
|
||||
- Add tests
|
||||
|
||||
### 2. Validation
|
||||
- Run validation scripts
|
||||
- Check against best practices
|
||||
- Verify examples work
|
||||
- Test edge cases
|
||||
|
||||
### 3. Review
|
||||
- Peer review by team members
|
||||
- Address all feedback
|
||||
- Update documentation
|
||||
- Final testing
|
||||
|
||||
### 4. Publication
|
||||
- Tag release version
|
||||
- Update skill index
|
||||
- Announce to team
|
||||
- Add to documentation
|
||||
|
||||
### 5. Maintenance
|
||||
- Monitor usage and issues
|
||||
- Collect feedback
|
||||
- Plan improvements
|
||||
- Release updates
|
||||
```
|
||||
|
||||
### Distribution Channels
|
||||
|
||||
```markdown
|
||||
## Distribution Methods
|
||||
|
||||
### 1. Local Repository
|
||||
- Default location: `.vibe/skills/`
|
||||
- Version controlled with project
|
||||
- Easy to update and maintain
|
||||
|
||||
### 2. Central Repository
|
||||
- Organization-wide skill library
|
||||
- Versioned releases
|
||||
- Access control and governance
|
||||
|
||||
### 3. Package Manager
|
||||
- Publish as packages (npm, pip, etc.)
|
||||
- Version management
|
||||
- Dependency resolution
|
||||
|
||||
### 4. Cloud Registry
|
||||
- Centralized skill registry
|
||||
- Discovery and search
|
||||
- Ratings and reviews
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Roadmap
|
||||
|
||||
```markdown
|
||||
## Skill Creator Roadmap
|
||||
|
||||
### Short-Term (Next 3 Months)
|
||||
- [ ] Interactive skill creation wizard
|
||||
- [ ] Visual skill editor (web-based)
|
||||
- [ ] Skill dependency resolver
|
||||
- [ ] Automated skill testing
|
||||
|
||||
### Medium-Term (Next 6 Months)
|
||||
- [ ] AI-assisted skill generation
|
||||
- [ ] Skill marketplace integration
|
||||
- [ ] Team collaboration features
|
||||
- [ ] Version conflict resolution
|
||||
|
||||
### Long-Term (Next Year)
|
||||
- [ ] Natural language skill creation
|
||||
- [ ] Automated skill updates
|
||||
- [ ] Skill performance analytics
|
||||
- [ ] Enterprise skill management
|
||||
```
|
||||
|
||||
### Innovation Ideas
|
||||
|
||||
```markdown
|
||||
## Innovation Opportunities
|
||||
|
||||
### 1. AI-Powered Skills
|
||||
- Natural language to skill conversion
|
||||
- Automated skill improvement
|
||||
- Intelligent skill recommendations
|
||||
|
||||
### 2. Visual Skill Builder
|
||||
- Drag-and-drop interface
|
||||
- Real-time preview
|
||||
- Interactive documentation
|
||||
|
||||
### 3. Skill Marketplace
|
||||
- Discover and share skills
|
||||
- Ratings and reviews
|
||||
- Usage analytics
|
||||
|
||||
### 4. Skill Analytics
|
||||
- Usage tracking and insights
|
||||
- Performance monitoring
|
||||
- Impact measurement
|
||||
|
||||
### 5. Skill Collaboration
|
||||
- Team-based skill development
|
||||
- Version control integration
|
||||
- Change management
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
These advanced features represent the next evolution of the skill_creator, transforming it from a basic scaffolding tool to a comprehensive skill management platform. By implementing these enhancements, we can:
|
||||
|
||||
1. **Improve skill quality** through better validation and testing
|
||||
2. **Increase adoption** with easier creation and discovery
|
||||
3. **Enhance collaboration** with team features
|
||||
4. **Measure impact** with analytics and metrics
|
||||
5. **Scale effectively** with governance and lifecycle management
|
||||
|
||||
The skill_creator can become the foundation for a robust skill ecosystem that drives productivity, quality, and innovation across the organization.
|
||||
298
.vibe/skills/skill_creator/references/BEST_PRACTICES.md
Normal file
298
.vibe/skills/skill_creator/references/BEST_PRACTICES.md
Normal file
@@ -0,0 +1,298 @@
|
||||
# Skill Creation Best Practices
|
||||
|
||||
Based on the [Agent Skills Best Practices Guide](https://agentskills.io/skill-creation/best-practices)
|
||||
|
||||
## Core Principles
|
||||
|
||||
### Start from Real Expertise
|
||||
|
||||
Effective skills are grounded in real domain knowledge, not generic LLM knowledge. Feed project-specific context into the creation process.
|
||||
|
||||
**Sources of expertise:**
|
||||
- Hands-on task completion with agent assistance
|
||||
- Project artifacts (runbooks, API specs, schemas)
|
||||
- Code review comments and issue trackers
|
||||
- Version control history and patches
|
||||
- Real-world failure cases and resolutions
|
||||
|
||||
### Refine with Real Execution
|
||||
|
||||
Test skills against real tasks and refine based on execution traces. Look for:
|
||||
- False positives (skill activating when it shouldn't)
|
||||
- Missed steps or edge cases
|
||||
- Unproductive paths (agent trying multiple approaches)
|
||||
- Context overload (too much irrelevant information)
|
||||
|
||||
## Context Management
|
||||
|
||||
### Spend Context Wisely
|
||||
|
||||
Every token in your skill competes for attention in the agent's context window.
|
||||
|
||||
**Add what the agent lacks:**
|
||||
- Project-specific conventions
|
||||
- Domain-specific procedures
|
||||
- Non-obvious edge cases
|
||||
- Specific tools/APIs to use
|
||||
|
||||
**Omit what the agent knows:**
|
||||
- Basic concepts (what is a PDF, HTTP, database)
|
||||
- Generic best practices
|
||||
- Obvious implementation details
|
||||
|
||||
### Design Coherent Units
|
||||
|
||||
Skills should encapsulate a coherent unit of work that composes well with others:
|
||||
- **Too narrow**: Multiple skills needed for one task
|
||||
- **Too broad**: Hard to activate precisely
|
||||
- **Just right**: One skill handles one class of problems
|
||||
|
||||
### Aim for Moderate Detail
|
||||
|
||||
Concise, stepwise guidance with working examples outperforms exhaustive documentation.
|
||||
|
||||
## Instruction Patterns
|
||||
|
||||
### Gotchas Sections
|
||||
|
||||
List environment-specific facts that defy reasonable assumptions:
|
||||
|
||||
```markdown
|
||||
## Gotchas
|
||||
|
||||
- The `users` table uses soft deletes (add `WHERE deleted_at IS NULL`)
|
||||
- User ID is `user_id` in DB, `uid` in auth service, `accountId` in billing API
|
||||
- `/health` returns 200 even when DB is down (use `/ready` for full health check)
|
||||
```
|
||||
|
||||
### Templates for Output Format
|
||||
|
||||
Provide concrete format examples rather than prose descriptions:
|
||||
|
||||
```markdown
|
||||
## Report Structure
|
||||
|
||||
```markdown
|
||||
# [Analysis Title]
|
||||
|
||||
## Executive Summary
|
||||
[One-paragraph overview]
|
||||
|
||||
## Key Findings
|
||||
- Finding 1 with data
|
||||
- Finding 2 with data
|
||||
|
||||
## Recommendations
|
||||
1. Actionable recommendation
|
||||
2. Actionable recommendation
|
||||
```
|
||||
```
|
||||
|
||||
### Checklists for Multi-Step Workflows
|
||||
|
||||
```markdown
|
||||
## Deployment Workflow
|
||||
|
||||
Progress:
|
||||
- [ ] Step 1: Run tests
|
||||
- [ ] Step 2: Build artifacts
|
||||
- [ ] Step 3: Validate configuration
|
||||
- [ ] Step 4: Deploy to staging
|
||||
- [ ] Step 5: Run smoke tests
|
||||
```
|
||||
|
||||
### Validation Loops
|
||||
|
||||
```markdown
|
||||
## Code Review Process
|
||||
|
||||
1. Make changes
|
||||
2. Run linter: `npm run lint`
|
||||
3. If errors: fix and re-lint
|
||||
4. Run tests: `npm test`
|
||||
5. If failures: fix and re-test
|
||||
6. Only commit when all checks pass
|
||||
```
|
||||
|
||||
### Plan-Validate-Execute Pattern
|
||||
|
||||
```markdown
|
||||
## Database Migration
|
||||
|
||||
1. Generate migration plan: `migrate plan`
|
||||
2. Review plan against schema
|
||||
3. Validate: `migrate validate`
|
||||
4. If invalid: revise and re-validate
|
||||
5. Execute: `migrate apply`
|
||||
```
|
||||
|
||||
## Control Calibration
|
||||
|
||||
### Match Specificity to Fragility
|
||||
|
||||
**Give freedom** when multiple approaches are valid:
|
||||
```markdown
|
||||
## Code Review
|
||||
|
||||
Check for:
|
||||
- SQL injection vulnerabilities
|
||||
- Proper authentication
|
||||
- Race conditions
|
||||
- PII in error messages
|
||||
```
|
||||
|
||||
**Be prescriptive** when operations are fragile:
|
||||
```markdown
|
||||
## Database Migration
|
||||
|
||||
Run exactly:
|
||||
```bash
|
||||
python scripts/migrate.py --verify --backup
|
||||
```
|
||||
|
||||
Do not modify this command.
|
||||
```
|
||||
|
||||
### Provide Defaults, Not Menus
|
||||
|
||||
```markdown
|
||||
<!-- Avoid -->
|
||||
You can use pypdf, pdfplumber, PyMuPDF, or pdf2image...
|
||||
|
||||
<!-- Better -->
|
||||
Use pdfplumber for text extraction:
|
||||
|
||||
```python
|
||||
import pdfplumber
|
||||
```
|
||||
|
||||
For scanned PDFs, use pdf2image with pytesseract.
|
||||
```
|
||||
|
||||
### Favor Procedures Over Declarations
|
||||
|
||||
Teach *how to approach* problems, not *what to produce*:
|
||||
|
||||
```markdown
|
||||
<!-- Avoid -->
|
||||
Join orders to customers on customer_id, filter region='EMEA', sum amount.
|
||||
|
||||
<!-- Better -->
|
||||
1. Read schema from references/schema.yaml
|
||||
2. Join tables using _id foreign keys
|
||||
3. Apply user filters as WHERE clauses
|
||||
4. Aggregate and format as markdown table
|
||||
```
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
### Keep SKILL.md Under 500 Lines
|
||||
|
||||
Move detailed reference material to separate files in `references/`:
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # Core instructions (<500 lines)
|
||||
├── references/
|
||||
│ ├── api-spec.md # Detailed API documentation
|
||||
│ ├── error-codes.md # Error code reference
|
||||
│ └── schemas/ # Data schemas
|
||||
└── scripts/
|
||||
└── validate.sh # Validation script
|
||||
```
|
||||
|
||||
### Load Context on Demand
|
||||
|
||||
Tell the agent *when* to load reference files:
|
||||
|
||||
```markdown
|
||||
Read references/api-errors.md if the API returns non-200 status.
|
||||
```
|
||||
|
||||
## Skill Structure Checklist
|
||||
|
||||
### Required Elements
|
||||
- [ ] `SKILL.md` with valid YAML frontmatter
|
||||
- [ ] `name` field (lowercase alphanumeric + hyphens, 1-64 chars)
|
||||
- [ ] `description` field (1-1024 chars, specific about what/when)
|
||||
- [ ] Clear instructions in Markdown body
|
||||
|
||||
### Recommended Elements
|
||||
- [ ] `license` field
|
||||
- [ ] `metadata` with author/version
|
||||
- [ ] `scripts/` directory for reusable code
|
||||
- [ ] `references/` directory for detailed docs
|
||||
- [ ] `assets/` directory for templates/resources
|
||||
|
||||
### Validation Checklist
|
||||
- [ ] Skill name matches directory name (underscores → hyphens)
|
||||
- [ ] Description is specific and actionable
|
||||
- [ ] Instructions focus on what agent wouldn't know
|
||||
- [ ] Gotchas section for non-obvious issues
|
||||
- [ ] Examples provided for key workflows
|
||||
- [ ] Progressive disclosure used for large skills
|
||||
- [ ] Validation loops for critical operations
|
||||
|
||||
## Iteration Process
|
||||
|
||||
1. **Create initial draft** from real expertise
|
||||
2. **Test against real tasks**
|
||||
3. **Review execution traces** for inefficiencies
|
||||
4. **Refine instructions** based on observations
|
||||
5. **Add gotchas** from corrections made
|
||||
6. **Validate** with skill_creator
|
||||
7. **Repeat** until performance is satisfactory
|
||||
|
||||
## Common Anti-Patterns
|
||||
|
||||
### ❌ Generic Advice
|
||||
```markdown
|
||||
Handle errors appropriately and follow best practices.
|
||||
```
|
||||
|
||||
### ✅ Specific Guidance
|
||||
```markdown
|
||||
Check for HTTP 429 errors and implement exponential backoff:
|
||||
|
||||
```python
|
||||
import time
|
||||
import requests
|
||||
|
||||
for attempt in range(5):
|
||||
try:
|
||||
response = requests.get(url, timeout=10)
|
||||
break
|
||||
except requests.HTTPError as e:
|
||||
if e.response.status_code == 429:
|
||||
time.sleep(2 ** attempt)
|
||||
else:
|
||||
raise
|
||||
```
|
||||
```
|
||||
|
||||
### ❌ Overly Broad Scope
|
||||
```markdown
|
||||
This skill handles all database operations including queries, migrations, backups, and administration.
|
||||
```
|
||||
|
||||
### ✅ Focused Scope
|
||||
```markdown
|
||||
This skill handles database query optimization for read-heavy workloads on PostgreSQL 14+.
|
||||
```
|
||||
|
||||
### ❌ Menu of Options
|
||||
```markdown
|
||||
You can use any of these libraries: pandas, numpy, polars, or vaex.
|
||||
```
|
||||
|
||||
### ✅ Clear Default
|
||||
```markdown
|
||||
Use polars for DataFrame operations:
|
||||
|
||||
```python
|
||||
import polars as pl
|
||||
df = pl.read_csv("data.csv")
|
||||
```
|
||||
|
||||
For pandas compatibility, use the .to_pandas() method.
|
||||
```
|
||||
Reference in New Issue
Block a user