mcpField
C
create-skill

create-skill

github.com/lwlee2608Agent workflows1178 installsUpdated 1d ago
Repository

About create-skill

create-skill guides Agent skill authors in writing quality SKILL.md files. It emphasizes clear activation conditions, focused responsibilities, and concise guidance rather than fixed scripts.

Key features

  1. 01Single-purpose skill design
  2. 02Naming and trigger guidance
  3. 03SKILL.md structure guidance
  4. 04Principles for concise rules
  5. 05Verification and mistake-recording criteria

Use cases

  1. 01Creating a new Agent skill file
  2. 02Improving a skill name and activation condition
  3. 03Trimming long or repetitive skill instructions

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/lwlee2608/agent-skills --skill create-skill

After installing, type/create-skillin Claude Code to confirm it loaded.

Details

From the project README

Create an Agent Skill

Guide the creation of a SKILL.md file that meets quality standards.

Rules

  1. One skill, one job. If you need "and" to describe it, split it.

  2. Name it well. Prefer gerund form (processing-pdfs). Noun phrases (pdf-processing) and action form (process-pdfs) are fine. Avoid vague names like utils or helpers. Spec limits: lowercase, numbers, and hyphens; max 64 chars; no anthropic or claude.

  3. Write the description as a trigger, in third person. It decides when the skill activates. Start with "Use when..." and name a specific condition. First-person phrasing ("I can...") hurts discovery. Max 1024 chars.

    • Bad: "Helps with diagrams."
    • Good: "Use when creating or fixing ASCII box diagrams to ensure proper alignment."

  4. Use this structure:

    ---
name: <kebab-case-name>
description: <"Use when..." trigger description>
user-invocable: true
---

# <Short Title>

<1-2 sentences: what problem this solves.>

## Rules

<Numbered rules, each starting with a bolded imperative.>

## Verification procedure (if applicable)

<Numbered checks the agent runs on its own work.>

## Common mistakes to watch for (only if observed — see rule 9)

<Observed failure modes and how to avoid them.>

  5. Start each rule with a bolded imperative ("Use...", "Never...").

  6. Write guidelines, not scripts. State the goal, constraints, and reason; let the agent choose the steps. Scripts break, cost tokens, and age as models improve. Give exact syntax or steps only for what the agent cannot know: project-specific formats, structured output, and fragile operations like bug workarounds. Cover the 80% case with a preference and a fallback, not every edge case.

  7. Explain the why behind non-obvious rules so the agent can handle edge cases.

  8. Add a verification procedure only for a concrete check the agent would not do on its own (e.g., measuring alignment, running a validator). Skip it otherwise.

  9. Document only observed mistakes. Add "Common mistakes" only with evidence: a user report, a failure in this session, or a documented bug. Otherwise omit it. Guesses add tokens and mislead.

  10. Keep skills independent. Do not assume other skills are loaded.

  11. Keep it short. Aim under 4KB; the hard max is 500 lines. Move detail to sibling files (reference.md, examples.md) linked from SKILL.md. Keep links one level deep, because nested files may be read only partly.

Common mistakes to watch for

  • Inventing common mistakes. Name each entry's evidence or drop it (rule 9).
  • Spelling out standard CLI commands. The agent knows them, and newer models know them better. Write a command only if it is project-specific or a bug workaround (rule 6).
  • Long, dense sentences. They bloat the skill without adding rules. Use short, plain sentences (rule 11).
  • Saying the same thing twice. A verification list that restates the rules, or two rules that overlap. Merge them or point back to the rule (rule 11).

Comments

Markdown supported