name: skill-builder description: Comprehensive guide for building Agent Skills according to agentskills.io specification. Use when developers need to create, structure, or validate skills that follow the Agent Skills standard format and best practices. allowed-tools: Write, Read

Skill Builder - Agent Skills Specification Guide

Build Agent Skills that follow the agentskills.io specification and industry best practices.

Purpose

This skill helps developers create professional, standardized Agent Skills that:

1. Follow Agent Skills Specification - Comply with agentskills.io standards
2. Provide Clear Structure - Organized, discoverable, and maintainable
3. Enable AI Agent Integration - Optimized for AI coding agents (Cursor, Copilot, etc.)
4. Support Team Collaboration - Shareable, version-controlled, and documented

Perfect for developers building skills for AI coding agents, teams standardizing workflows, and organizations creating skill libraries.

📋 Agent Skills Specification Overview

Core Principles

The Agent Skills specification (agentskills.io) defines standards for:

1. Skill Structure - File organization and naming conventions
2. Metadata Format - Frontmatter with required fields
3. Content Guidelines - Documentation and instruction patterns
4. Discovery Mechanism - How AI agents find and load skills
5. Interoperability - Cross-platform compatibility

Required Components

Every Agent Skill must include:

• SKILL.md - Main skill file with frontmatter metadata
• Structured Content - Clear instructions and examples
• Proper Metadata - Name, description, version, license
• Documentation - Usage examples and best practices

🏗️ Skill Structure Standards

Directory Layout

skill-name/
├── SKILL.md              # Main skill file (required)
├── README.md             # Documentation (recommended)
├── EXAMPLES.md           # Usage examples (recommended)
├── references/           # Supporting materials (optional)
│   ├── api-docs.md
│   ├── best-practices.md
│   └── troubleshooting.md
├── assets/              # Images, diagrams (optional)
│   ├── architecture.png
│   └── workflow.svg
└── scripts/             # Helper scripts (optional)
    ├── setup.sh
    └── validate.py

File Naming Conventions

• SKILL.md - Always uppercase, main entry point
• README.md - Uppercase, general documentation
• EXAMPLES.md - Uppercase, usage examples
• references/ - Lowercase directory, supporting docs
• assets/ - Lowercase directory, media files
• scripts/ - Lowercase directory, executable files

📝 SKILL.md Format Specification

Required Frontmatter

---
name: skill-name                    # Required: kebab-case identifier
description: Brief skill description # Required: 1-2 sentences
version: 1.0.0                     # Recommended: semantic versioning
license: MIT                       # Recommended: open source license
author: Your Name                  # Optional: skill creator
tags: [tag1, tag2, tag3]          # Optional: searchable keywords
allowed-tools: [Write, Read]       # Optional: tool permissions
dependencies: [other-skill]        # Optional: skill dependencies
---

Content Structure Template

# Skill Name

Brief description of what this skill does and when to use it.

## Purpose

Detailed explanation of:
- What problems this skill solves
- When developers should use it
- What outcomes it provides
- Who benefits from it

## Core Concepts

### Concept 1: [Name]
Explanation of key concept with examples.

### Concept 2: [Name]
Another important concept.

## Instructions

### Phase 1: [Phase Name]

**Objective**: Clear goal for this phase

**Steps**:
1. Step 1 with specific actions
2. Step 2 with expected outcomes
3. Step 3 with validation criteria

**Expected Output**:
- Deliverable 1
- Deliverable 2

### Phase 2: [Phase Name]

[Continue with additional phases...]

## Examples

### Example 1: [Scenario Name]

**Input**:

User request or scenario description

**Process**:
1. How the skill handles this input
2. What steps are taken
3. What decisions are made

**Output**:

Expected result or deliverable

### Example 2: [Scenario Name]

[Additional examples...]

## Best Practices

### Do's
- ✅ Specific guideline with rationale
- ✅ Another best practice
- ✅ Quality standard

