/omk-skill-creation

name: omk-skill-creation
description: "Create high-quality, production-ready skills from scratch. Trigger when user says 'create skill', 'new skill', 'write a skill', 'make a skill', '创建 skill', '写个 skill', 'skillify', or when packaging a repeated workflow into a reusable skill. Also trigger when reviewing or improving existing skills."

Skill Creation — From Idea to Production

Trigger Examples

• "把这个重复流程做成 skill"
• "create a new skill for code review"
• "帮我写一个 SEO 研究的 skill"
• "review and improve this skill"
• "这个工作流应该 skillify"

Philosophy

> Context window is a public good. Only add what the agent doesn't already know.

A skill is an onboarding manual for the agent — after reading it, the agent knows your process, standards, and preferences without re-teaching every session.

Phase 0: Should This Be a Skill?

Before writing anything, decide the right mechanism:

| Signal | Mechanism | |--------|-----------| | Rule needed in EVERY conversation | AGENTS.md / rules.md | | Must run automatically on events | Hook (gate/ or feedback/) | | Teaches agent a specific workflow | **Skill** ← you are here | | Gives agent a new tool/API | MCP server | | Needs isolated context execution | Subagent |

**Skill ROI threshold**: Will this workflow run ≥3 times? If not, just explain in conversation.

Phase 1: Design (Before Writing SKILL.md)

Step 1: Define Use Cases

Write 3-5 concrete user prompts that should trigger this skill. Not abstract descriptions — actual sentences users will type:

Example for a "daily planning" skill:
- "plan my day"
- "start work"
- "今天做什么？"
- "morning routine"
- "daily standup prep"

These prompts shape everything: skill name, description, input/output, workflow steps.

Step 2: Define Input → Output

| Question | Answer | |----------|--------| | What does the user provide? | (file, URL, text, nothing?) | | What does the skill produce? | (file, report, action, decision?) | | What format? | (markdown, JSON, email, code?) |

Step 3: Choose Pattern

| Need external APIs/real-time data? | → Pattern C: Skill + MCP | |-------------------------------------|--------------------------| | Need deterministic computation? | → Pattern B: Prompt + Scripts | | Agent judgment alone is enough? | → Pattern A: Prompt-Only |

**When in doubt, start with Pattern A.** Add scripts later if needed.

Step 4: Choose Freedom Level

| Fragility | Freedom | Example | |-----------|---------|---------| | High (DB migration, deploy) | Low — exact commands, no variation | `Run exactly: python migrate.py --verify` | | Medium (code generation) | Medium — template with parameters | Pseudocode + config options | | Low (code review, writing) | High — guidelines + heuristics | "Check for X, Y, Z" |

Phase 2: Write SKILL.md

File Structure

my-skill/
├── SKILL.md              # Required. < 500 lines
├── scripts/              # Optional. Deterministic code
├── references/           # Optional. Loaded on demand
└── assets/               # Optional. Templates, data

Frontmatter (Critical)

The description determines whether the skill ever triggers. Agent defaults to NOT triggering — your description must be "pushy."

---
name: kebab-case-name        # ≤64 chars, lowercase + hyphens only
description: >                # ≤1024 chars, third person
  [What it does]. Trigger when user says [keyword1], [keyword2],
  [keyword3], or [scenario description]. Also trigger when
  [implicit trigger condition].
---

**Rules:**

• Third person always ("Processes X", not "I help you" or "You can use this")
• First sentence: what it does (purpose)
• Second sentence: explicit trigger keywords (list actual user phrases)
• Third sentence: implicit triggers (file types, contexts, patterns)
• Be specific > be brief. Use all 1024 chars if needed

**Bad**: `description: Helps with data tasks` **Good**: `description: Analyze sales/revenue CSV files to find patterns and calculate metrics. Trigger when user mentions sales data, revenue analysis, profit margins, or uploads xlsx/csv with financial column headers.`

Body Structure

## Trigger Examples
- "realistic user prompt 1"
- "realistic user prompt 2" (different language/style)
- "realistic user prompt 3"
- "realistic user prompt 4"
- "realistic user prompt 5"

## [Workflow Steps]
Step 1: ...
Step 2: ...

## [Rules / Constraints]

## [Output Format] (if applicable)

Writing Principles

1. **Concise is key** — Claude is smart. Only add what it doesn't know. Challenge every paragraph: "Does this justify its token cost?" 2. **Reasons > commands** — "Show command before executing, because users need to verify safety" beats "ALWAYS show commands. NEVER execute directly." 3. **Examples > explanations** — One input/output pair teaches more than three paragraphs of description 4. **One default, one escape hatch** — Don't list 5 options. Pick the best one, mention the alternative for edge cases 5. **Consistent terminology** — Pick one term, use it everywhere. Not "endpoint/URL/route/path" interchangeably

Progressive Disclosure

• SKILL.md = overview + navigation (< 500 lines)
• `references/` = detailed docs, loaded on demand
• `scripts/` = executable code, runs without entering context
• Reference depth: max 1 level. SKILL.md → reference.md. Never reference.md → sub-reference.md
• For references > 100 lines, add a table of contents at top

Phase 3: Test

Write Messy Test Prompts

Real users make typos, use slang, forget file names. Test with realistic prompts, not clean ones:

# Good (realistic)
"ok so my boss sent me this xlsx (its in downloads, called
something like 'Q4 sales final FINAL v2.xlsx') and she wants
profit margin as a percentage"

# Bad (too clean)
"Please analyze the sales data in the uploaded Excel file
and add a profit margin column"

Iteration Loop

1. Run skill with test prompts 2. Did it trigger? If not → fix description 3. Did it produce correct output? If n