Skill Creator

Skills are modular packages that extend an agent's capabilities with specialized knowledge, workflows, and tools. Think of them as "onboarding guides" that transform a general-purpose agent into a specialized one.

Core Principle: The Context Window is a Public Good

Skills share context with: system prompt, conversation history, other skills' metadata, and the user's request.

Default assumption: The agent is already very smart. Only add context it doesn't already have. Challenge each piece: "Does the agent really need this?" and "Does this justify its token cost?"

Prefer concise examples over verbose explanations.

Skill Structure

skill-name/
├── SKILL.md              (required - the only required file)
├── references/           (optional - docs loaded on-demand)
├── scripts/              (optional - executable code)
└── assets/               (optional - templates, images, etc.)

SKILL.md Format

---
name: skill-name
description: What it does and WHEN to use it. This is the ONLY trigger mechanism.
---

# Skill Name

[Instructions for using the skill - loaded only AFTER skill triggers]

Frontmatter rules:

• •name (required): hyphen-case, must match directory name
• •description (required): what + when. This is ALL the agent sees for selection.
• •Nothing else. No license, no allowed-tools, no metadata.

Why minimal frontmatter?

• •The description is the ONLY thing that helps with skill selection
• •Extra fields are noise that don't help selection decisions
• •allowed-tools is for runtime permissions, not selection - skip it
• •Weaker models get confused by extra frontmatter

The Description is Everything

The description determines when your skill gets loaded. It must answer:

1. •What does this skill do?
2. •When should the agent use it?

Good:

description: Create and execute commit plans using the commit-helper tool - use when managing commits across repositories

Bad:

description: A skill for commits

Progressive Disclosure

Three-level loading minimizes context bloat:

1. •Metadata (~100 tokens) - Always in context (name + description only)
2. •SKILL.md body (<5k tokens) - Loaded when skill triggers
3. •Bundled resources (unlimited) - Loaded on-demand by agent

Keep SKILL.md under 500 lines. Split into references/ when approaching this limit.

What to Include

In SKILL.md Body

• •Core workflow steps
• •Decision points and branching logic
• •References to bundled resources ("see references/foo.md for details")
• •Concise examples (prefer over verbose explanations)

In references/

• •Detailed documentation
• •Domain-specific knowledge
• •API specs, schemas
• •Variant-specific patterns (e.g., aws.md, gcp.md)

In scripts/

• •Deterministic operations that would be rewritten each time
• •Complex transformations
• •Validated, tested code

Script execution guidance:

• •Use shebang lines (e.g., #!/usr/bin/env python3) so scripts can run directly
• •Document required dependencies in the script's docstring
• •If a specific interpreter is needed, document it in SKILL.md

In assets/

• •Templates
• •Boilerplate code
• •Images, fonts
• •Files used in output (not loaded into context)

What to NOT Include

Never create these files:

• •README.md
• •INSTALLATION_GUIDE.md
• •QUICK_REFERENCE.md
• •CHANGELOG.md
• •Any "meta" documentation

The skill is for an agent, not a human. No auxiliary context about creation, setup, or testing.

System Safety: Do Not Mutate

Default behavior: Do NOT modify the system.

Skills should NEVER encourage the agent to:

• •Install packages with pip install (or npm, apt, brew, etc.)
• •Modify system configuration
• •Create files outside the project directory
• •Run commands that require elevated privileges

When scripts have dependencies:

1. •Document them - List required packages in the script docstring and SKILL.md
2. •Fail gracefully - If dependencies are missing, report the error clearly
3. •Let the user decide - Tell the user what's needed; don't auto-install

Exceptions (when agent MAY install packages):

• •Agent has explicit custody of a project venv (e.g., ./local.venv/bin/python)
• •User has explicitly authorized package installation
• •Project rules/guidelines grant this permission

Example SKILL.md guidance for scripts with dependencies:

### If Dependencies Are Missing

If the script fails due to missing packages:
1. Report the error to the user
2. Tell the user what's needed: "This script requires X and Y"
3. Let the user decide how to install

Exception: If you have custody of a project venv and authorization
to install packages, you may install there.

Skill Locations in Brynhild

Skills are discovered from (in priority order):

1. •~/.config/brynhild/skills/ - Global user skills
2. •$BRYNHILD_SKILL_PATH - Custom paths (colon-separated)
3. •.brynhild/skills/ - Project-local skills (highest priority)

For project-specific skills, use .brynhild/skills/. For personal/global skills, use ~/.config/brynhild/skills/.

Skill Creation Process

1. •Understand - Get concrete examples of how the skill will be used
2. •Plan - Identify what scripts, references, assets would help
3. •Create - Make the directory and SKILL.md
4. •Test - Use the skill on real tasks
5. •Iterate - Refine based on actual usage

Step 1: Understand

Ask clarifying questions:

• •"What functionality should this skill support?"
• •"Can you give examples of how it would be used?"
• •"What would a user say that should trigger this skill?"

Step 2: Plan

For each example, consider:

• •What code gets rewritten each time? → scripts/
• •What documentation would help? → references/
• •What templates or assets are needed? → assets/

Step 3: Create

mkdir -p .brynhild/skills/my-skill
# Create SKILL.md with minimal frontmatter
# Add references/, scripts/, assets/ as needed

Step 4: Test

Use the skill in real scenarios. Note struggles or inefficiencies.

Step 5: Iterate

Update SKILL.md and resources based on actual performance.

Design Patterns

See references/patterns.md for:

• •Sequential workflows
• •Conditional workflows
• •Template patterns
• •Example patterns
• •Progressive disclosure patterns