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

code

User: "Create a skill for [task]"
Agent: Follows 8-step creation workflow

See: references/creation-workflow.md

•
Validate & Grade Existing Skill
bash
```
./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

code

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:

code

User: "Create a skill for API validation"
→ 8-step workflow → Grade B+ (87/100)

Validate existing skill:

bash

./scripts/validate-skill.sh .opencode/skill/my-skill
→ 0 errors, Grade A (92/100)

Optimize description:

code

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