skill-helper by jander99/skills

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 workflow

See: references/creation-workflow.md

Validate & Grade Existing Skill
```
./scripts/validate-skill.sh path/to/skill
# Returns: 34 validation checks + 100-point grade
```
See: references/validation-guide.md

Rubric: references/grading-rubric.md

Optimize for Discoverability

User: "Make [skill-name] more discoverable"
Agent: Analyzes description, adds verbs/keywords

See: references/optimization-patterns.md

What I Do

Create new skills from scratch with templates
Validate skills against 33-check system (8 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

33 checks across 3 tiers:

🔴 Errors (8): 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 files
github-actions - For CI/CD integration of validation
github-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