### Don'ts
- ❌ What to avoid and why
- ❌ Common mistakes
- ❌ Anti-patterns

## Quality Standards

Define what constitutes success:
- Measurable criteria
- Quality checkpoints
- Validation methods

## Troubleshooting

### Common Issue 1
**Problem**: Description of issue
**Cause**: Why it happens
**Solution**: How to fix it

### Common Issue 2
[Additional troubleshooting...]

## References

- [Link 1](url) - Description
- [Link 2](url) - Description
- [Documentation](url) - Official docs

🎯 Skill Development Process

Phase 1: Planning & Research

Objective: Define skill scope and requirements

Steps:

1. Identify the Problem

   • What specific challenge does this skill address?
   • Who is the target user (developers, PMs, designers)?
   • What existing solutions are inadequate?

2. Research Existing Skills

   • Check if similar skills already exist
   • Identify gaps or improvement opportunities
   • Study successful skill patterns

3. Define Scope

   • What will the skill do (and not do)?
   • What are the input/output formats?
   • What tools or dependencies are needed?

Expected Output:

• Skill requirements document
• Scope definition
• Success criteria

Phase 2: Structure Design

Objective: Create skill architecture and file structure

Steps:

1. Choose Skill Type

   • Process Skill: Step-by-step workflows
   • Knowledge Skill: Information and best practices
   • Template Skill: Code/document generation
   • Analysis Skill: Evaluation and assessment

2. Design File Structure

   • Determine required files (SKILL.md always required)
   • Plan supporting documentation
   • Identify assets and references needed

3. Plan Content Organization

   • Break down into logical phases/sections
   • Define instruction hierarchy
   • Plan examples and use cases

Expected Output:

• Directory structure plan
• Content outline
• File organization strategy

Phase 3: Content Creation

Objective: Write comprehensive skill content

Steps:

1. Write Frontmatter

   • Choose descriptive name (kebab-case)
   • Write clear, concise description
   • Set appropriate metadata

2. Create Core Instructions

   • Write clear, actionable steps
   • Include decision points and branching logic
   • Provide specific examples

3. Add Supporting Content

   • Create usage examples
   • Document best practices
   • Add troubleshooting guide

Expected Output:

• Complete SKILL.md file
• Supporting documentation
• Usage examples

Phase 4: Testing & Validation

Objective: Ensure skill works correctly and meets standards

Steps:

1. Test with AI Agents

   • Test with Cursor IDE
   • Test with GitHub Copilot
   • Test with other supported agents

2. Validate Against Specification

   • Check frontmatter format
   • Verify file structure
   • Ensure content quality

3. User Testing

   • Test with target users
   • Gather feedback on clarity
   • Iterate based on results

Expected Output:

• Tested, working skill
• Validation report
• User feedback incorporated

🔧 Skill Types & Patterns

Process Skills

Purpose: Guide users through step-by-step workflows

Structure Pattern:

## Phase 1: [Name]
### Objective
### Steps
### Expected Output
### Quality Checks

## Phase 2: [Name]
[Continue pattern...]

Examples: Code review, deployment, testing workflows

Knowledge Skills

Purpose: Provide information, best practices, and guidelines

Structure Pattern:

## Core Concepts
### Concept 1
### Concept 2

## Best Practices
### Category 1
### Category 2

## Reference Materials

Examples: Security guidelines, architecture patterns, coding standards

Template Skills

Purpose: Generate code, documents, or configurations

Structure Pattern:

## Template Types
### Template 1: [Name]
#### When to Use
#### Template Content
#### Customization Options

### Template 2: [Name]
[Continue pattern...]

Examples: Project scaffolding, document generation, configuration creation

Analysis Skills

Purpose: Evaluate, assess, or analyze existing work

Structure Pattern:

## Analysis Framework
### Criteria 1
### Criteria 2

