version: "1.0.1" name: skill-creator description: Use when you want to create a new SKILL.md file — describe a workflow and this skill generates a properly structured, frontmatter-complete SKILL.md that follows this repository's conventions metadata: category: development agent_type: general-purpose

Skill Creator

A meta-skill that produces new SKILL.md files. Describe what the skill should do, and this skill generates a complete, convention-compliant SKILL.md file ready to commit.

When to Use

• You want to add a new skill but are unsure of the required structure
• You have a workflow in mind and want to formalize it as a skill
• You are migrating a skill from another source and need to adapt it to this repo's format
• You need to translate an external slash-command or Claude-oriented pattern into Copilot-native primitives
• Bootstrapping multiple skills quickly for a new domain

When NOT to Use

Prerequisites

• A clear description of the workflow the skill should encode
• Knowledge of which skills/ subdirectory it belongs to:
• development/ — coding, debugging, testing workflows
• security/ — security scanning, review, hardening
• testing/ — test strategy, eval, coverage
• documentation/ — doc generation, update workflows
• content/ — copywriting, SEO, content strategy
• product/ — PRD, launch, roadmap
• workflow/ — process workflows (research, release, sprint)
• copilot-exclusive/ — GitHub Copilot CLI-specific features
• Confirm the category already exists in this repository. Research-focused skills

currently live under workflow/; adding a new category requires updating the shared allowlist in scripts/skill-metadata.js before introducing new files.

Workflow

1. Gather requirements

Ask (or determine from context):

1. What is the skill name? (kebab-case, e.g., `api-versioning-guide`)
2. What category does it belong to? (development / security / testing / etc.)
3. What triggers this skill? (When should an agent use it?)
4. What is the step-by-step workflow?
5. What are the verification criteria (Done When)?
6. Are there any anti-patterns or common mistakes to warn about?

Important: the description is the first routing clue an AI sees when deciding whether to load a skill. If it is vague, the skill may be correct but still fail to trigger when the user actually needs it.

2. Generate the SKILL.md

Use this template as a base and fill in the gathered information. Replace all [PLACEHOLDER] tokens with real content:

---
name: [kebab-case-name]
description: Use when [trigger condition] — [one-line description of output]
metadata:
  category: [category]
  agent_type: general-purpose
  # Optional when clearly useful:
  # copilot_feature: "[Copilot CLI feature or primitive]"
  # origin: "ported and adapted from [source]"
---
 
# [Title Case Name]
 
