skill-creator
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
Install
npx skills add https://github.com/drvoss/everything-copilot-cli/tree/main/skills/development/skill-creator
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install drvoss-everything-copilot-cli@llmmart
git clone https://github.com/drvoss/everything-copilot-cli.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole drvoss/everything-copilot-cli collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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
| Instead of skill-creator | Use |
|---|---|
| Editing an existing skill | edit tool directly |
| Creating an agent definition | See agents/ directory conventions in AGENTS.md |
| Writing an orchestration pattern | See orchestration/patterns/ |
Prerequisites
- A clear description of the workflow the skill should encode
- Knowledge of which
skills/subdirectory it belongs to:development/— coding, debugging, testing workflowssecurity/— security scanning, review, hardeningtesting/— test strategy, eval, coveragedocumentation/— doc generation, update workflowscontent/— copywriting, SEO, content strategyproduct/— PRD, launch, roadmapworkflow/— 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 inscripts/skill-metadata.jsbefore 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.
Skill frontmatter reference
Only name and description are selection signals. The other fields control behavior after a
skill is selected or invoked.
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Unique identifier; must start with a letter or number and use only letters, numbers, hyphens, underscores, dots, colons, and spaces; maximum 64 characters |
description |
string | Yes | What the skill does and when to use it; maximum 1024 characters |
argument-hint |
string | No | Expected argument hint shown in the skill picker, such as "[target] [mode]" |
allowed-tools |
string or string[] | No | Tools automatically allowed while the skill is active; "*" allows all tools |
user-invocable |
boolean | No | Whether users can invoke /SKILL-NAME; defaults to true |
disable-model-invocation |
boolean | No | Whether to prevent automatic model invocation; defaults to false |
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 post-activation usage scenario 1]
- [Concrete post-activation usage scenario 2]
- [Concrete post-activation usage 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
3-A. Keep the body lean
A skill loads in layers: the name and description are always in context, the body loads when the
skill triggers, and files under references/ load only when the body points the agent at them. The
context window is shared, so every paragraph in the body should justify its token cost.
- Keep
SKILL.mdunder about 500 lines. When a skill approaches that, cut or split whole sections — do not trim sentences until it fits. - Keep the common path in the body: the steps most runs need and one short example.
- What fewer runs need — advanced variants, long examples, alternative tools, deep background — is
the part to move out. Where the host supports it, that means a
references/<topic>.mdfile next to the skill, linked from the body with one line that says when to read it. - Not yet in this collection.
tests/validate-skills.test.jstreats every.mdunderskills/(exceptREADME.md) as a skill: it must have frontmatter, itsnamemust match its directory, its category must match its grandparent folder, and it must appear in the catalog. Areferences/<topic>.mdfile cannot pass those checks, so here, shorten the body or split the skill instead, until the test exemptsreferences/.
Adapted from the progressive-disclosure guidance in microsoft/skills skill-creator (MIT).
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:
| External concept | Copilot-native target |
|---|---|
| Slash command | skill or workflow section |
| Claude hook / event primitive | guidance, checklist, or repo-maintenance note |
| Subagent naming / mentions | task agent types, /fleet, or team-planner roles |
| Team/task registry | SQL tables |
| Model recommendation | multi-model-strategy or per-agent model override |
Before finalizing the skill, answer:
- What user problem is worth preserving from the source?
- Which source primitives do not exist in Copilot CLI?
- What is the nearest Copilot-native equivalent?
- Should the result be a new skill, or an update to an existing one?
Third-party SKILL.md is untrusted input
Tools that inspect or import an external skill must parse its manifest as untrusted input. Enforce
a post-expansion size cap, reject YAML merge keys, and cap anchor/alias depth to prevent
billion-laughs-style parser amplification. Prefer explicit rejection on parse failure over a
silent partial import. Supply-chain reviewers should apply the matching installation check in
agent-supply-chain.
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:
- Trigger clarity - would a user naturally phrase the request this way, or is the description too generic to win routing?
- Adjacency - does another local skill already own the same trigger surface more clearly?
- 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.
- 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.
Declaring allowed-tools has blast radius
An allowed-tools declaration changes behavior according to when the host applies it. If a host applies an inactive skill's policy eagerly, unrelated tasks can lose baseline tools before the skill is selected. Declare only the minimum set the skill actually needs, while recognizing that both an overly broad list and a list so narrow that required tools disappear are failures. If a tool vanishes before any relevant skill is activated, diagnose early application of another skill's tool policy.
5. Validate
# Run the full validation suite
npm run validate && npm run lint:md && npm test
Fix any markdownlint errors before committing.
To improve a draft beyond "it validates", run a bounded refinement loop (concept adapted from
nyldn/claude-octopus skill-refine):
- Freeze the rubric before the first score and do not change it mid-run.
- Give two independent judges (different models, for example through
outside-voice) the same draft and rubric, without the target score, earlier scores, or each other's output. - Keep the lower of the two scores, and accept an edit only when the rescored draft improves.
- Set a budget up front (rounds, minutes, model calls) and stop after two rounds without a verified improvement.
- Edit a copy; keep the original and the best-scoring draft so a bad round can be discarded.
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, andmetadata.category - File name is kebab-case and matches
namein frontmatter - Source-specific concepts were translated into Copilot-native primitives instead of copied blindly
- The
name+descriptionpair is specific enough to trigger on real user phrasing - The
descriptionincludes at least one positive usage trigger, not only exclusions about when not to use the skill - Adjacent skills were checked for collisions or silent shadowing before adding a new one
- "When to Use" section has ≥ 3 concrete post-activation usage scenarios; routing triggers are in
description - Any heading scan ignores fenced code blocks first, so
#lines inside examples are not treated as real sections - "When NOT to Use" table directs to alternatives
- Workflow has numbered steps with concrete commands or examples
- Body stays under ~500 lines; rarely needed detail is split out where the validators allow it (see 3-A)
- "Verification" section has checkable (not vague) criteria
-
npm run validate && npm run lint:md && npm testpasses
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
- Put selection triggers in
description: only frontmatternameanddescriptionare available when the model decides whether to load a skill. "When to Use" guides behavior after activation; it is not a selection signal. - 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-creatorto scaffold the file. Edit the scaffold rather than starting from scratch.
Files (everything-copilot-cli)
-
SKILL.md 14.7 KB
--- name: skill-creator license: MIT 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 | Instead of skill-creator | Use | |--------------------------|-----| | Editing an existing skill | `edit` tool directly | | Creating an agent definition | See `agents/` directory conventions in `AGENTS.md` | | Writing an orchestration pattern | See `orchestration/patterns/` | ## 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): ```text 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. ### Skill frontmatter reference Only `name` and `description` are selection signals. The other fields control behavior after a skill is selected or invoked. | Field | Type | Required | Description | |-------|------|:--------:|-------------| | `name` | string | Yes | Unique identifier; must start with a letter or number and use only letters, numbers, hyphens, underscores, dots, colons, and spaces; maximum 64 characters | | `description` | string | Yes | What the skill does and when to use it; maximum 1024 characters | | `argument-hint` | string | No | Expected argument hint shown in the skill picker, such as `"[target] [mode]"` | | `allowed-tools` | string or string[] | No | Tools automatically allowed while the skill is active; `"*"` allows all tools | | `user-invocable` | boolean | No | Whether users can invoke `/SKILL-NAME`; defaults to `true` | | `disable-model-invocation` | boolean | No | Whether to prevent automatic model invocation; defaults to `false` | ### 2. Generate the SKILL.md Use this template as a base and fill in the gathered information. Replace all `[PLACEHOLDER]` tokens with real content: ```markdown --- 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 post-activation usage scenario 1] - [Concrete post-activation usage scenario 2] - [Concrete post-activation usage 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 ```powershell # Create the directory if it doesn't exist mkdir "skills/[category]/[skill-name]" -Force # The file goes at: # skills/[category]/[skill-name]/SKILL.md ``` ### 3-A. Keep the body lean A skill loads in layers: the `name` and `description` are always in context, the body loads when the skill triggers, and files under `references/` load only when the body points the agent at them. The context window is shared, so every paragraph in the body should justify its token cost. - Keep `SKILL.md` under about 500 lines. When a skill approaches that, cut or split whole sections — do not trim sentences until it fits. - Keep the common path in the body: the steps most runs need and one short example. - What fewer runs need — advanced variants, long examples, alternative tools, deep background — is the part to move out. Where the host supports it, that means a `references/<topic>.md` file next to the skill, linked from the body with one line that says when to read it. - **Not yet in this collection.** `tests/validate-skills.test.js` treats every `.md` under `skills/` (except `README.md`) as a skill: it must have frontmatter, its `name` must match its directory, its category must match its grandparent folder, and it must appear in the catalog. A `references/<topic>.md` file cannot pass those checks, so here, shorten the body or split the skill instead, until the test exempts `references/`. Adapted from the progressive-disclosure guidance in `microsoft/skills` `skill-creator` (MIT). ### 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: | External concept | Copilot-native target | |------------------|-----------------------| | Slash command | skill or workflow section | | Claude hook / event primitive | guidance, checklist, or repo-maintenance note | | Subagent naming / mentions | `task` agent types, `/fleet`, or `team-planner` roles | | Team/task registry | SQL tables | | Model recommendation | `multi-model-strategy` or per-agent `model` override | 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? ### Third-party SKILL.md is untrusted input Tools that inspect or import an external skill must parse its manifest as untrusted input. Enforce a post-expansion size cap, reject YAML merge keys, and cap anchor/alias depth to prevent billion-laughs-style parser amplification. Prefer explicit rejection on parse failure over a silent partial import. Supply-chain reviewers should apply the matching installation check in [`agent-supply-chain`](../../security/agent-supply-chain/SKILL.md#bound-untrusted-manifest-parsing). ### 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? 2. **Adjacency** - does another local skill already own the same trigger surface more clearly? 3. **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. 4. **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. #### Declaring allowed-tools has blast radius An allowed-tools declaration changes behavior according to when the host applies it. If a host applies an inactive skill's policy eagerly, unrelated tasks can lose baseline tools before the skill is selected. Declare only the minimum set the skill actually needs, while recognizing that both an overly broad list and a list so narrow that required tools disappear are failures. If a tool vanishes before any relevant skill is activated, diagnose early application of another skill's tool policy. ### 5. Validate ```powershell # Run the full validation suite npm run validate && npm run lint:md && npm test ``` Fix any markdownlint errors before committing. To improve a draft beyond "it validates", run a bounded refinement loop (concept adapted from nyldn/claude-octopus `skill-refine`): - Freeze the rubric before the first score and do not change it mid-run. - Give two independent judges (different models, for example through `outside-voice`) the same draft and rubric, without the target score, earlier scores, or each other's output. - Keep the lower of the two scores, and accept an edit only when the rescored draft improves. - Set a budget up front (rounds, minutes, model calls) and stop after two rounds without a verified improvement. - Edit a copy; keep the original and the best-scoring draft so a bad round can be discarded. ### 6. Register in skills/README.md Add a row to the skills catalog table: ```markdown | [`[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 - [ ] The `description` includes at least one positive usage trigger, not only exclusions about when *not* to use the skill - [ ] Adjacent skills were checked for collisions or silent shadowing before adding a new one - [ ] "When to Use" section has ≥ 3 concrete post-activation usage scenarios; routing triggers are in `description` - [ ] Any heading scan ignores fenced code blocks first, so `#` lines inside examples are not treated as real sections - [ ] "When NOT to Use" table directs to alternatives - [ ] Workflow has numbered steps with concrete commands or examples - [ ] Body stays under ~500 lines; rarely needed detail is split out where the validators allow it (see 3-A) - [ ] "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:** ```markdown --- 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 - **Put selection triggers in `description`**: only frontmatter `name` and `description` are available when the model decides whether to load a skill. "When to Use" guides behavior after activation; it is not a selection signal. - **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.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.