skill-creator

name	skill-creator
description	Guide for creating new skills in this system with proper frontmatter format. Use when adding new skills, updating skill templates, or reviewing skill structure. DO NOT USE FOR: general agent or instruction file customization (use agent-customization) or modifying existing skill logic/content.

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:

1. Length target: ≤60 words total (positive triggers + negative signals combined)
2. Positive triggers: includes "Use when..." with 2–3 specific, distinct scenarios — not generic summary language
3. Negative signals: includes "DO NOT USE FOR:..." with at least one adjacent skill pointer, e.g. (use {other-skill})
4. 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                  

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

1. Be actionable: Provide steps, not just concepts
2. Use [CUSTOMIZE] markers: For project-specific placeholders
3. Keep SKILL.md concise: Route to supporting files for details
4. Template-generic language: No repo-specific references
5. 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 <!-- gotcha-status: new --> — Process-Review will scan and route them upstream

  Example entry in local-gotchas.instructions.md:

  ## brainstorming
  
  <!-- gotcha-status: new -->
  
  | Trigger                                | Gotcha                            | Fix                                        |
  | -------------------------------------- | --------------------------------- | ------------------------------------------ |
  | Asking for options without constraints | Produces unbounded solution space | Add scope constraints before brainstorming |
  

  The <!-- gotcha-status: new --> 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 <!-- gotcha-status: ... --> 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