Skill Creator

Skill Creator — Comprehensive Skill Authoring Guide

Overview

This skill guides you through the complete process of creating a new AI skill for the system. A skill is a reusable instruction bundle that teaches the AI how to perform a specific type of task. Skills follow the AgentSkills open specification.

Skills use progressive disclosure to manage context efficiently:

1. L1 — Metadata (~100 tokens): name + description loaded at startup for all skills
2. L2 — Instructions (SKILL.md body): Loaded only when the skill is activated
3. L3 — Resources (scripts/, references/, assets/): Loaded on demand

1. Skill Directory Structure

1.1 Full File Layout

Copy code
<skill-name>/                        # Directory name = skill name (lowercase + hyphens)
├── SKILL.md                         # Required: metadata + instructions
├── scripts/                         # Optional: executable code
│   ├── script.py
│   ├── script.sh
│   └── ...
├── references/                      # Optional: reference docs loaded on demand
│   ├── api-spec.md
│   ├── configuration-guide.md
│   └── ...
├── assets/                          # Optional: templates, configs, resources
│   ├── template.json
│   ├── icon.svg
│   └── ...
└── ...                              # Any additional files or directories

1.2 Minimal Structure (always valid)

Copy code
<skill-name>/
└── SKILL.md

A single SKILL.md file is all that's required. The optional directories are for organizing larger skills.

1.3 Location by Source Type

2. SKILL.md Format Specification

2.1 Overall Structure

Copy code
---
<YAML frontmatter>
---

<Markdown body>

• Opening --- must be at line 1 of the file
• Frontmatter parser pattern: /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/
• Must have a blank line after closing --- before body content

2.2 Frontmatter Fields

2.3 Name Validation Rules

The system enforces these rules:

Copy code
✓ name is present (required)
✓ 1-64 characters
✓ matches ^[a-z0-9-]+$  (lowercase letters, digits, hyphens only)
✓ does not start or end with a hyphen
✓ does not contain consecutive hyphens (-- inferred by the pattern)
✓ matches the parent directory name (case-insensitive)

Examples:

Copy code
✅ code-review
✅ data-analyzing-v2
✅ translation-helper
❌ Code-Review        (uppercase not allowed)
❌ code_review        (underscore not allowed)
❌ -code-review       (leading hyphen)
❌ code-review-       (trailing hyphen)
❌ code--review       (consecutive hyphens)

Naming Strategy

A good name is short, scannable, and self-explanatory:

• Use the core function as the name: pdf, docx, xlsx, mcp-builder
• Avoid vague names: tool, helper, utils, my-script — these don't tell Claude when to trigger
• Compound names OK: slack-gif-creator, web-artifacts-builder, theme-factory
• Version suffix only when needed: data-analyzing-v2 (not data-analyzing-final-final)
• Follow existing conventions: look at other skills in the system for naming patterns

Good names read like CLI commands — users and AI alike can guess what they do by reading the name alone.

2.4 Description Best Practices

The description is the primary trigger mechanism — it's what Claude reads to decide whether to use the skill. Get this right above all else.

Core Rules

• Use third-person ("Generating review reports…" not "Generate review reports…")
• Describe what the skill does and when to use it
• Max 1024 characters

The "Pushy" Style

Claude has a tendency to undertrigger skills — not use them when they'd be useful. To combat this, make descriptions a little pushy. Include not just what the skill does, but specific contexts where it should trigger — even if the user doesn't explicitly ask for it.

Pattern:

markdownCopy code
<what it does>. Use this skill whenever <context A>, <context B>, or <context C>,
even if the user doesn't explicitly mention <keyword>.

Good:

Copy code
Creating slide decks, pitch decks, and presentations. Use this skill any time
a .pptx file is involved in any way — as input, output, or both. Trigger
whenever the user mentions "deck," "slides," "presentation," or references a
.pptx filename, regardless of what they plan to do with the content afterward.

Poor (too passive):

Copy code
Creating PowerPoint presentations

Trigger Coverage

Ask yourself: what are all the ways a user might ask for this? List the synonyms, casual phrasings, and edge cases:

• Formal: "Generate a PDF report"
• Casual: "turn this into a PDF"
• Implicit: "I need to send this to the client" (implies PDF)
• Adjacent: "make this fillable" (implies PDF form)

Cover these in the description so Claude catches them all.

What NOT to Put in Description

• ❌ Implementation details ("uses Python 3.10 with pandas")
• ❌ Step-by-step instructions (that goes in the body)
• ❌ Developer notes ("todo: add error handling")
• ❌ Version info or changelog

Good:

