jander99 Quick Start
Prerequisites:
- Write access to skill directory (.opencode/skill/ or .claude/skills/)
- Bash for validation script
- Git configured (for author metadata)
Tools Used: Read, Write, Edit, Bash, Grep, Glob
Three Primary Workflows:
Create a New Skill
User: "Create a skill for [task]" Agent: Follows 8-step creation workflowSee: references/creation-workflow.md
Validate & Grade Existing Skill
./scripts/validate-skill.sh path/to/skill # Returns: 34 validation checks + 100-point gradeSee: references/validation-guide.md
Rubric: references/grading-rubric.md
Optimize for Discoverability
User: "Make [skill-name] more discoverable" Agent: Analyzes description, adds verbs/keywordsSee: references/optimization-patterns.md
What I Do
- Create new skills from scratch with templates
- Validate skills against 34-check system (9 errors, 17 warnings, 8 suggestions)
- Grade skills using 100-point rubric (A/B/C/D/F scale)
- Optimize descriptions for auto-activation (5+ verbs, 10+ keywords)
- Generate slash commands with proper naming (ak- prefix for agent-kit)
- Audit existing skills for quality and compliance
- Refactor skills for token efficiency (1000-2000 token sweet spot)
- Bundle resources (assets/, references/, scripts/)
- Provide skill templates and patterns
When to Use Me
Use this skill when you:
- Create, write, or generate new Agent Skills
- Validate, audit, or review existing skills
- Grade or score skills using rubric
- Optimize descriptions for trigger-richness
- Fix validation errors (placeholders, XML, format issues)
- Refactor skills that are too small (<1000 tokens) or too large (>3500 tokens)
- Generate or fix slash commands
- Check Context7 integration format
- Prepare skills for publishing
- Need skill templates or patterns
- Convert documentation to skills
Core Principles
Auto-Activation: 5+ action verbs, 10+ keywords, "Use when" triggers, parenthetical grouping, task-centric framing
Progressive Loading: L1 (frontmatter ~100 tokens) → L2 (SKILL.md 1000-2000 tokens) → L3 (references/ unlimited)
Token Targets: Sweet spot 1000-2000 tokens; warn <500 or >3500
Validation + Grading: 34 checks + 100-point rubric; grade calculated first, used as validation input
Run: ./scripts/validate-skill.sh path/to/skill
Validation Overview
34 checks across 3 tiers:
- 🔴 Errors (9): Must fix to publish
- 🟡 Warnings (17): Should fix for effectiveness
- 🟢 Suggestions (8): Polish & best practices
See references/validation-guide.md for complete details.
Grading Overview
100-point rubric: Description Quality (35%), Structure (25%), Content (20%), Technical (15%), Compliance (5%)
Grades: A (90-100), B (80-89), C (70-79), D (60-69), F (0-59)
See references/grading-rubric.md for scoring details.
Skill Patterns
Workflow Skills: Multi-step processes with phases (planning, deployment) Reference Skills: Domain knowledge with quick references (testing, security) Tool Skills: Specific operations with clear input/output (validation, formatting)
See references/creation-workflow.md for pattern details.
Quick Reference
| Element | Rule | Example |
|---|---|---|
| Name | ^[a-z0-9-]+$ (max 64) |
spring-boot-core |
| Description | 50-1024 chars, 5+ verbs, 10+ keywords | See frontmatter above |
| Tokens | 1000-2000 ideal, >500 min, <3500 warn | ~200-400 lines |
| Sections | What I Do, When to Use Me, Quick Start | Required |
| Resources | assets/, references/, scripts/ | Optional |
| Command | {name}.md or ak-{name}.md |
Matches skill name |
| Grade | A-F scale (100 points) | Target: B+ (85+) minimum |
Examples
Create new skill:
User: "Create a skill for API validation"
→ 8-step workflow → Grade B+ (87/100)
Validate existing skill:
./scripts/validate-skill.sh .opencode/skill/my-skill
→ 0 errors, Grade A (92/100)
Optimize description:
User: "Make skill more discoverable"
→ Add verbs + keywords → Grade improves C (75) to A (93)
See references/creation-workflow.md for detailed examples.
Common Errors
| Error | Solution |
|---|---|
| "Invalid name format" | Use lowercase, hyphens only |
| "Description too short" | Add action verbs + keywords |
| "SKILL.md too large" | Move content to references/ |
| "No slash command" | Create command file |
See references/validation-guide.md for complete error catalog.
References
Load detailed guidance as needed:
| Reference | Use When | Content |
|---|---|---|
| creation-workflow.md | Creating new skills | 8-step process, patterns, examples |
| validation-guide.md | Understanding validation | 34 checks explained, fixes |
| optimization-patterns.md | Improving descriptions | Trigger-rich patterns, testing |
| grading-rubric.md | Understanding grades | 100-point scoring breakdown |
Related Skills
markdown-editor- For creating and editing SKILL.md markdown filesgithub-actions- For CI/CD integration of validationgithub-project-manager- For tracking skill development tasks
Next Steps
Complete workflows & resources:
- references/creation-workflow.md - 8-step creation process
- references/validation-guide.md - 34 validation rules
- references/optimization-patterns.md - Trigger patterns + testing
- references/grading-rubric.md - 100-point scoring system
Templates:
- assets/skill-template.md - Ready-to-use starter template
- assets/command-template.md - Slash command template
Automation:
./scripts/validate-skill.sh- Validation + grading in one command