skill-creator

Skill Creator

Guide for creating new skills with proper structure and VS Code 1.108+ compatible frontmatter.

When to Use

Creating a new skill for the project
Reviewing existing skills for compliance
Updating skill templates
Onboarding contributors to skill creation

Built-in Creation Commands (VS Code 1.110+)

If you are on VS Code 1.108 or 1.109, skip this section and proceed directly to Required Frontmatter Format below.

VS Code 1.110 ships built-in slash commands for scaffolding customization files:

/create-skill — generates a new skill file
/create-agent — generates a new .agent.md file
/create-prompt — generates a new .prompt.md file
/create-instruction — generates a new .instructions.md file

Recommended workflow: Use the built-in /create-skill (or equivalent) to generate the initial scaffold, then apply this skill to validate and refine the output against project conventions:

Kebab-case name in frontmatter (e.g., my-skill, not MySkill)
description must include usage triggers ("Use when ..." phrasing) for discoverability
Directory structure: skills/{skill-name}/SKILL.md
Required frontmatter fields: name and description only — no unsupported fields

Required Frontmatter Format

---
name: skill-name-kebab-case
description: What the skill does AND when to use it. This description triggers skill discovery in chat.
---

Important:

name and description are the only supported frontmatter fields
No allowed-tools or other fields—they will be ignored
Description should include usage triggers for discoverability

Directory Structure

skills/
└── {skill-name}/
    ├── SKILL.md          # Required: Main skill file with frontmatter
    ├── reference.md      # Optional: Detailed reference material
    ├── templates.md      # Optional: Code/document templates
    └── examples/         # Optional: Example files
        └── ...

Discovery in VS Code (1.108+)

Skill discovery in chat is available in VS Code 1.108+
Ensure agent skills are enabled via chat.useAgentSkills
Discovery quality depends on clear trigger phrasing in description (for example: "Use when ...")

Minimal vs Full Skill Pattern

Use the smallest structure that solves the need:

Minimal Skill: Single SKILL.md with frontmatter, "When to Use," and concise process/checklist
Full Skill: SKILL.md plus supporting references/templates/examples when topic depth or reuse requires it

Start minimal, then split into supporting files only when the core document becomes hard to navigate.

Skill Template

---
name: {skill-name}
description: {What it does}. Use when {trigger conditions}. DO NOT USE FOR: {scenarios where adjacent skills are better} (use {other-skill}).
---

# {Skill Title}

Brief overview of the skill's purpose.

## When to Use

- Bullet list of situations
- That trigger this skill
- Be specific for discoverability

## Core Content

Main guidance, principles, or process.

### Subsections as Needed

Organize by user goals, not by internal structure.

## Project-Specific Configuration

[CUSTOMIZE] Add project-specific details:

- Configuration files to modify
- Team conventions to follow
- Tools and paths used

## Quick Reference

| Item        | Description       |
| ----------- | ----------------- |
| Key concept | Brief explanation |

## See Also

- [Related supporting file](./related-file.md)
- External reference links

## Gotchas

| Trigger                                        | Gotcha                    | Fix                     |
| ---------------------------------------------- | ------------------------- | ----------------------- |
| {observable condition that causes the failure} | {what goes wrong and why} | {actionable correction} |

Description Quality Checklist

Before finalizing a skill's description: field, verify:

Length target: ≤60 words total (positive triggers + negative signals combined)
Positive triggers: includes "Use when..." with 2–3 specific, distinct scenarios — not generic summary language
Negative signals: includes "DO NOT USE FOR:..." with at least one adjacent skill pointer, e.g. (use {other-skill})
Collision check: before finalizing, use grep_search with query your-trigger-word and includePattern: "skills/*/SKILL.md" to check for naming collisions with existing skills. Add explicit "DO NOT USE FOR:" signals to both sides of any conflict.

Writing Guidelines

Prescription Budget (Claude 5)

Before adding imperative guardrails to a skill — MUST/NEVER lists, step-by-step behavioral coaching, forbidden-command enumerations — read Documents/Design/context-engineering-claude-5.md: prescription written for older models degrades Claude 5 output. Keep contracts exact (schemas, marker grammars, enum literals, gate definitions); trim coaching the model no longer needs.

Description Field (Critical for Discovery)

The description determines when the skill appears in suggestions.

Good descriptions:

description: 4-phase debugging process for complex issues. Use when debugging failures, investigating flaky tests, or tracking root causes. DO NOT USE FOR: writing new tests (use test-driven-development), React component test patterns (use ui-testing), or E2E test setup (use webapp-testing).

description: Resilient React component testing strategies focusing on user behavior. Use when writing or reviewing component-level React tests, fixing flaky tests, or establishing React testing patterns. DO NOT USE FOR: Playwright E2E tests (use webapp-testing), canvas game interaction (use browser-canvas-testing), TDD workflow (use test-driven-development), or debugging failures (use systematic-debugging).

Bad descriptions:

description: Debugging guide.  # Too vague, poor discoverability

description: This skill helps with testing things.  # Unclear scope

Frontmatter Validation

Field	Required	Rule	Validation Guidance
`name`	Yes	kebab-case	Use lowercase words separated by hyphens (for example: `test-driven-development`)
`description`	Yes	Include what it does + usage triggers + negative signals	Include "Use when ..." for positive triggers and "DO NOT USE FOR: ... (use {skill})" for at least one negative signal
Other fields	No	Unsupported	Do not add extra fields (for example `allowed-tools`) because they are ignored

Content Principles