## Evaluation Process
### Step 1: Data Collection
### Step 2: Analysis
### Step 3: Reporting

## Output Format

Examples: Code quality assessment, performance analysis, security audits

📊 Quality Standards & Validation

Content Quality Checklist

• ✅ Clear Purpose: Skill purpose is immediately obvious
• ✅ Actionable Instructions: Steps are specific and executable
• ✅ Complete Examples: Real-world usage scenarios included
• ✅ Error Handling: Common issues and solutions documented
• ✅ Consistent Format: Follows specification standards
• ✅ Proper Metadata: All required frontmatter fields present
• ✅ Logical Flow: Information organized intuitively
• ✅ Measurable Outcomes: Success criteria clearly defined

Technical Validation

# Validate frontmatter format
grep -A 10 "^---$" SKILL.md | head -20

# Check required fields
grep -E "^(name|description):" SKILL.md

# Verify file structure
ls -la skill-name/

# Test with AI agent
# (Manual testing required)

User Experience Standards

• Discoverability: Easy to find and understand purpose
• Usability: Clear instructions that work on first try
• Reliability: Consistent results across different scenarios
• Maintainability: Easy to update and extend
• Accessibility: Works for users with different skill levels

🚀 Deployment & Distribution

Local Installation

# Copy to skills directory
cp -r skill-name/ .cursor/skills/
# or
cp -r skill-name/ .claude/skills/
# or
cp -r skill-name/ .kiro/steering/skills/

Git-Based Distribution

# Add to repository
git add .cursor/skills/skill-name/
git commit -m "Add skill-name skill"
git push origin main

# Team members get automatically
git pull

Package Distribution

// package.json for npm distribution
{
  "name": "@company/agent-skills",
  "version": "1.0.0",
  "description": "Company agent skills collection",
  "files": ["skills/"],
  "keywords": ["agent-skills", "ai", "automation"]
}

💡 Advanced Patterns

Skill Composition

Combining Multiple Skills:

---
name: full-stack-development
dependencies: [frontend-development, backend-development, testing]
---

Skill Inheritance:

---
name: react-testing
extends: testing
specialization: react-components
---

Dynamic Content

Conditional Instructions:

## Framework-Specific Steps

### If using React:
1. Install React Testing Library
2. Create component tests

### If using Vue:
1. Install Vue Test Utils
2. Create component tests

Variable Substitution:

## Setup for {{FRAMEWORK}}

Replace {{FRAMEWORK}} with your chosen framework:
- React
- Vue
- Angular

Integration Patterns

Tool Integration:

---
allowed-tools: [Write, Read, Execute, Search]
tool-configs:
  linter: eslint
  formatter: prettier
  bundler: webpack
---

External Dependencies:

---
dependencies:
  skills: [base-development]
  tools: [node, npm, git]
  services: [github, vercel]
---

🧪 Testing Strategies

Manual Testing

1. Clarity Test: Can a new user follow instructions successfully?
2. Completeness Test: Does the skill handle all stated use cases?
3. Error Test: How does it handle edge cases and errors?
4. Integration Test: Does it work with target AI agents?

Automated Testing

# Example validation script
def validate_skill(skill_path):
    # Check file structure
    assert os.path.exists(f"{skill_path}/SKILL.md")
    
    # Validate frontmatter
    with open(f"{skill_path}/SKILL.md") as f:
        content = f.read()
        assert "name:" in content
        assert "description:" in content
    
    # Check content quality
    assert len(content) > 1000  # Minimum content length
    assert "## Purpose" in content
    assert "## Instructions" in content

User Acceptance Testing

## Test Scenarios

### Scenario 1: New Developer
- **User**: Junior developer, first time using skills
- **Task**: Follow skill instructions to complete workflow
- **Success**: Completes task without external help

### Scenario 2: Experienced Developer
- **User**: Senior developer, familiar with domain
- **Task**: Use skill for complex scenario
- **Success**: Achieves better results than manual approach