Copy code
Generating comprehensive code review reports, identifying potential bugs,
security vulnerabilities, and style violations in pull requests. Use when
reviewing PRs or analyzing code quality.

Poor:

Copy code
Code review tool

2.5 Frontmatter Example

yamlCopy code
---
name: data-analyzing
description: Analyzing structured datasets, identifying trends, and generating statistical summary reports
version: 2.1.0
author: team-data
tags: [analysis, data-science, reporting]
license: MIT
compatibility: Requires Python 3.10+ with pandas and numpy
---

3. Progressive Disclosure Model

3.1 L1 — Metadata (always loaded)

Only name and description are loaded into the system prompt at startup. The AI uses this to determine if a skill might be relevant to the user's request. This is why description must include trigger keywords.

3.2 L2 — Instructions (activated on demand)

When the AI decides a skill is relevant, it reads the full SKILL.md body from its file path (provided in the skills list). This is the core instruction content.

3.3 L3 — Resources (loaded as needed)

When the skill body references files from scripts/, references/, or assets/, the AI reads them on demand. This keeps the initial skill activation lean.

3.4 Organizing Large Skills

If a skill's instructions exceed 100-200 lines, split them:

Copy code
writing-assistant/
├── SKILL.md                  # Core instructions + overview
├── references/
│   ├── style-guide.md        # Detailed style rules (loaded only when style is relevant)
│   ├── grammar-rules.md      # Grammar reference (loaded only for grammar tasks)
│   └── templates.md          # Output templates (loaded when generating)
├── scripts/
│   └── validate-markdown.js  # Validation script (run when checking output)
└── assets/
    └── template-letter.docx  # Template file (download when creating letters)

4. Creating a Skill — Step by Step

Step 1: Plan the Skill

Determine:

