AgentSkillsCN

skill-creator

这是一项元技能，旨在帮助开发者构建结构清晰、逐步披露的优质技能。当用户想要创建新技能时，可引导他们完成整个流程：明确目的、设定触发条件、编写详细说明、划定行为边界、提供示例参考。如此一来，不仅能确保技能严格遵循仓库规范，还能让用户即刻投入使用。

SKILL.md
--- frontmatter
name: skill-creator
description: |
  Meta-skill for creating well-structured skills with proper progressive
  disclosure. When user wants to create a new skill, guide them through
  the process: purpose, triggers, instructions, guardrails, examples.
  Ensures skills follow the repository conventions and are immediately usable.
allowed-tools: |
  bash: ls, cat, mkdir
  file: read, write

Skill Creator

<purpose> Creating good skills is itself a skill. This meta-skill guides the creation of new skills with proper structure, clear triggers, actionable instructions, and the guardrails that make skills reliable. It's the skill that makes skills. </purpose>

When To Activate

Trigger when:

  • •User says "create a skill for X"
  • •User says "make this into a skill"
  • •User asks how to write a skill
  • •User wants to add to the skill library
  • •skill-forge needs to materialize a skill

The Skill Template

<template> ```markdown --- name: [kebab-case-name] description: | [2-4 sentence description. This is what triggers activation. Be specific about WHEN this skill should activate. Include keywords that would appear in relevant user requests.] allowed-tools: | bash: [list of bash commands needed] file: [read, write, etc.] ---

[Skill Name]

<purpose> [1-2 paragraphs: Why does this skill exist? What problem does it solve? What goes wrong without it? This grounds the skill in real need.] </purpose>

When To Activate

Trigger when:

  • •[Specific condition 1]
  • •[Specific condition 2]
  • •[Specific condition 3]

Do NOT trigger for:

  • •[Exception 1]
  • •[Exception 2]

Instructions

Step 1: [Verb-based title]

[Clear, actionable instructions]

Step 2: [Verb-based title]

[Clear, actionable instructions]

Step 3: [Verb-based title]

[Clear, actionable instructions]

NEVER

  • •[Hard rule 1 - something that would break the skill's purpose]
  • •[Hard rule 2]
  • •[Hard rule 3]

ALWAYS

  • •[Required behaviour 1]
  • •[Required behaviour 2]
  • •[Required behaviour 3]

Examples

Example 1: [Descriptive scenario name]

[Show concrete input and output. Real-world scenario.]

Example 2: [Another scenario]

[Different angle or edge case.]

<failed-attempts> What DOESN'T work: - [Approach that seems reasonable but fails, and why] - [Common mistake to avoid] </failed-attempts>

Why This Skill Exists

[Final grounding: the human cost of not having this skill]

code
</template>

## Instructions

### Step 1: Clarify the Need

Before creating, understand:

What problem does this skill solve? What goes wrong without it? Who/when would use this? Is there an existing skill that covers this?

code

### Step 2: Define the Trigger

The description field is critical - it determines activation:

Good trigger: "When modifying database schemas, force migration planning and rollback strategy before executing any ALTER statements"

Bad trigger: "Help with databases"

code

Be specific. Include keywords. Describe the situation.

### Step 3: Write Clear Instructions

Each step should be:
- Actionable (starts with verb)
- Unambiguous (one interpretation)
- Testable (you can verify it was done)

Good: "List all callers of the function using grep or IDE find-references" Bad: "Consider the dependencies"

code

### Step 4: Add Guardrails

NEVER/ALWAYS sections prevent misuse:

- NEVER: Things that would break the skill's intent
- ALWAYS: Non-negotiable behaviours

NEVER:

  • •Skip the migration plan for "simple" changes
  • •Execute DDL without rollback strategy

ALWAYS:

  • •Test migrations on copy of production data
  • •Include rollback script with every migration
code

### Step 5: Provide Real Examples

Examples should be:
- Concrete (real-looking code/scenarios)
- Complete (show full input → output)
- Varied (different situations)

Include `<failed-attempts>` - what doesn't work and why.

### Step 6: Write the File

Create the skill:

mkdir -p skills/[skill-name]

Write SKILL.md with template

code

## Skill Quality Checklist

<checklist>
Before finalizing, verify:

| Aspect | Check |
|--------|-------|
| Name | Kebab-case, descriptive, not generic |
| Description | Specific triggers, includes keywords |
| Purpose | Clear problem statement, real need |
| Triggers | Specific conditions, includes exceptions |
| Instructions | Actionable steps, unambiguous |
| NEVER | Prevents misuse, hard rules |
| ALWAYS | Required behaviours, non-negotiable |
| Examples | Concrete, complete, varied |
| Failed attempts | Documents what doesn't work |
| Distinct | Not duplicate of existing skill |
</checklist>

## Progressive Disclosure

<progressive-disclosure>
Skills should reveal complexity gradually:

**Layer 1: Metadata** (~100 tokens)
- Name + description
- Always loaded, determines activation
- Must be tight and triggerable

**Layer 2: Instructions** (~500-1000 tokens)
- Loaded when skill activates
- Step-by-step process
- The "how to"

**Layer 3: Resources** (variable)
- Scripts, templates, references
- Executed or loaded on demand
- Not in main context

Keep Layer 1 tight. Most tokens should be in Layer 2.
</progressive-disclosure>

## Common Skill Patterns

<patterns>
**The Checklist** (prove-it, loose-ends)
- Run through verification steps
- Binary pass/fail outcomes

**The Process** (rubber-duck, battle-plan)
- Multi-step workflow
- Each step builds on previous

**The Gate** (you-sure, skill-gate)
- Pause before action
- Require confirmation

**The Transform** (geordie, explain-like)
- Change output format/style
- Modify how information is presented

**The Analysis** (pre-mortem, split-decision)
- Structured evaluation
- Multiple perspectives/options
</patterns>

## NEVER

- Create vague, generic skills ("help with code")
- Skip the examples section
- Write instructions that are just "be careful about X"
- Duplicate existing skills
- Create skills without NEVER/ALWAYS guardrails
- Make triggers too broad (will over-activate)

## ALWAYS

- Include `<failed-attempts>` section
- Test trigger description against likely user prompts
- Keep description under 100 tokens
- Make instructions step-by-step and actionable
- Ground in real problem (not theoretical)

## Examples

### Example 1: User Requests New Skill

User: "Create a skill for handling database migrations"

Let me create a structured skill for database migrations.

First, some questions:

  1. •What goes wrong without this skill? (e.g., data loss, failed deployments)
  2. •What's the trigger? (modifying schemas, adding tables, etc.)
  3. •What's the process you want enforced?

[After gathering info, creates skill following template]

code

### Example 2: Forging from Discovery

skill-forge identifies a non-obvious learning about API rate limiting.

Forging skill: api-rate-limit-handling

[Creates skill with:]

  • •Trigger: When implementing API calls, external service integration
  • •Instructions: Check rate limits, implement backoff, handle 429s
  • •Failed attempts: "Tried simple retry - got banned"
  • •Examples: Concrete rate limiting code
code

## Integration

This skill is the foundation for:
- **skill-forge**: Uses skill-creator to materialize discoveries
- **learn-from-this**: Feeds insights to skill-creator
- All manual skill creation

## Why This Skill Exists

Bad skills are worse than no skills - they activate at wrong times, give vague
guidance, and erode trust in the system. Good skills are force multipliers.

This meta-skill ensures every new skill meets the quality bar. It's the
quality gate for the skill library itself.