### Scenario 3: AI Agent Integration
- **User**: AI coding agent (Cursor, Copilot)
- **Task**: Parse and execute skill instructions
- **Success**: Produces expected output automatically

📚 Examples & Templates

Example 1: Simple Process Skill

---
name: code-review-checklist
description: Systematic code review process with quality gates and best practices
version: 1.0.0
license: MIT
tags: [code-review, quality, process]
---

# Code Review Checklist

Systematic approach to conducting thorough, constructive code reviews.

## Purpose

This skill provides a structured checklist for code reviews that ensures:
- Code quality and maintainability
- Security and performance considerations
- Team knowledge sharing
- Consistent review standards

## Instructions

### Phase 1: Initial Assessment

**Objective**: Quick overview and scope understanding

**Steps**:
1. Read the PR description and linked issues
2. Understand the business context and requirements
3. Identify the scope and complexity of changes
4. Check if automated tests pass

**Expected Output**:
- Understanding of what the code should accomplish
- Assessment of review complexity (simple/medium/complex)

### Phase 2: Code Quality Review

**Objective**: Evaluate code structure and implementation

**Checklist**:
- [ ] Code follows team style guidelines
- [ ] Functions are single-purpose and well-named
- [ ] Complex logic is commented and explained
- [ ] No obvious bugs or logic errors
- [ ] Error handling is appropriate
- [ ] No code duplication (DRY principle)

[Continue with additional phases...]

Example 2: Knowledge Skill Template

---
name: api-design-principles
description: REST API design guidelines and best practices for scalable, maintainable APIs
version: 1.0.0
license: MIT
tags: [api, rest, design, backend]
---

# API Design Principles

Comprehensive guidelines for designing REST APIs that are intuitive, scalable, and maintainable.

## Core Principles

### 1. Resource-Oriented Design
APIs should model business entities as resources with clear hierarchies.

**Good**:

GET /users/123/orders/456 POST /users/123/orders

**Bad**:

GET /getUserOrder?userId=123&orderId=456 POST /createOrderForUser

### 2. HTTP Methods Semantics
Use HTTP methods according to their intended semantics.

| Method | Purpose | Idempotent | Safe |
|--------|---------|------------|------|
| GET | Retrieve resource | Yes | Yes |
| POST | Create resource | No | No |
| PUT | Update/replace resource | Yes | No |
| PATCH | Partial update | No | No |
| DELETE | Remove resource | Yes | No |

[Continue with additional principles...]

🔍 Troubleshooting Guide

Common Issues

Issue 1: Skill Not Recognized by AI Agent

Symptoms:

• Agent doesn't activate skill automatically
• Skill not found in available skills list

Causes:

• Incorrect file location
• Missing or malformed frontmatter
• Agent not configured to scan skills directory

Solutions:

1. Verify file is in correct location (.cursor/skills/, .claude/skills/, etc.)
2. Check frontmatter syntax and required fields
3. Restart AI agent to refresh skill cache
4. Explicitly mention skill name in prompt

Issue 2: Instructions Too Vague

Symptoms:

• Users can't follow instructions successfully
• AI agent produces inconsistent results
• Frequent clarification requests

Causes:

• Steps lack specific details
• Missing examples or context
• Assumptions about user knowledge

Solutions:

1. Add specific, actionable steps
2. Include concrete examples
3. Define technical terms and concepts
4. Test with users unfamiliar with the domain

Issue 3: Skill Too Complex

Symptoms:

• Users abandon skill partway through
• Instructions feel overwhelming
• Poor adoption rates

Causes:

• Trying to solve too many problems
• Lack of clear phases or milestones
• Missing quick-start options

Solutions:

1. Break into smaller, focused skills
2. Add progressive complexity levels
3. Provide quick-start and comprehensive paths
4. Include progress indicators

📈 Skill Metrics & Analytics

