Converting Prompts to Skills

Markdown
---
name: converting-prompts-to-skills
description: Converts a system prompt describing someone's expertise or methodology into a complete set of Claude Code agent skill files (SKILL.md format with YAML frontmatter). Use when given a persona, system prompt, job description, or expertise narrative that needs to be decomposed into one or more actionable, trigger-based skill files.
---

Quick Start

Given a system prompt (persona description, job description, or expertise narrative), produce one or more `SKILL.md` files. Each file is self-contained: YAML frontmatter + Quick Start + Workflow + Examples + Best Practices + Common Pitfalls.

Minimal example — input: "You are a senior SQL performance tuner who diagnoses slow queries using EXPLAIN plans."

Output file: `diagnosing-slow-queries/SKILL.md`

```yaml
---
name: diagnosing-slow-queries
description: Diagnoses slow SQL queries using EXPLAIN plans and recommends indexing or rewrite fixes. Use when a query is reported as slow, timing out, or when asked to optimize database performance.
---

...followed by Workflow, Examples, etc.

Workflow

Progress:

• Step 1: Parse the system prompt for distinct skill boundaries
• Step 2: Name each skill (gerund-form, kebab-case)
• Step 3: Write trigger-focused descriptions
• Step 4: Extract the methodology into Quick Start + Workflow steps
• Step 5: Fabricate 2-3 concrete Examples per skill from domain context
• Step 6: Add Best Practices and Common Pitfalls from implicit/explicit expertise cues
• Step 7: Decide single-skill vs. multi-skill decomposition
• Step 8: Output files with clear path headers

Step 1: Parse for skill boundaries Scan the prompt for:

• Distinct verbs/tasks ("you analyze X, write Y, review Z" → 3 candidate skills)
• Distinct deliverables (a report, a plan, a critique)
• Distinct triggers (different situations that invoke different behavior)

Rule of thumb: if two tasks share workflow steps and tools, merge into one skill. If they have independent inputs/outputs and could be invoked separately, split.

Step 2: Name skills

• Gerund form, kebab-case, ≤64 chars
• Name the activity, not the role: reviewing-pull-requests not senior-engineer

Step 3: Write descriptions

• Third person, present tense
• Formula: [Verb]s [object] [method]. Use when [trigger 1], [trigger 2], or [trigger 3].
• Mine the system prompt for trigger language ("when asked to...", "whenever a client...")
• If no explicit triggers exist, infer natural invocation scenarios from the deliverable

Step 4: Extract methodology

• Pull any numbered steps, phases, or principles stated in the prompt verbatim where possible
• If the prompt is narrative/implicit, reverse-engineer a plausible expert workflow (3-7 steps)
• Quick Start must be immediately actionable — no throat-clearing

Step 5: Fabricate examples

• Use the domain terminology from the original prompt
• Keep input/output pairs short but realistic
• Minimum 2 examples per skill

Step 6: Best practices & pitfalls

• Best practices = things the expert "always does" (explicit or implied)
• Pitfalls = things a novice would get wrong (infer from what the expert emphasizes or warns against)

Step 7: Single vs. multi-skill decision

Signal	Decision
One core task, consistent inputs/outputs	1 skill file
2-4 related tasks sharing domain but different deliverables	2-4 skill files in a shared directory
Broad role with 5+ distinct responsibilities	Build a skill suite: one SKILL.md per responsibility, named by directory e.g. skills/reviewing-code/SKILL.md, skills/writing-tests/SKILL.md

Step 8: Output format For multi-skill output, prefix each file clearly:

### FILE: skills/<skill-name>/SKILL.md
---
name: ...
description: ...
---
<body>

Examples

Example 1 (single-skill input): Input: "You are a copyeditor who tightens prose, fixes grammar, and flags passive voice, always preserving the author's voice." Output: One file, tightening-prose/SKILL.md, with description: "Tightens prose, fixes grammar, and flags passive voice while preserving author voice. Use when editing drafts, blog posts, or manuscripts for clarity and concision." Workflow covers: read-through, sentence-level edits, passive-voice flagging, voice-preservation check.

Example 2 (multi-skill input): Input: "You are a startup CFO. You build financial models, prepare board decks, negotiate term sheets, and manage runway." Output: Four files:

• building-financial-models/SKILL.md
• preparing-board-decks/SKILL.md
• negotiating-term-sheets/SKILL.md
• managing-runway/SKILL.md

Each with independent Quick Start/Workflow/Examples, cross-referencing shared context (e.g., runway numbers feed into board decks) via a one-line "See also" note rather than duplicating content.

Example 3 (ambiguous scope input): Input: "You help people with their careers." Output: Treat as too broad — decompose into the most common, concrete sub-skills implied: writing-resumes/SKILL.md, preparing-for-interviews/SKILL.md, negotiating-offers/SKILL.md. Note in output that scope was inferred and narrower/broader decomposition is possible.

Best Practices

• Prefer more, smaller skill files over one bloated file — each should be independently invocable
• Always derive the description trigger phrases from the actual prompt language when present
• Keep each file ~500 lines max; if a workflow needs more, split into a core skill plus reference sub-files
• Preserve domain-specific vocabulary and tone from the source prompt in Examples
• When the source prompt gives explicit steps/rules, quote/adapt them rather than inventing generic ones
• Name the directory to match the skill name exactly (skill-name/SKILL.md)

Common Pitfalls

• Don't create one giant skill for a multi-responsibility persona — it becomes undiscoverable and hard to trigger correctly
• Don't write first/second-person descriptions ("I help you..." / "You will...") — always third person
• Don't pad with generic advice disconnected from the source prompt's actual domain
• Don't omit trigger phrases from descriptions — a skill without clear "use when" guidance won't be selected correctly
• Don't invent tool/API names not implied by the source prompt
• Don't exceed the frontmatter limits (name ≤64 chars, description ≤1024 chars)