BGSkillz

Build high-quality, portable Claude skills that trigger reliably and deliver real value.

Core Philosophy

Skills are prompts — SKILL.md is a prompt document. Everything in it shapes Claude's behavior when the skill activates.
Explain the why, not just the what — LLMs are smart. They respond better to understood rationale than rigid rules. Instead of "ALWAYS use 4-space indentation," explain why consistent indentation matters. If you find yourself writing MUST or NEVER in all caps, that's a yellow flag — reframe as reasoning.
Progressive disclosure — Keep SKILL.md lean (<500 lines). Put deep reference material in references/, agent instructions in agents/, and link to them. Claude reads these when referenced explicitly.
Composability — Skills should do one thing well. Combine multiple skills for complex workflows rather than building monoliths.
Portability — Skills work across Claude.ai, Claude Code, and the API. Write for all surfaces unless you have a reason not to.
Specificity wins — Vague skills don't trigger. Specific skills with clear use cases and trigger phrases activate reliably. Make descriptions slightly "pushy" — Claude tends to undertrigger rather than overtrigger.
Generalize, don't overfit — A skill that works only for your test examples is useless. It will be invoked by diverse users with diverse needs. When iterating, resist fiddly overfitty changes. Instead, try different metaphors and explain reasoning. Lean toward fewer, higher-impact improvements.

Skill Anatomy

my-skill/
├── SKILL.md              # Required. Main entry point. Contains frontmatter + instructions.
├── agents/               # Optional. Sub-agent instruction files for multi-agent workflows.
├── scripts/              # Optional. Executable helpers (Python, Bash, etc.)
├── references/           # Optional. Deep reference docs linked from SKILL.md.
└── assets/               # Optional. Templates, configs, examples bundled with the skill.

SKILL.md is the only required file. It must be exactly SKILL.md (not skill.md, not README.md).

Frontmatter fields:

name (required): kebab-case, no spaces, no capitals, no "claude" or "anthropic"
description (required): Under 1024 chars. Determines when the skill triggers.
license, metadata, compatibility: Optional but recommended for distribution.

Creation Workflow

Follow these 7 steps to build a skill from scratch.

Step 1: Define 2-3 Concrete Use Cases

Before writing anything, articulate exactly who will use this skill and for what. Pick a category:

Document/Asset Creation — Generate reports, code, configs, designs
Workflow Automation — Multi-step processes with tools and decisions
MCP Enhancement — Add intelligence on top of MCP server capabilities

Write 2-3 specific use case sentences: "A developer wants to... so they can..."

Step 2: Define Success Criteria

Set measurable goals before building:

Quantitative: Triggers correctly >90% of the time, reduces task time by X%, output matches template Y% of the time
Qualitative: Users find output useful without heavy editing, skill integrates naturally into existing workflow

Step 3: Choose Your Approach

Problem-first: You have a pain point. Design the skill around solving it.
Tool-first: You have an MCP server or API. Design the skill to make it more useful.

Problem-first skills tend to have better descriptions because the pain point is the trigger.

Step 4: Plan Reusable Contents

Decide what goes into each directory:

agents/: Sub-agent instruction files loaded only when spawning specialized agents (graders, comparators, analyzers). These keep SKILL.md lean while enabling multi-agent workflows.
scripts/: Anything Claude should execute (scaffolders, validators, eval runners, build tools)
references/: Deep knowledge Claude should read when needed (style guides, API docs, patterns, schemas)
assets/: Templates, example files, configs that get copied into user projects

Rule of thumb: If it's >50 lines and not needed on every invocation, it belongs in references/. If it's instructions for a sub-agent, it belongs in agents/.

Step 5: Initialize the Skill

Run the scaffolder to create your skill directory:

python ~/.claude/skills/bgskillz/scripts/init_skill.py my-skill-name --path ~/target/directory

This creates a well-structured starting point with TODO prompts to guide you.

Step 6: Write the Skill

This is where quality is made or lost. Follow these rules:

Description (most critical field): Use the formula: [What it does] + [When to use it] + [Key capabilities]

Good: "Generate production-ready database migrations from natural language descriptions. Use when adding tables, columns, indexes, or modifying schema. Handles rollbacks, data preservation, and index optimization."

Bad: "Helps with database stuff."

See references/description-crafting.md for 15+ examples and anti-patterns.

Naming rules:

kebab-case only: my-cool-skill not MyCoolSkill
No spaces or capital letters
Never include "claude" or "anthropic" in the name
Skill folder name must match the name: field in frontmatter

Writing instructions:

Use imperative voice: "Generate a report" not "You should generate a report"
Be specific and actionable: "Use 4-space indentation" not "Format code nicely"
Explain reasoning over rigid rules: "Use early returns because deeply nested code is harder to debug" is more effective than "ALWAYS use early returns"
Front-load critical instructions — Claude may skim long documents
Include examples of good output when possible — Claude mimics examples more reliably than it follows abstract rules
Use markdown headings (##, ###) to organize sections — NOT XML tags
Provide a "degrees of freedom" principle: tell Claude what it CAN vary, not just constraints
Set defaults with escape hatches: "Use TypeScript by default. If the user specifies another language, use that instead."
Calibrate your tone to your audience — users range from non-technical to expert developers. Use context cues from the user's message to adapt jargon level.

Error handling:

Tell Claude what to do when things go wrong
Include fallback behaviors for missing tools or failed API calls
Specify how to communicate errors to the user

Security rules:

Never instruct Claude to bypass safety measures
Don't hardcode credentials or API keys
Don't reference external URLs that could change or be compromised
Scripts should validate inputs before executing

Step 7: Package and Distribute

Run the packager to validate and create a distributable zip:

python ~/.claude/skills/bgskillz/scripts/package_skill.py /path/to/my-skill

This runs full validation, then creates a zip ready for upload or sharing. See references/distribution-guide.md for hosting and positioning guidance.

Critical Rules

These are hard requirements. Violating them causes failures.

File must be named SKILL.md — Exact casing. Not skill.md, not Skill.md.
No README.md inside the skill folder — It confuses the system. README goes in your GitHub repo root, outside the skill folder.
Name must be kebab-case — my-skill not my_skill or MySkill or my skill
No XML tags in frontmatter — No < or > characters anywhere in the YAML block.
Name must match folder — If folder is my-skill/, frontmatter name must be my-skill.
No "claude" or "anthropic" in name — Reserved terms.
Description under 1024 characters — Hard limit.
SKILL.md under 5000 words — Beyond this, Claude's attention degrades. Use references for depth.
One level of nesting — One level deep is fine. Nested subdirectories like bar/baz/ inside references are not.
Forward slashes only — Even on Windows. No backslash paths.

bgskillz