Be actionable: Provide steps, not just concepts
Use [CUSTOMIZE] markers: For project-specific placeholders
Keep SKILL.md concise: Route to supporting files for details
Template-generic language: No repo-specific references
Include "When to Use": Explicit trigger conditions

Gotchas Section Guidelines

Always include ≥1 gotcha: No skill should ship without at least one entry
Trigger precision: Use observable conditions, not abstract categories ("Using clickElement on canvas" not "Wrong tool usage")
Fix specificity: Provide actionable commands, skill section references, or concrete alternatives — not "use the right approach"
Use prose alternatives: When a gotcha needs more than 2 sentences, use a callout block or guardrail section instead of cramming it into a table cell
Downstream convention: When agents discover new gotchas while working in a downstream repo, append them to .github/instructions/local-gotchas.instructions.md under a ## {skill-name} heading with format  — Process-Review will scan and route them upstream

Example entry in local-gotchas.instructions.md:
```
## brainstorming



| Trigger                                | Gotcha                            | Fix                                        |
| -------------------------------------- | --------------------------------- | ------------------------------------------ |
| Asking for options without constraints | Produces unbounded solution space | Add scope constraints before brainstorming |
```
The  marker goes on the line immediately before the table header it annotates (not inside the table body). Each gotcha entry must be its own single-row table — do not combine multiple entries in one table, as the  marker tracks state per table, not per row.

Customization Markers

Use [CUSTOMIZE] for sections that need project adaptation:

## Project Configuration

[CUSTOMIZE] Add your project's specific:

- File paths and locations
- Naming conventions
- Team-specific practices

Skill Sizing Guidelines

Size	SKILL.md Lines	Supporting Files	Use Case
Small	50-100	0	Simple process or checklist
Medium	100-200	0-1	Standard methodology
Large	150-250	1-3	Complex topic with patterns

Rule: If SKILL.md exceeds 300 lines, split into supporting files.

Supplement Skills

A supplement skill layers project-specific constraints, themes, or identity guidance on top of an existing hub skill. When a project has one, load both together — the hub skill provides universal principles and the supplement narrows them for the project.

Naming convention: skills/{project}-{hub-skill-name}/SKILL.md — for example, windgust-frontend-design supplements frontend-design.

Supplement ≠ replacement: A supplement adds to the hub skill; it does not replace it. Load both together. If your supplement contradicts hub skill guidance, the benefit of shared defaults is lost.

Description convention: Supplement descriptions should explicitly reference the hub skill they extend — for example: "Supplements frontend-design with {project} brand identity...".

See the frontend-design skill for a worked example and a minimal supplement SKILL.md template.

Validation Checklist

Before committing a new skill:

[ ] Frontmatter has only name and description
[ ] name is kebab-case
[ ] description includes usage triggers
[ ] "When to Use" section is present
[ ] [CUSTOMIZE] markers for project-specific content
[ ] No hardcoded paths or repo-specific references
[ ] Supporting files are referenced from SKILL.md
[ ] Content is actionable, not just conceptual
[ ] Gotchas section present with at least one entry

Example: Complete Skill

---
name: code-review
description: Structured code review process with security and maintainability focus. Use when reviewing PRs, conducting code audits, or establishing review standards. DO NOT USE FOR: line-by-line debugging assistance (use systematic-debugging) or writing test cases from scratch (use test-driven-development).
---

# Code Review Skill

Systematic approach to reviewing code changes.

## When to Use

- Reviewing pull requests
- Conducting security audits
- Establishing team review standards
- Self-review before submitting PRs

## Review Process

### 1. Understand Context

- Read PR description and linked issues
- Understand the goal before reading code

### 2. High-Level Review

- Does the approach make sense?
- Are there architectural concerns?

### 3. Detailed Review

- Security: Input validation, auth, data exposure
- Correctness: Edge cases, error handling
- Maintainability: Readability, naming, complexity

### 4. Provide Feedback

- Be specific and actionable
- Suggest alternatives, don't just criticize
- Distinguish blocking vs. non-blocking

## Project Standards

[CUSTOMIZE] Add your team's review requirements:

- Required reviewers by area
- Review checklist items
- Auto-merge criteria

Gotchas

Trigger	Gotcha	Fix
Using extra frontmatter fields (`allowed-tools`, `applyTo`, custom keys)	Only `name` and `description` are supported; extras are silently ignored	Use only `name` and `description` in frontmatter
Writing a vague description: `description: Debugging guide.`	Skill never appears in suggestions — description fails semantic matching	Include "Use when..." with 2–3 specific observable triggers
Omitting "DO NOT USE FOR:..." negative signals	Skill collides with adjacent skills; wrong one is chosen	Include at least one `DO NOT USE FOR:` pointer with the alternative skill name
Not running a collision check before finalizing	New skill's trigger words shadow an existing skill	`grep_search` trigger phrases across `skills/*/SKILL.md` before finalizing
Using camelCase or PascalCase for `name` (`MySkill`)	Naming convention violation; potential discovery failure	Use kebab-case (`my-skill`) for the `name` frontmatter field
Creating `references/`, `examples/`, and `templates/` directories immediately	File bloat; harder to navigate and maintain	Start with Minimal structure; split only when core document becomes hard to navigate
Creating a supplement that contradicts or overrides the hub skill's defaults	Loses shared hub-skill defaults; teams diverge without a shared baseline	Layer on top — supplements narrow or extend hub guidance, never replace; load both together

01 前言 Front Matter

03 SKILL.md 正文