ravnhq/agent-skill-creator

Skill Creator

Create effective, portable skills that work across Claude.ai, Claude Code, and the API. A skill is a folderized instruction set that encodes a reusable workflow once, then applies it consistently.

Skill Structure

skill-name/
├── SKILL.md              # Required: YAML frontmatter + markdown instructions
├── scripts/              # Optional: executable code for deterministic tasks
├── references/           # Optional: docs loaded into context as needed
└── assets/               # Optional: files used in output (templates, images, fonts)

SKILL.md

Two parts:

1. Frontmatter (YAML) — name and description fields. Always in context. Determines when the skill triggers.
2. Body (Markdown) — Instructions, workflows, and pointers to bundled resources. Loaded only after triggering.

Bundled Resources

| Directory | Purpose | Loaded into context? | |-----------|---------|---------------------| | scripts/ | Executable code (Python/Bash) for deterministic operations | Only when Claude reads them | | references/ | Documentation Claude consults while working | On demand | | assets/ | Files used in output (templates, images, fonts) | Never — used directly in output |

Do not include README.md, CHANGELOG.md, or any auxiliary documentation files.

Core Principles

Context Budget

The context window is shared. Only include what Claude does not already know. Prefer concise examples over verbose explanations. Every paragraph must justify its token cost — remove paragraphs that do not.

Hard limit: Keep SKILL.md body under 5,000 words. Move detailed content to references/.

Degrees of Freedom

Match specificity to the task's fragility:

• High freedom (text guidance) — multiple valid approaches, context-dependent
• Medium freedom (pseudocode/parameterized scripts) — preferred pattern, some variation ok
• Low freedom (exact scripts) — fragile operations, consistency critical

Progressive Disclosure

Three-layer loading minimizes context usage:

1. Frontmatter (under 100 words) — always in context
2. SKILL.md body (under 5,000 words) — loaded when skill triggers
3. Bundled resources (unlimited) — loaded as needed

Keep SKILL.md lean. Split into reference files when exceeding 300 lines. Always reference split files from SKILL.md with clear descriptions of when to read them.

Composability and Portability

• Skills must coexist without conflicting instructions
• Skills must work across Claude.ai, Claude Code, and the API
• Do not hard-depend on environment-specific tooling

Workflow

1. Understand

Gather concrete use cases before building anything.

Entry: User request to create or improve a skill.

Actions:

• Identify 2-3 concrete examples of how the skill will be used
• For each example: what triggers it, what steps run, what the end result looks like
• Ask targeted questions — avoid overwhelming the user with too many at once

Exit: Clear understanding of the skill's scope, triggers, and expected outputs.

2. Plan

Determine what reusable resources the skill needs.

Entry: Concrete use cases from Step 1.

Actions:

• For each use case: what gets rewritten every time? That belongs in the skill.
• Categorize resources:
  • Code rewritten repeatedly → scripts/
  • Knowledge referenced repeatedly → references/
  • Templates/assets used in output → assets/
• Decide SKILL.md structure — see references/workflows.md for common patterns.

Exit: List of resources to create and SKILL.md outline.

3. Build

Create the skill folder and write its contents.

Entry: Resource list and SKILL.md outline from Step 2.

Actions:

1. Create the skill folder following the structure above. If scripts/init_skill.py is available in the environment, use it as a scaffolding accelerator:

   scripts/init_skill.py <skill-name> --path <output-directory>
   

   Otherwise, create the folder and SKILL.md manually.

2. Write bundled resources first — scripts, references, assets. Test scripts by running them. Delete any scaffolding files not needed.

3. Write SKILL.md:

   • Frontmatter: Follow references/description-authoring.md for the description formula
   • Body: Use imperative/infinitive form. Structure by workflow steps or task categories.
   • Keep the body lean — point to references for depth
   • Validate against references/validation-checklist.md to ensure the skill meets all structural requirements

4. Delete unused scaffolding — remove example files and empty directories.

Exit: Complete skill folder with all resources and SKILL.md.

4. Test

Validate triggering and output quality.

Entry: Complete skill from Step 3.

Actions:

• Run triggering tests (positive and negative prompts)
• Run functional tests on real tasks
• Compare results against baseline (no skill)

See references/testing-iteration.md for detailed testing methodology and success criteria.

Exit: Skill triggers on 9 out of 10 relevant prompts and produces consistent output.

5. Iterate

Refine based on real usage.

Entry: Test results or user feedback.

Actions:

• Diagnose issues: undertriggering, overtriggering, or execution failures
• Apply targeted fixes per references/testing-iteration.md
• Re-test affected areas

Exit: Skill meets success criteria across real-world usage.

Packaging

Package a finished skill as a .skill file (zip with .skill extension). If scripts/package_skill.py is available, use it — it validates and packages automatically:

scripts/package_skill.py <path/to/skill-folder> [output-directory]

Otherwise, zip the skill folder manually ensuring SKILL.md is at the root of the archive.

Reference Guides

Consult these based on the skill's needs:

• Description and triggers: references/description-authoring.md — formula, trigger phrases, negative triggers, hard constraints
• Workflow patterns: references/workflows.md — sequential, multi-service, iterative, context-aware, domain intelligence
• Output patterns: references/output-patterns.md — templates and example-based output guidance
• Testing and iteration: references/testing-iteration.md — triggering tests, functional tests, performance metrics, diagnostics
• Validation checklist: references/validation-checklist.md — structural requirements every skill must meet
• Troubleshooting: references/troubleshooting.md — common failures and resolution paths

Examples

Positive Trigger

User: "Create a new skill for converting PDFs to markdown with reusable scripts."

Expected behavior: Follow this skill's workflow — understand use cases, plan resources, build the skill.

Non-Trigger

User: "Find and fix a TypeScript type error in src/api/client.ts."

Expected behavior: Do not use this skill. Choose a more relevant skill or proceed directly.

Troubleshooting

Created Skill Does Not Trigger

• Error: The skill is not selected when expected.
• Cause: Description lacks specific trigger phrases or is too vague.
• Solution: Rewrite description following references/description-authoring.md.

Created Skill Is Too Verbose

• Error: SKILL.md exceeds 5,000 words or fills excessive context.
• Cause: Detailed content belongs in references, not the body.
• Solution: Move detailed content to references/ files. Keep SKILL.md as a lean workflow guide.

Output Is Inconsistent Across Sessions

• Error: Skill produces different quality results each time.
• Cause: Instructions are ambiguous or lack explicit validation steps.
• Solution: Add concrete examples, exact commands, and verification steps. See references/troubleshooting.md.