# Skill Maker

> Create complex, portable agent skills that embed all prompts, scripts, tools, and environment automation. Use when user wants to "create a skill", "make a skill", "build a skill", "write a skill", or "design a skill". Supports multi-agent portability (Claude Code, Codex, Hermes, OpenCode, WorkBuddy). Do NOT use for installing or searching existing skills (use find-skills or marketplace-skill-installer instead).

- Skill: `loongyowl/skill-maker` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add loongyowl/skill-maker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/loongyowl/skill-maker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: loongyowl (https://skillmd.com/u/loongyowl)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/loongyowl/skill-maker

---


# Skill Maker

Create production-grade, portable agent skills that embed all prompts, scripts, tools, and environment automation into a self-contained package. Compatible with any AI agent that supports the agent-skills specification (Claude Code, Codex, Hermes, OpenCode, WorkBuddy, Cursor, Windsurf, etc.).

## Core Principles

| Principle | Meaning |
|-----------|---------|
| **Self-Contained** | Every skill bundles everything it needs — no external dependencies beyond the target agent |
| **Progressive Disclosure** | Metadata first → SKILL.md body → Bundled resources — loaded only as needed |
| **Portable** | Works across agents with zero modification; avoid agent-specific features |
| **Concrete** | Must include "Use when" and "Do NOT use for" trigger phrases |
| **Token-Aware** | SKILL.md ≤ 500 lines; detailed docs in references/ |

## Skill Architecture

```
skill-name/                    # kebab-case, ≤64 chars
├── SKILL.md                   # 【REQUIRED】Main instruction file
├── scripts/                   # 【OPTIONAL】Executable code (Python/Bash/Node)
├── references/                # 【OPTIONAL】On-demand context docs
├── templates/                 # 【OPTIONAL】File templates (code, config, docs)
└── assets/                    # 【OPTIONAL】Output assets (fonts, images, boilerplate)
```

### Directory Purpose

| Directory | Intent | Loaded to Context? | Examples |
|-----------|--------|-------------------|----------|
| `SKILL.md` | Main instructions | Always (when triggered) | Workflows, decision trees, rules |
| `scripts/` | Executable automation | No (executed directly) | init tool, converter, validator |
| `references/` | Deep-dive documentation | On-demand | API specs, detailed guides, schemas |
| `templates/` | File blueprints | On-demand (read, then output) | SKILL.md template, config template |
| `assets/` | Output artifacts | No (copied into output) | Fonts, logos, starter projects |

## Workflow

Creating a skill follows this sequence. For simple skills (<200 line SKILL.md), Steps 2-4 can merge.

```
1. DISCOVER  →  2. DESIGN  →  3. INIT  →  4. AUTHOR  →  5. VALIDATE  →  6. PACKAGE
```

### Step 1: DISCOVER — Understand the Need

Ask the user and answer for yourself:

| Question | Why It Matters |
|----------|---------------|
| What problem does this skill solve? | Defines scope and prevents feature creep |
| When should the agent trigger this skill? | Drives the "Use when" phrases |
| When should the agent NOT use this skill? | Drives the "Do NOT use for" phrases |
| What does the agent need that it doesn't already know? | Only add missing context |
| What actions need to happen? | Determines scripts vs inline instructions |
| What reference material is needed? | Determines references/ content |
| Which agents will use this? | Determines portability constraints |

Record answers for Step 2.

### Step 2: DESIGN — Plan the Skill

Based on the DISCOVER answers, decide:

**Structure Pattern** (pick primary, mix as needed):

| Pattern | Best For | Example |
|---------|----------|---------|
| **Workflow** | Sequential processes with clear steps | PDF form filling: analyze → map → fill → verify |
| **Task-Based** | Collections of distinct operations | PDF toolkit: merge, split, extract, rotate |
| **Capabilities** | Integrated systems with multiple features | Design tool: prototyping, animation, review |
| **Reference** | Standards, guidelines, specifications | Brand guidelines: colors, typography, layout |

**Resource Planning:**

| If the skill needs... | Put it in... |
|----------------------|-------------|
| Executable tooling | `scripts/` — Python/Bash/Node scripts |
| Deep documentation | `references/` — Markdown docs |
| Output blueprints | `templates/` — Template files |
| Static assets | `assets/` — Fonts, images, boilerplate |

**Token Budget:**

| Component | Max Size |
|-----------|----------|
| SKILL.md | 500 lines |
| Description | 1024 chars |
| Name | 64 chars |
| Per reference file | No hard limit, but keep focused |

### Step 3: INIT — Scaffold the Skill

Use the init script to create the directory structure:

```bash
python scripts/init_skill.py <skill-name> --path <output-dir>
```

This creates:
- `SKILL.md` with frontmatter template and guidance
- `scripts/`, `references/`, `assets/` with placeholder files
- Ready-to-edit structure

**Manual alternative** (if script unavailable):

```bash
mkdir -p skill-name/{scripts,references,templates,assets}
```

Create `SKILL.md` using the template at `templates/SKILL.template.md`.

### Step 4: AUTHOR — Write the Skill

#### 4a. Frontmatter (YAML)

```yaml
---
name: my-skill                  # kebab-case, lowercase only, ≤64 chars
description: [What it does]. [Use when...]. [Do NOT use for...].  # ≤1024 chars
license: MIT                    # Or CC-BY-4.0 for content
metadata:
  version: 1.0.0
  author: github.com/username
---
```

**Description MUST include:**
1. What the skill does
2. "Use when" + trigger phrases in quotes
3. "Do NOT use for" + exclusion scenarios

**Description MUST NOT include:**
- Angle brackets `<` `>`
- Vague language without triggers

#### 4b. Body Structure

```markdown
# Skill Title

Brief overview (1-2 sentences).

## Core Principles / Rules

Critical constraints as bullet points or a table.

## Workflow / Process

Step-by-step flow. Use Mermaid for complex flows, ASCII for simple ones.

## Detailed Instructions

The main content — organized by the chosen pattern:

### For Workflow Pattern
## Step 1: [Name]
## Step 2: [Name]
...

### For Task-Based Pattern
## [Task Category 1]
### Operation A
### Operation B
## [Task Category 2]
...

### For Capabilities Pattern
## Core Capabilities
### 1. [Capability Name]
### 2. [Capability Name]
...

### For Reference Pattern
## [Topic 1]
### Guidelines
### Specifications
## [Topic 2]
...

## Scripts / Tools

Reference bundled scripts with usage examples.

## References

Link to bundled reference docs: `references/doc-name.md`
```

#### 4c. Writing Rules

| Rule | Explanation |
|------|-------------|
| **Assume agent intelligence** | Don't explain what the agent already knows |
| **Be concrete** | Use exact trigger phrases, not "when relevant" |
| **Prefer tables** | Tables are easier for agents to parse than prose |
| **Code blocks for commands** | All commands in fenced code blocks with language tag |
| **Avoid agent-specific features** | No Claude-only MCP, no Codex-only hooks |
| **Cross-reference scripts** | When mentioning a script, show the exact command |

### Step 5: VALIDATE — Check Quality

Run the validator:

```bash
python scripts/validate_skill.py <path/to/skill-folder>
```

**Validation checks:**
- SKILL.md exists
- Valid YAML frontmatter
- Required fields: `name`, `description`
- Name: kebab-case, ≤64 chars, no consecutive hyphens
- Description: ≤1024 chars, no angle brackets, includes "Use when"
- No unexpected frontmatter keys
- Directory structure is valid
- Scripts have proper shebangs
- No binary files (unless explicitly allowed)
- All referenced files exist

See `references/quality-checklist.md` for the full checklist.

### Step 6: PACKAGE — Distribute

```bash
python scripts/package_skill.py <path/to/skill-folder> [output-dir]
```

Creates a `.skill` file (ZIP format) for distribution.

## Cross-Agent Portability

Skills created by this tool work on any agent that follows the agent-skills spec. Key portability rules:

### Universal (Safe Everywhere)

| Pattern | Example |
|---------|---------|
| Markdown instructions | All agents parse Markdown |
| Shell commands in code blocks | `bash`, `python`, `node` blocks |
| Relative file references | `scripts/tool.py`, `references/guide.md` |
| Standard YAML frontmatter | `name`, `description`, `license`, `metadata` |

### Agent-Specific (Restricted)

| Pattern | Works On | Avoid If Targeting |
|---------|----------|-------------------|
| MCP tool calls | Claude Code, WorkBuddy | Codex, Hermes, OpenCode |
| Claude-specific XML | Claude Code | Everything else |
| Codex CLI flags | Codex | Everything else |
| OpenCode hooks | OpenCode | Everything else |

**Strategy**: If you need agent-specific behavior, create an agent-detection pattern or provide fallback instructions:

```markdown
## Script Execution

### Universal (all agents)
```bash
python scripts/helper.py --input data.json
```

### Claude Code / WorkBuddy
Use MCP integration if available; fall back to the universal script.

### Codex
Run directly: `codex run scripts/helper.py --input data.json`
```

See `references/cross-agent-guide.md` for full portability matrix.

## Environment Automation

### Python Environment

When a skill requires Python dependencies, embed setup in scripts:

```python
# scripts/setup.py
"""Self-contained environment setup."""
import subprocess, sys, venv, os
from pathlib import Path

VENV_DIR = Path(__file__).parent.parent / ".venv"

def ensure_venv():
    if VENV_DIR.exists():
        return VENV_DIR
    venv.create(VENV_DIR, with_pip=True)
    # Cross-platform pip path
    pip = VENV_DIR / "Scripts" / "pip.exe" if sys.platform == "win32" else VENV_DIR / "bin" / "pip"
    subprocess.check_call([str(pip), "install", "-r",
        str(Path(__file__).parent / "requirements.txt")])
    return VENV_DIR

if __name__ == "__main__":
    ensure_venv()
```

### Node.js Environment

```bash
# scripts/setup.sh
#!/bin/bash
SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
if [ ! -d "$SKILL_DIR/node_modules" ]; then
    cd "$SKILL_DIR" && npm install
fi
```

### Auto-Detection Pattern

Skills can auto-detect their environment and adapt:

```python
# scripts/env_detect.py
import os, sys

def detect_agent():
    """Detect which AI agent is running this skill."""
    if os.environ.get("CLAUDE_CODE"):
        return "claude-code"
    if os.environ.get("CODEX_CLI"):
        return "codex"
    # WorkBuddy detection via home directory
    if Path.home().joinpath(".workbuddy").exists():
        return "workbuddy"
    if os.environ.get("OPENCODE"):
        return "opencode"
    if os.environ.get("CURSOR_WORKSPACE_PATH"):
        return "cursor"
    return "generic"
```

## Scripts Reference

### init_skill.py

Initialize a new skill with proper directory structure and template SKILL.md.

```bash
python scripts/init_skill.py <skill-name> --path <output-dir>
```

### validate_skill.py

Validate a skill against the agent-skills specification.

```bash
python scripts/validate_skill.py <path/to/skill-folder>
```

### package_skill.py

Package a skill into a distributable `.skill` file (ZIP format).

```bash
python scripts/package_skill.py <path/to/skill-folder> [output-dir]
```

## Templates Reference

### SKILL.template.md

Complete SKILL.md template with all required sections and inline guidance. Copy and edit, or use `init_skill.py`.

### script.template.py

Python script template with proper structure, argument parsing, and error handling.

### reference.template.md

Reference document template for `references/` content.

## Design Patterns

See `references/design-patterns.md` for:

- **Scaffold Pattern**: Skills that generate project structures
- **Pipeline Pattern**: Skills that chain multiple operations
- **Adapter Pattern**: Skills that wrap external tools/APIs
- **Wizard Pattern**: Skills that guide through interactive processes
- **Guard Pattern**: Skills that enforce rules and constraints

## Quality Checklist

See `references/quality-checklist.md` for the complete pre-release checklist covering:
- Frontmatter validation
- Description quality
- Structure integrity
- Script reliability
- Portability verification
- Security review

## Common Pitfalls

| Pitfall | Fix |
|---------|-----|
| Description lacks trigger phrases | Add "Use when user says 'X', 'Y'" |
| SKILL.md > 500 lines | Move details to references/ |
| Agent-specific features in core | Move to agent-specific sections or remove |
| Scripts without error handling | Add try/except and clear messages |
| Broken file references | Run `validate_skill.py` |
| Name doesn't match directory | Ensure exact match |
| Missing negative scope | Add "Do NOT use for..." |
| No usage examples | Add concrete command examples |

---

*Built with skill-maker. Follows the agent-skills specification (agent-skills-v0.14).*