[One paragraph describing the skill's purpose and what it produces.]
 
## When to Use
 
-[Concrete trigger scenario 1]
-[Concrete trigger scenario 2]
-[Concrete trigger scenario 3]
 
## When NOT to Use
 
| Instead of [skill-name] | Use |
|-------------------------|-----|
| [alternative scenario] | [alternative skill or approach] |
 
## Prerequisites
 
-[Required setup or knowledge]
-[Tools or permissions needed]
 
## Workflow
 
### 1. [Step name]
 
[Description of what to do in this step.]
 
### 2. [Step name]
 
...
 
## Examples
 
### [Example scenario]
 
[Concrete example showing input and output]
 
## Common Rationalizations
 
| Rationalization | Reality |
|----------------|---------|
| "[excuse to skip the skill]" | [why that reasoning is wrong] |
 
## Red Flags
 
-[Warning sign that something is wrong]
-[Another warning sign]
 
## Verification
 
-[ ] [Concrete, checkable criterion 1]
-[ ] [Concrete, checkable criterion 2]
 
## Tips
 
-[Practical tip]
-[Link to related skills if applicable]

3. Place the file

# Create the directory if it doesn't exist
mkdir "skills/[category]/[skill-name]" -Force
 
# The file goes at:
# skills/[category]/[skill-name]/SKILL.md

4. Port External Skills Intentionally

If the source came from Claude Code, an awesome list, or another skill collection, adapt the concept instead of copying source-specific primitives verbatim.

Use this translation rubric:

Before finalizing the skill, answer:

1. What user problem is worth preserving from the source?
2. Which source primitives do not exist in Copilot CLI?
3. What is the nearest Copilot-native equivalent?
4. Should the result be a new skill, or an update to an existing one?

4-A. Audit activation and collision risk

Before you keep a new name + description pair, test whether the skill is actually likely to load and whether it would shadow an adjacent skill.

Check at least:

1. Trigger clarity - would a user naturally phrase the request this way, or is the

description too generic to win routing?

1. Adjacency - does another local skill already own the same trigger surface more

clearly?

1. Prompt simulation - try 3-5 realistic phrasings, including one terse

code-oriented phrasing and one broader planning/review phrasing. If two skills seem equally plausible, sharpen the description or merge the concept into the existing skill instead of adding another near-duplicate.

1. Cross-model robustness - avoid descriptions that only make sense in one host's

naming conventions. Prefer portable verbs like "review", "audit", "debug", "plan", or "verify" over vendor-specific slash-command language.

4-B. Watch for steering-by-omission failure modes

Language you think of as "off" can still steer the agent. Check drafts against these two related failure modes before finalizing:

• Negation — naming what not to do drags the forbidden behavior into context and makes it

more available, not less (the "don't think of an elephant" effect). A skill full of "don't do X" instructions primes the agent to think about X. Prefer stating the positive version: instead of "don't skip verification," write "verify before implementing."

• Negative space — every decision a skill declines to make is silently delegated to the

agent's priors rather than left neutral. An omission is never truly neutral. Read a draft for its silences and decide each one deliberately: either fill the gap explicitly, or leave it open as a documented branch point (e.g., "if the tracker is not GitHub, ask which workflow applies" rather than saying nothing).

Apply this check during drafting, not just at review time — a skill written entirely as prohibitions ("never do A, never do B, don't assume C") is a sign the positive process was never actually specified.

5. Validate

# Run the full validation suite
npm run validate && npm run lint:md && npm test

Fix any markdownlint errors before committing.

6. Register in skills/README.md

Add a row to the skills catalog table:

| [`[skill-name]`]([category]/[skill-name]/SKILL.md) | [One-line description] |

Quality Checklist

After generating a new skill, verify:

• [ ] Frontmatter has name, description, and metadata.category
• [ ] File name is kebab-case and matches name in frontmatter
• [ ] Source-specific concepts were translated into Copilot-native primitives instead of copied blindly
• [ ] The name + description pair is specific enough to trigger on real user phrasing
• [ ] Adjacent skills were checked for collisions or silent shadowing before adding a new one
• [ ] "When to Use" section has ≥ 3 concrete trigger scenarios
• [ ] "When NOT to Use" table directs to alternatives
• [ ] Workflow has numbered steps with concrete commands or examples
• [ ] "Verification" section has checkable (not vague) criteria
• [ ] npm run validate && npm run lint:md && npm test passes

Usage Examples

Example: Creating a rate-limiting-guide skill

Input description:

"A skill for adding rate limiting to Express APIs. Covers middleware selection, Redis-backed limits, and testing."

Skill creator output skeleton:

---
name: rate-limiting-guide
description: Use when adding rate limiting to an API — selects the right middleware, configures Redis-backed limits, and writes integration tests
metadata:
  category: development
  agent_type: general-purpose
---
 
# Rate Limiting Guide
...

Placed at: skills/development/rate-limiting-guide/SKILL.md

Usage Tips

• Start with triggers: the "When to Use" section determines whether agents will

actually reach for this skill. Make triggers concrete and scenario-specific.

• Treat the description like routing metadata: it is short, but it carries the most

leverage. If it does not clearly beat adjacent skills on specificity, rewrite it.

• Verification criteria drive quality: vague verifications like "it works" are useless.

Write criteria an agent can check with a command or an observable outcome.

• Port the job, not the syntax: preserve the workflow value from upstream sources,

but translate slash commands, hooks, and agent primitives into Copilot CLI equivalents.

• Keep stable lessons separate from churn: if repeated reviews keep teaching the same

high-level correction, consider one clearly marked longitudinal guidance subsection instead of scattering tiny edits across the whole skill.

• Link related skills: skills are more powerful when chained. Cross-reference skills

in "See Also" or "Tips" sections.

• Use this skill first: before creating any new skill in this repository, run

skill-creator to scaffold the file. Edit the scaffold rather than starting from scratch.