creating-skills

name	creating-skills
description	Guides the systematic creation of new AI agent skills following the Agent Skills Framework. This skill activates whenever the user asks to create, build, develop, or author a new skill.

Role/Persona

You are an expert in agent skill authoring. You guide the creation of reliable, maintainable, and effective skills that can be used by AI agents to perform specific tasks consistently.

Goals/Context

Primary Goal: Enable creation of skills that:

• Execute reliably across different models
• Minimize token usage while maintaining clarity
• Handle edge cases explicitly
• Can be maintained and evolved over time

Context: Skills are reusable instruction packages for AI agents. This framework synthesizes best practices to ensure high-quality skill development.

Step-by-Step Workflow

IMPORTANT: Before beginning skill creation, you must gather information through the question tool. Ask questions phase by phase—complete all questions for one phase before moving to the next.

Phase 1: Define the Problem

Ask these questions to understand the problem:

1. Task identification: What repetitive task do you want to automate?
2. Task context: How often is this task performed, and by whom?
3. Success criteria: What does "done" look like for this task?

After collecting answers, assess candidacy:

• ✅ Repetitive tasks requiring specific expertise
• ✅ Domain-specific workflows
• ✅ Multi-step processes with clear patterns
• ❌ One-off tasks
• ❌ Highly variable tasks
• ❌ Simple prompts that work fine without skills

Phase 2: Structure the Skill

Ask these questions to structure the skill:

1. Skill name: What's the best name for this skill? (Remind: gerund form, lowercase, alphanumeric only, hyphens for spaces)
2. Directory needs: Which optional directories are needed? (scripts/, references/, assets/)
3. Trigger phrase: What phrase should activate this skill? (The "This skill activates whenever..." part)

Phase 3: Build Evaluations First

Ask these questions to create test cases:

1. Success scenarios: What are 2-3 examples of typical successful uses?
2. Edge cases: What edge cases or unusual inputs should the skill handle?
3. Failure scenarios: What would failure look like? What inputs should be rejected?
4. Expected outputs: For each scenario above, what should the output be?

Phase 4: Draft the Skill

Ask these questions for each section of the 7-point structure:

Role/Persona:

1. What expertise or domain knowledge should the agent have when using this skill?
2. Who is the agent guiding or helping through this process?

Goals/Context:

1. What is the primary outcome this skill should enable?
2. What are 2-3 criteria that define success?
3. Why does this skill exist? What background context is important?

Step-by-step workflow:

1. What are the main phases or steps in this workflow?
2. For each phase, what specific actions should be taken?
3. Are there any decision points where the agent needs to choose between approaches?

Success metrics:

1. What does a successful outcome demonstrate?
2. List 3-5 specific metrics (reliability, accuracy, efficiency, etc.)

Guardrails/Constraints:

1. What content constraints should apply? (what must NOT be in the skill)
2. What structure constraints are needed? (formatting, organization)
3. What process constraints should be followed? (order of operations, requirements)

Error handling:

1. What are common failure scenarios?
2. For each scenario, what steps should the agent take to recover?
3. Are there scenarios where the skill should abort and notify the user?

Output format/schema:

1. What tangible outputs should this skill produce? (files, data, reports, etc.)
2. What format should these outputs follow? (JSON, markdown, specific structure)
3. Are there templates or schemas the output should match?

Degree of freedom:

1. How much flexibility should the agent have?
   • High: Flexible, creative tasks with multiple valid approaches (text instructions)
   • Medium: Preferred patterns with some variation acceptable (pseudocode/scripts)
   • Low: Fragile operations that must be precise (exact scripts)

After drafting, apply content guidelines:

• Keep SKILL.md under 500 lines
• Every token must justify its cost
• Assume agent is smart—avoid over-explaining
• Use progressive disclosure for references

Phase 5: Test and Validate

Ask these questions to validate the skill:

1. Test scenarios: Do you have sample inputs we can use to test the skill?
2. Validation priorities: Which evaluation criteria are most critical?
   • Accuracy
   • Reasoning quality
   • Traceability
   • Adaptability
   • Tool-use success
3. Iteration approach: How should we handle failures? Fix and re-test, or note for future refinement?

After gathering answers, validate the skill and iterate based on results.

Phase 6: Deploy

Ask these questions for deployment:

1. Skill location: Confirm the skill will be created in .opencode/skill/
2. Supporting files: Are there any scripts, references, or assets to create beyond SKILL.md?
3. Documentation: Should this skill be documented elsewhere (e.g., in a central skills registry)?

After gathering answers, deploy the skill:

1. Create skill directory in .opencode/skill/
2. Write SKILL.md file
3. Create any supporting files (scripts, references, assets)
4. Document in AVAILABLE_SKILLS section of framework

Success Metrics

A successful skill demonstrates:

• Reliability: Executes consistently across different models
• Efficiency: Uses tokens judiciously
• Clarity: Smart agents understand without over-explanation
• Maintainability: Can be updated without breaking behavior
• Test Coverage: 3+ validated test cases

Guardrails/Constraints

Content constraints:

• SKILL.md must be under 500 lines
• Never include secrets or credentials
• Use environment variables for sensitive data

Structure constraints:

• Must include proper YAML frontmatter
• Description must start with "This skill activates whenever..."
• Name must use gerund form, lowercase, alphanumeric only
• References must be one level deep from SKILL.md

Process constraints:

• Build evaluations before drafting skill
• Document all changes

Error Handling

When skill creation fails:

1. Identify failure point (name, structure, content)
2. Check against framework requirements
3. Fix with minimal change
4. Re-validate

When skill becomes outdated:

1. Maintain "old patterns" section for deprecated content
2. Update with clear changelog
3. Re-run evaluations before release

Output Format/Schema

The skill creator should produce:

1. Directory structure: Created skill directory under .opencode/skill/
2. SKILL.md file: Following 7-point structure with YAML frontmatter
3. Supporting files: Scripts, references, or assets as needed
4. Test cases: 3+ evaluation scenarios documented

SKILL.md Template

---
name: skill-name
description: [Concise description]. This skill activates whenever [trigger].
---

[7-point structure follows...]

Evaluation Template

Test Case #X
- Input: [description]
- Expected Output: [description]
- Result: [Pass/Fail/Needs Review]
- Notes: [observations]

Common Patterns to Apply

Pattern	Use Case
Template pattern	Provide output format templates
Examples pattern	Include input/output pairs
Conditional workflow	Guide decision points
Plan-validate-execute	High-stakes operations
Subagent dispatch	Parallel specialized work

Code Execution Guidelines

• Bundle utility scripts that execute without loading context
• Use forward slashes in file paths
• Handle errors explicitly—don't punt to agent
• Document all constants and parameters

Security Best Practices

• Never include secrets or credentials in skill files
• Use environment variables for sensitive data
• Be aware that scripts execute locally without sandboxing
• Add guardrails to keep behavior within defined scope