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

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

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:

Record answers for Step 2.

Step 2: DESIGN — Plan the Skill

Based on the DISCOVER answers, decide:

Structure Pattern (pick primary, mix as needed):

Resource Planning:

Token Budget:

Step 3: INIT — Scaffold the Skill

Use the init script to create the directory structure:

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):

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)

---
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

# 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

Step 5: VALIDATE — Check Quality

Run the validator:

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

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)

Agent-Specific (Restricted)

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

## 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

# 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:

# 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.

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

validate_skill.py

Validate a skill against the agent-skills specification.

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

package_skill.py

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

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

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