Skill Creator

Skill Creator

Builds structured skills for AI agents following a consistent pattern.

Core Principle

A skill is a bundled, routing-based knowledge system. The agent doesn't navigate a folder tree — it follows routes from a single entry point. Dead content is worse than no content: every file must be registered in the routing table or it won't be found.

Lifecycle

Every new skill follows this path:

1. Bootstrap    → Create repo structure, write SKILL.md skeleton
2. Add docs     → Create *.md reference docs, register in SKILL.md routing
3. Add scripts  → Create tools under scripts/, reference from docs (optional)
4. Add agents   → Create specialized agents under agents/ (optional)
5. Validate     → Run structure tests

Not every skill needs scripts or agents. Start with docs only.

Bootstrap a New Skill

Step 1 — Define the Skill

Answer these before writing any code:

Step 2 — Create Directory Structure

skills/<name>/
├── SKILL.md           # Entry point (required)
├── *.md               # Reference docs (at least basics.md)
├── agents/            # Specialized agents (optional)
├── scripts/           # Tool scripts (optional)
├── data/              # Embedded indexes (optional)
└── examples/          # Runnable examples (optional)

Important: The skills/<name>/ directory is the bundle. Everything outside it is development infrastructure.

Step 3 — Write SKILL.md

SKILL.md must have:

• --- frontmatter with name and description
• Detection section (what triggers this skill)
• Routing table (which doc to read for what task)
• Dependencies list
• Script usage (if any scripts exist)

Step 4 — Add Reference Docs

For each doc:

1. Create skills/<name>/<topic>.md
2. Start with a cross-reference line
3. Lead with patterns, not prose
4. Add entry to SKILL.md routing table

Step 5 — Add Scripts (optional)

Scripts go in scripts/. Requirements:

Step 6 — Validate

Run the structure validator:

python tests/test_structure.py

Every .md file must be registered in SKILL.md routing table.

SKILL.md Template

---
name: <name>
description: 'One-line description. Use when: (1) trigger conditions, (2) file patterns, (3) user intent'
---

# <Name>

## Detection

What activates this skill?

**File patterns:** `*.ext`, `*.config`
**Keywords:** `import`, `function`, `task`
**Commands:** `build`, `deploy`, `init`

## Routing

| When you need to... | Read |
|---|---|
| Get started | [basics.md](basics.md) |
| Configure | [config.md](config.md) |
| Common tasks | [tasks.md](tasks.md) |

## Dependencies

Required tools and how to install them.

## Script Usage (optional)

```bash
python scripts/search.py "query"
```

## Examples (optional)

| Example | Description |
|---|---|
| [example.ext](examples/example.ext) | ... |

Writing Reference Docs (*.md)

Rules for .md files inside skills/<name>/:

1. First line: Cross-reference to sibling docs
2. Lead with pattern, not explanation: Show code first, explain after
3. Tables over prose: Agents parse structure better
4. Code blocks use correct fencing: ```<lang> for code, ```bash for shell
5. Code examples should compile: If snippet, say so

Writing Agents

When a task needs a specialized agent, create agents/<name>-<task>.md:

---
name: <name>-<task>
description: 'What this agent does. Use when: trigger conditions'
model: claude-sonnet-4-6
---

You are a <task> agent for <name>. [Detailed system prompt...]

Script Path Management

When scripts live inside skills/<name>/scripts/:

from pathlib import Path

base_dir = Path(__file__).parent.parent  # → skills/<name>
data_dir = base_dir / "data"
# For upstream docs at repo root:
upstream_dir = base_dir.parent / "references" / "docs"

Use parent.parent (not parent.parent.parent). Rule: scripts are at skills/<name>/scripts/.

Building Search Indexes from Upstream Docs

If upstream docs are HTML, you can parse them to build a search index:

extract-api.py Pattern

1. Scan for keyword files — glob pattern depends on naming convention
2. Parse HTML structure — find predictable sections (title, syntax, params, examples)
3. Handle complex names — some keywords have special characters (Print | ?), must be looked up exactly
4. Build api.json with: name, category, syntax, description, parameters, examples, see_also

BM25 Index

K1 = 1.5   # term frequency saturation
B = 0.75   # document length normalization
WEIGHTS = {'name': 3.0, 'syntax': 2.0, 'description': 1.0}

Field weights: name at 3x because exact matches should rank highest.

Search Script Interface

python scripts/search.py "query" --top 5      # ranked search
python scripts/search.py --name "keyword"    # exact lookup
python scripts/search.py "query" --json       # structured output

Encoding Safety

Windows console may use GBK. Always clean text output:

def clean_text(text: str) -> str:
    return text.replace('\xa0', ' ').replace('​', '')

Detection Patterns by Type

Do not assume shebang — many compiled languages don't have it.

Routing Table Enforcement

Every new file MUST be registered in SKILL.md's routing table.

A doc not in the routing table is invisible to agents. Test tests/test_structure.py enforces this.

Pattern:

• New .md doc → add row in routing table
• New script → document in "Script Usage"
• New agent → document which docs reference it

Commit Style

Imperative mood, lowercase, no period. Scope prefix.

skill: bootstrap <name> structure
docs: add basics.md and config.md
scripts: add search with embedded index
agent: add <name>-verify agent

Common Mistakes