Karma Skill Creator

Create well-structured Claude Code skills for the Karma ecosystem.

Skill Creation Process

Understand the skill with concrete examples
Plan reusable skill contents (references, assets)
Initialize the skill directory structure
Write the skill (implement resources and SKILL.md)
Validate against the checklist before shipping
Iterate based on real usage

Step 1: Understand the Skill

Ask the user for concrete examples of how the skill will be used:

"What should this skill do? Can you give 2-3 example prompts?"
"What would a user say that should trigger this skill?"
"What Karma-specific context does this need?" (grants, funding maps, ecosystem data)

Step 2: Plan Reusable Contents

For each example, identify what reusable resources would help:

Resource Type	When to Use	Example
`references/`	Domain knowledge Claude needs	`references/gap-schema.md`
`assets/`	Files used in output	`assets/report-template.md`

Step 3: Initialize the Skill

Create the skill directory under skills/:

skills/<skill-name>/
├── SKILL.md          # Required
├── references/       # Optional
└── assets/           # Optional

Naming rules:

kebab-case, lowercase letters, digits, and hyphens only
Max 64 characters
Descriptive: grant-milestone-tracker, not tracker

Step 4: Write the Skill

How Skills Load (Progressive Disclosure)

Skills use a three-level system — understanding this is critical for writing effective skills:

YAML frontmatter — always loaded into Claude's system prompt. This is how Claude decides whether to activate the skill. Keep it lean: just name and description.
SKILL.md body — loaded only when Claude thinks the skill is relevant. Contains the full instructions.
Linked files (references/, assets/) — Claude navigates to these on demand. Use for detailed docs, templates, and examples.

The implication: frontmatter must be self-sufficient for triggering. The body must be self-sufficient for execution. Reference files are for depth.

Writing the Description (Most Important Field)

The description field determines whether your skill triggers. Get this right.

Structure: [What it does] + [When to use it] + [Key capabilities]

Rules:

Under 1024 characters
MUST include both what the skill does AND when to use it (trigger phrases)
Include specific phrases users would actually say
No XML angle brackets (< or >)

Good examples:

# Specific, with trigger phrases
description: Analyzes grant milestone reports and generates
  compliance summaries. Use when user asks to "review milestones",
  "check grant progress", or "generate a milestone report".

# Clear scope with negative triggers
description: Advanced data analysis for CSV files. Use for
  statistical modeling, regression, clustering. Do NOT use for
  simple data exploration (use data-viz skill instead).

Bad examples:

# Too vague — won't trigger reliably
description: Helps with projects.

# Missing triggers — when should Claude load this?
description: Creates sophisticated multi-page documentation systems.

# Too technical, no user-facing triggers
description: Implements the Project entity model with hierarchical
  relationships.

Debugging tip: Ask Claude "When would you use the [skill-name] skill?" — it will quote the description back. Adjust based on what's missing.

SKILL.md Body

---
name: skill-name
description: What the skill does and when to use it. Include specific triggers.
---

The body contains instructions Claude will follow. Key principles:

Concise is key. Claude is already smart — only add what it doesn't know. Challenge each paragraph: "Does this justify its token cost?"

Set appropriate freedom levels:

High freedom (text instructions): multiple valid approaches, context-dependent
Medium freedom (pseudocode/parameterized scripts): preferred pattern with some variation
Low freedom (exact scripts): fragile operations, consistency critical

Progressive disclosure: Keep SKILL.md under 500 lines. Split into reference files when approaching this limit.

Design Patterns

Consult these guides based on your skill's needs:

Multi-step processes: See workflows.md for sequential and conditional patterns
Output format/quality: See output-patterns.md for template and example patterns

What NOT to Include

README.md, CHANGELOG.md, or other auxiliary docs
"When to use" sections in the body (put this in the frontmatter description)
Setup/testing procedures
Information Claude already knows

Step 5: Validate Before Shipping

Run through this checklist before considering the skill done:

Structure:

Folder named in kebab-case
SKILL.md exists (exact casing)
YAML frontmatter has --- delimiters on both sides
name field: kebab-case, no spaces, no capitals
No XML angle brackets (< >) anywhere in frontmatter
Skill name does not contain "claude" or "anthropic" (reserved)
No README.md inside the skill folder

Description:

Includes WHAT the skill does
Includes WHEN to use it (trigger phrases)
Under 1024 characters
Trigger phrases match how users actually talk

Triggering:

Triggers on obvious task requests
Triggers on paraphrased requests
Does NOT trigger on unrelated topics

Instructions:

Instructions are clear and actionable
Critical steps use explicit language, not vague guidance
Error handling included for likely failure points
References clearly linked (not inlined)

Step 6: Iterate

Use the skill on real tasks
Note struggles or inefficiencies
Update SKILL.md or resources

Let the user's specifications guide the skill's domain and direction.

skill-creator