# skill-builder

> Comprehensive guide for creating effective Agent Skills that extend AI agent capabilities with specialized knowledge and workflows. Use when creating new skills, validating existing skills, packaging skills for distribution, or learning skill design best practices. Supports initialization, validation, packaging, and iteration workflows.

- Author: Markus Heimbach
- Repository: esukram/skill-builder
- Version: 20260125130224
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/esukram/skill-builder
- Web: https://mule.run/skillshub/@@esukram/skill-builder~skill-builder:20260125130224

---

---
name: skill-builder
description: Comprehensive guide for creating effective Agent Skills that extend AI agent capabilities with specialized knowledge and workflows. Use when creating new skills, validating existing skills, packaging skills for distribution, or learning skill design best practices. Supports initialization, validation, packaging, and iteration workflows.
---

# Skill Builder

Create effective Agent Skills following the [Agent Skills specification](https://agentskills.io/specification).

## Quick Start

All commands run from **workspace root**.

### Create a New Skill

```bash
node .agent/skills/skill-builder/scripts/init-skill.js my-skill
```

Creates: `.agent/skills/my-skill/` with template files.

### Validate a Skill

```bash
node .agent/skills/skill-builder/scripts/validate-skill.js .agent/skills/my-skill
```

### Package a Skill

```bash
node .agent/skills/skill-builder/scripts/package-skill.js .agent/skills/my-skill
```

Creates: `my-skill.skill` (distributable zip file).

---

## What Are Skills?

Skills are modular packages that extend agent capabilities with:
- **Specialized workflows** - Multi-step procedures for specific domains
- **Tool integrations** - Instructions for file formats, APIs, services
- **Domain expertise** - Company knowledge, schemas, business logic
- **Bundled resources** - Scripts, references, assets for complex tasks

Think of skills as "onboarding guides" that transform a general-purpose agent into a specialized one.

---

## Skill Creation Process

### Step 1: Research and Understand

Before creating a skill, ensure you understand the domain by consulting external resources and gathering concrete examples.

**Research Best Practices:**
Consult the internet to find current best practices, expert opinions, and industry standards for the domain you are building a skill for. Do not rely solely on internal knowledge.
- Search for "best practices [domain]", "expert guide [domain]", or "standard workflow [domain]".
- Incorporate these findings into the skill's design.

**Gather Concrete Examples:**
Identify how the skill will be used:
- What tasks should trigger this skill?
- What would users say that should activate it?
- What are the expected inputs and outputs?

Example questions for an image-editor skill:
- "What functionality should it support? Editing, rotating, filters?"
- "Can you give examples of how this would be used?"
- "What edge cases should it handle?"

### Step 2: Plan Reusable Contents

Analyze examples to identify what to include:

| If you find yourself... | Include in skill... |
|------------------------|---------------------|
| Rewriting the same code | `scripts/` - executable scripts |
| Explaining the same concepts | `references/` - documentation |
| Using the same templates | `assets/` - template files |

Example: A PDF skill might include:
- `scripts/rotate_pdf.js` - rotation logic rewritten each time
- `references/forms.md` - form filling documentation
- `assets/template.pdf` - base template

### Step 3: Initialize the Skill

Run the initialization script:

```bash
node .agent/skills/skill-builder/scripts/init-skill.js <skill-name>
```

This creates a skill directory with:
- `SKILL.md` - template with TODO placeholders
- `scripts/` - example script
- `references/` - example reference doc
- `assets/` - placeholder

### Step 4: Edit the Skill

#### 4.1 Complete the Frontmatter

```yaml
---
name: my-skill
description: Clear description of what this skill does AND when to use it. Include trigger scenarios.
---
```

The `description` is critical - it determines when the skill activates.

**Good description:**
```yaml
description: Extracts text and tables from PDF files, fills PDF forms, merges documents. Use when working with PDFs or when user mentions document extraction, form filling, or PDF manipulation.
```

**Poor description:**
```yaml
description: Helps with PDFs.
```

#### 4.2 Write Instructions

Choose a structure based on skill type:

| Skill Type | Structure | Example |
|-----------|-----------|---------|
| Sequential process | Workflow-based | PDF processing: analyze → extract → transform |
| Tool collection | Task-based | Image editor: resize, crop, rotate, filter |
| Standards/guidelines | Reference-based | Brand guidelines: colors, typography, voice |
| Integrated system | Capabilities-based | CRM integration: contacts, deals, reports |

See [references/workflow-patterns.md](references/workflow-patterns.md) for detailed patterns.

#### 4.3 Add Resources

**Scripts** (`scripts/`):
- Executable code for repeated operations
- Test scripts before including them
- Make executable: `chmod +x script.js`

**References** (`references/`):
- Detailed documentation loaded on demand
- Keep files focused (<300 lines each)
- Link from SKILL.md: `See [references/api.md](references/api.md)`

**Assets** (`assets/`):
- Templates, images, fonts for output
- Not loaded into context, used in results

Delete any unneeded example files.

### Step 5: Validate the Skill

```bash
node .agent/skills/skill-builder/scripts/validate-skill.js .agent/skills/my-skill
```

Fix any errors before proceeding. Validation checks:
- SKILL.md exists with valid frontmatter
- Name follows spec (lowercase, hyphens, 1-64 chars)
- Description present (1-1024 chars, no angle brackets)
- Name matches directory name

### Step 6: Package and Iterate

Package for distribution:

```bash
node .agent/skills/skill-builder/scripts/package-skill.js .agent/skills/my-skill
```

Then iterate based on real usage:
1. Use the skill on real tasks
2. Notice struggles or inefficiencies
3. Update SKILL.md or resources
4. Revalidate and repackage

---

## Core Principles

### Concise is Key

The context window is shared. Only add what the agent doesn't already know.

- Challenge each piece: "Does this justify its token cost?"
- Prefer concise examples over verbose explanations
- Keep SKILL.md under 500 lines

### Set Appropriate Degrees of Freedom

Match specificity to task requirements:

| Freedom Level | When to Use | Example |
|--------------|-------------|---------|
| High (guidance) | Multiple valid approaches | Creative writing |
| Medium (patterns) | Preferred approach with variation | Code generation |
| Low (scripts) | Fragile, must be exact | File format manipulation |

### Progressive Disclosure

Structure for efficient context usage:

1. **Metadata** (~100 tokens) - Always loaded
2. **SKILL.md body** (<5000 tokens) - When skill activates
3. **Resources** (unlimited) - On demand

See [references/progressive-disclosure.md](references/progressive-disclosure.md) for splitting patterns.

---

## Skill Anatomy

```
skill-name/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Optional: executable code
├── references/           # Optional: detailed documentation
└── assets/               # Optional: templates, images, etc.
```

### SKILL.md Structure

```yaml
---
name: skill-name          # Required: lowercase, hyphens, 1-64 chars
description: What and when  # Required: 1-1024 chars
license: Apache-2.0       # Optional
compatibility: Requires X  # Optional: environment needs
metadata:                 # Optional: arbitrary key-value
  author: org
  version: "1.0"
---

# Skill Title

[Instructions for using the skill]
```

---

## Design Pattern References

Load these for detailed guidance:

- **Workflow patterns**: [references/workflow-patterns.md](references/workflow-patterns.md)
  - Sequential, conditional, iterative workflows
  - Error handling patterns

- **Output patterns**: [references/output-patterns.md](references/output-patterns.md)
  - Templates (strict vs flexible)
  - Examples and quality checklists

- **Progressive disclosure**: [references/progressive-disclosure.md](references/progressive-disclosure.md)
  - When to split content
  - Organization patterns

- **Spec reference**: [references/spec-reference.md](references/spec-reference.md)
  - Full field requirements
  - Validation rules

---

## What NOT to Include

Skills should only contain what agents need. Do NOT create:
- README.md (in the skill itself)
- CHANGELOG.md
- INSTALLATION_GUIDE.md
- User-facing documentation
- Setup/testing procedures

These add clutter. The skill is for agents, not humans.