Menu
Use when creating, editing, splitting, renaming, or reviewing Copilot skills in this dotfiles repo.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when ingesting, refreshing, listing, searching, or deleting a local corpus with Blackbird code search and `gh blackbird search --fileset`.
Use when reaching for `gh blackbird` (Blackbird code search) for cross-repo lexical, symbol, or semantic search on GitHub — finding callers, ownership, or how systems work without cloning.
Use when creating a GitHub pull request, or when updating an existing PR's title or body so it matches what the code actually does.
Use when authoring or substantially editing a design doc, architecture doc, or subsystem explanation — the "here's what's there and why" companion to an ADR's terse decision record.
Use when creating a repo-tracked multi-agent planning PR for a large project, especially when phases, living docs, parallel agent prompts, and cross-PR coordination are needed.
Use when about to call a library, crate, or framework API you haven't verified, when a dependency's behavior is surprising, when training-data memory might be stale, or when investigating how a dependency actually behaves.
| name | skill-author |
| description | Use when creating, editing, splitting, renaming, or reviewing Copilot skills in this dotfiles repo. |
Create small, searchable user-level Copilot skills that encode durable judgment the user wants across repos.
A skill is reusable workflow guidance, not a diary entry and not a substitute for app behavior. It should help a future agent decide when to load it and how to behave differently after reading it.
Create or update a dotfiles skill when the guidance is:
Do not create a dotfiles skill for:
Use this layout unless the skill needs something simpler:
---
name: short-hyphen-name
description: Use when concrete triggering condition, symptom, or task applies.
---
# Human Title
One or two sentences with the core idea.
## When to use
Specific triggers and non-triggers.
## Rules
The behavior that must change.
## Common mistakes
Likely agent failure modes and how to avoid them.
The description is for discovery. Keep it trigger-focused.
Good:
description: Use when creating, editing, splitting, renaming, or reviewing Copilot skills in this dotfiles repo.
Bad:
description: Explains the full process for writing high-quality skills, including testing, directory layout, examples, and review.
Frontmatter is parsed as YAML. Single-quote the description: value whenever it contains : (colon-space), a ", a leading > | & * ! % @ \``, or #`. Single quotes pass everything through literally; use double quotes only if the value itself contains a single quote.
description: 'Use when reading layout. Symptoms: jank, "ResizeObserver loop" warnings.'
When a skill fails to load, check this first.
Prefer several focused skills over one broad policy blob. A future agent should be able to load the smallest applicable skill and not inherit unrelated workflow.
If a new skill overlaps an existing skill, either:
choosing-workflow.Some user-level skills exist as explicit fallbacks for tasks the user does across many repos but where individual repos may provide a specialized version (Rust coding, alert investigation, postmortems, dependency updates). When both layers exist, the repo-local skill always wins.
When creating or editing a user-level skill that could plausibly have a repo-level specialization:
"Use when ... and the repository has no equivalent skill of its own." This signals fallback intent at discovery time. Current tooling can't enumerate other skills to enforce it, but the phrasing sets the expectation.choosing-workflow/SKILL.md.copilot/templates/<name>/SKILL.md (not copilot/skills/). The template is scaffolding; the user-level skill is the live fallback.Some user-level skills are pure cross-repo personal workflow with no repo-level specialization (e.g. blackbird, pr-author, thinking-about, daily-handoff, copy-editor, delegating-plan-work, planning-multi-agent-projects, skill-author, choosing-workflow). They should not be copied into any project's .copilot/skills/ or .github/skills/.
When authoring one of these, note in the body that the skill is user-level only. The "Skills that should never be mirrored" list in choosing-workflow/SKILL.md is the canonical roster.
To temporarily suppress a skill from ~/.copilot/skills/ without deleting the source, add disabled: true to its frontmatter:
---
name: pr-merge-readiness
disabled: true
description: '...'
---
script/sync-copilot install skips disabled skills and prunes any existing symlink. Remove the line to re-enable. Use this when:
pr-merge-readiness vs agent-merge — those are deliberately distinct: pr-merge-readiness drives to green and stops, agent-merge keeps going through the merge).Find disabled skills with script/skills-status or rg '^disabled: true' copilot/skills/*/SKILL.md.
For skills that enforce discipline, write against the failure mode agents naturally choose under pressure.
Before calling the skill done, ask:
If the skill can be skipped with "this case is different", "being pragmatic", "I'll do it later", or "the spirit still applies", tighten the rule.
When adapting ideas from another public skill or workflow, add or update copilot/skills/README.md with the source, license, and what was adapted. Do not copy large sections verbatim unless the license permits it and attribution is included.