Usage Metrics

Track skill effectiveness:

• Activation Rate: How often is the skill used?
• Completion Rate: Do users finish the workflow?
• Success Rate: Do users achieve intended outcomes?
• Time to Value: How quickly do users see benefits?

Quality Metrics

Measure skill quality:

• Clarity Score: User feedback on instruction clarity
• Completeness Score: Coverage of use cases
• Accuracy Score: Correctness of information
• Maintainability Score: Ease of updates and changes

Collection Methods

## Feedback Collection

### In-Skill Feedback
Add feedback prompts in skill content:
"Was this step clear? (Y/N)"
"Did you encounter any issues? (describe)"

### Post-Usage Survey
"Rate this skill's usefulness (1-5)"
"What would you improve?"
"Would you recommend to others?"

### Analytics Integration
Track usage patterns:
- Which sections are accessed most?
- Where do users typically stop?
- What errors are most common?

🎯 Success Patterns

High-Impact Skills

Characteristics of successful skills:

• Solve Real Problems: Address actual pain points
• Save Significant Time: Provide clear efficiency gains
• Reduce Errors: Prevent common mistakes
• Enable Consistency: Standardize approaches
• Facilitate Learning: Help users improve skills

Adoption Strategies

• Start Small: Begin with simple, high-value skills
• Get Early Feedback: Test with small group first
• Iterate Quickly: Improve based on usage data
• Provide Training: Help users understand benefits
• Measure Impact: Track and communicate value

Community Building

• Share Openly: Contribute to skill libraries
• Document Learnings: Share what works and what doesn't
• Collaborate: Work with others on skill development
• Standardize: Follow and promote specifications
• Evangelize: Help others adopt skill-based workflows

📋 Skill Builder Checklist

Planning Phase

• Problem clearly defined and scoped
• Target users identified
• Success criteria established
• Existing solutions researched
• Skill type determined (process/knowledge/template/analysis)

Development Phase

• File structure planned and created
• Frontmatter completed with all required fields
• Core instructions written and tested
• Examples created and validated
• Best practices documented
• Troubleshooting guide included

Quality Assurance Phase

• Content reviewed for clarity and completeness
• Instructions tested by target users
• AI agent compatibility verified
• Specification compliance checked
• Performance and usability validated

Deployment Phase

• Skill installed in target environment
• Documentation updated
• Team training provided (if applicable)
• Usage metrics collection set up
• Feedback mechanisms established

Maintenance Phase

• Regular usage review scheduled
• Update process defined
• Version control strategy implemented
• Community feedback incorporated
• Continuous improvement plan active

🆘 Getting Help

Resources

• Agent Skills Specification: https://agentskills.io/specification
• Community Forums: Platform-specific communities
• Example Skills: Study existing high-quality skills
• Documentation: AI agent documentation for skill integration

Support Channels

• GitHub Issues: For specification questions
• Community Discord: Real-time help and discussion
• Stack Overflow: Technical implementation questions
• Documentation: Official guides and tutorials

Contributing

• Report Issues: Help improve the specification
• Share Skills: Contribute to community libraries
• Provide Feedback: Help refine best practices
• Write Documentation: Improve guides and examples

📊 Version History

• v1.0.0 (2025-12-22): Initial release with comprehensive skill building guide
• v1.1.0 (TBD): Enhanced templates and validation tools
• v1.2.0 (TBD): Advanced patterns and integration examples

🎉 Next Steps

1. Study the Specification: Read agentskills.io thoroughly
2. Analyze Existing Skills: Learn from successful examples
3. Start Small: Create a simple skill for immediate need
4. Test Thoroughly: Validate with real users and AI agents
5. Iterate and Improve: Refine based on feedback and usage
6. Share and Collaborate: Contribute to the community

Remember: Great skills solve real problems, provide clear value, and make developers more productive. Focus on user needs, follow standards, and iterate based on feedback.