• Name: Short, lowercase, hyphenated (my-skill-name)
• Description: What + when (will be the AI's main trigger)
• Scope: How much instruction content is needed?
• Resources: Any scripts, templates, or references?

Step 2: Create the Development Directory

Create the skill directory in your current working directory for development:

Copy code
mkdir -p <skill-name>

Directory name must match the planned name field.

Step 3: Write SKILL.md

Create {SKILL_DIR}/<skill-name>/SKILL.md with:

markdownCopy code
---
name: my-skill-name
description: What this skill does and when to use it
---

# Skill Instructions

Detailed instructions the AI should follow when this skill is activated.

Step 4: Add Optional Resources (if needed)

Copy code
mkdir scripts/ references/ assets/

Step 5: Validate the Skill ⚠️ Required

Before installing, run the bundled validation script to check for errors. The script lives in this skill's own directory (scripts/validate-skill.mjs), relative to the resourceBase directory returned by the skill_learn tool. Run it from that directory:

bashCopy code
node scripts/validate-skill.mjs <skill-name>

This checks 14 items: frontmatter format, name rules (lowercase, length, no leading/trailing hyphens), directory-name consistency, description constraints, optional fields, body length, and directory structure. All must pass before proceeding.

If validation fails, fix the reported issues and re-run until it passes.

Step 6: Install the Skill

After validation passes, move the skill directory to the system's skills directory:

Copy code
mv <skill-name> {SKILL_DIR}/<skill-name>

Windows users: ~ maps to your user directory, i.e. C:\Users\<username>\.guada\skills\.
You can also move the <skill-name> folder via File Explorer to C:\Users\<username>\.guada\skills\.

Step 7: Automatic Registration

Once placed in {SKILL_DIR}/, the file watcher automatically detects the new SKILL.md and registers the skill within seconds — no manual action needed.

Step 8: Verify Registration

Use the read tool to confirm the skill is registered:

markdownCopy code
read({ path: "{SKILL_DIR}/my-skill-name/SKILL.md" })

This checks 14 items including frontmatter format, name rules, directory-name consistency, description constraints, optional fields, and directory structure. See scripts/validate-skill.mjs for details.

5. SKILL.md Body Writing Guidelines

5.1 Recommended Sections

5.2 Writing Philosophy

Explain the WHY, Not Just the WHAT

Today's LLMs are smart — they have good theory of mind and can go beyond rote instructions when given proper understanding. Instead of heavy-handed ALWAYS / MUST / NEVER, explain the reasoning:

markdownCopy code
## Good: Explain the WHY
Use the imperative verb form (e.g. "Generate a report") rather than descriptive
("This skill generates a report"). The imperative form makes the instruction
actionable — Claude will execute it directly rather than reading about it.

## Poor: Rigid MUST/ALWAYS
ALWAYS use imperative form. NEVER use descriptive form.

When you find yourself typing ALL CAPS or extremely rigid structures, that's a yellow flag — try to reframe and explain the why.

Keep It Lean

Every line in a skill is executed on every invocation. Remove things that aren't pulling their weight:

• Read the transcripts, not just the outputs — if Claude wastes time on unproductive steps, prune those parts of the skill
• Avoid redundancy — don't restate the same instruction in multiple ways
• Short paragraphs — one idea per paragraph, scannable
• Bundle repeated work — if test runs show Claude writing the same helper script across different prompts, that script belongs in scripts/

Generalize, Don't Overfit

Skills are used millions of times across unpredictable prompts. Don't write instructions that only work for the examples you tested:

• Use theory of mind — understand the user's intent, not just their literal words
• Explain patterns rather than prescribing exact steps
• Branch out — if a stubborn issue keeps appearing, try a different metaphor or approach instead of piling on more constraints
• Test with fresh eyes — write a draft, step away, then review it as if you're seeing it for the first time

Writing Patterns

Use imperative form in instructions. Tell Claude what to do, not what the skill is about.

Defining output formats — be explicit about structure:

markdownCopy code
## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations

Examples with Input/Output — useful for format-oriented skills:

markdownCopy code
## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

Principle of Lack of Surprise

Skills must not contain malware, exploit code, or content that could compromise system security. A skill's intent should not surprise the user if described honestly. Don't go along with requests to create misleading skills or skills designed for unauthorized access.

Organization Tips

• Use headings (##, ###) to structure content
• Use code blocks for commands, configs, and code
• Use tables for reference data
• Use numbered lists for sequential steps
• Reference bundled files explicitly: see references/style-guide.md
• Define clear boundaries — what the skill does AND doesn't do
• Keep paragraphs short and scannable

5.3 Complete Minimal Example

markdownCopy code
---
name: hello-world
description: Printing a friendly greeting and demonstrating basic skill structure
version: 1.0.0
author: guada
tags: [example, demonstration]
---

# Hello World — Example Skill

## Overview

A minimal example skill that demonstrates the SKILL.md format.

## Instructions

When asked to say hello:

1. Respond with a friendly greeting
2. Include the user's name if known
3. Ask how you can help them today

## Rules

- Always be polite and friendly
- Keep the greeting concise

6. Skill Lifecycle

7. Scripts Directory

Place executable code in scripts/. The AI can read and run these files:

Copy code
scripts/
├── transform.py         # Data transformation script
├── generate_report.sh   # Report generation script
└── ...

The AI can:

• Read script contents for understanding
• Execute scripts using available tools
• Reference scripts from SKILL.md body

Best practice: When test runs reveal Claude repeatedly writing the same helper logic across different prompts, bundle it into a script under scripts/ instead. This saves every future invocation from reinventing the wheel.

8. References Directory

Place reference documentation in references/. The AI loads these on demand:

Copy code
references/
├── api-docs.md         # API reference
├── configuration.md    # Setup guide
├── faq.md              # Frequently asked questions
└── ...

Reference from within SKILL.md:

markdownCopy code
For detailed API documentation, see references/api-docs.md.

9. Assets Directory

Place templates, configuration files, icons, and output resources in assets/:

Copy code
assets/
├── template.json       # JSON template file
├── config.yml          # Default configuration
├── icon.svg            # Skill icon
└── ...

10. Validation Reference

10.1 Auto-Validation

The system validates on every automatic scan or reload, triggered by the file watcher on any SKILL.md change:

Copy code
✓ File exists: <dir>/SKILL.md
✓ YAML frontmatter present and properly delimited
✓ Frontmatter parsed as valid YAML object
✓ name: present (≤64 chars)
✓ name: matches ^[a-z0-9-]+$
✓ name: no leading/trailing hyphens
✓ name: matches directory name (case-insensitive)
✓ description: present (≤1024 chars)
✓ SHA256 content_hash computed for change detection

10.2 Offline Validation Script

This skill bundles scripts/validate-skill.mjs — a more comprehensive Node.js validation tool that you run before installation. It checks everything the system checks, plus additional guardrails:

14 checks performed:

Usage:

bashCopy code
# Run from this skill's `resourceBase` directory (returned by skill_learn):
node scripts/validate-skill.mjs <skill-directory>

Exit codes:

• Exit code 0 — all checks passed
• Exit code 1 — errors found and must be fixed

11. Spec Compliance

This skill follows the AgentSkills open specification for interoperability. The system's name field:

• Is lowercase-only ([a-z0-9-]) — per spec requirement
• Must match directory name — per spec requirement
• Is auto-converted to lowercase for ID — manifest.name.toLowerCase()