Copilot CLI Skills: A Practical Guide With Examples for Every Role

---
name: my-skill
description: Does a specific thing. Use this when asked to do that specific thing.
---

Instructions for Copilot go here. Be specific. Be prescriptive.

---
name: release-notes-drafter
description: Drafts release notes by analyzing recent commits and pull requests. Use this when asked to create release notes, write a changelog, or prepare a release summary.
---

## Instructions

Generate release notes for the specified version or date range. Follow these steps:

1. Use the GitHub MCP server tools to list merged pull requests since the last release tag.
2. Categorize changes into the following sections (skip empty sections):
   - **Breaking Changes** - Any changes that break backwards compatibility
   - **New Features** - New functionality
   - **Bug Fixes** - Defect corrections
   - **Performance** - Performance improvements
   - **Documentation** - Docs-only changes
   - **Dependencies** - Dependency updates
   - **Internal** - Refactoring, CI changes, test improvements
3. For each entry, include:
   - A one-line summary written for end users (not developers)
   - The PR number as a link
   - The author's GitHub handle
4. Include a "Contributors" section at the bottom listing all unique contributors.
5. Write the output in Markdown format suitable for a GitHub Release.

## Formatting Rules

- Use past tense ("Added", "Fixed", "Removed")
- Do not include commit hashes in the user-facing notes
- If a PR title is unclear, read the PR description to write a better summary
- Group related PRs under a single bullet when they are part of the same feature

---
name: meeting-notes
description: Structures raw meeting notes into a formatted summary with action items. Use this when asked to clean up meeting notes, format meeting notes, or organize notes from a meeting.
---

## Instructions

Take the raw meeting notes provided and restructure them into the following format:

### Output Format

## Meeting: [Topic]
**Date:** [date]
**Attendees:** [list]

### Summary
[2-3 sentence executive summary of the meeting]

### Key Discussion Points
- [Bullet points of major topics discussed]

### Decisions Made
- [Numbered list of decisions with brief rationale]

### Action Items
| Owner | Action | Due Date | Priority |
|-------|--------|----------|----------|
| @name | task   | date     | H/M/L    |

### Open Questions
- [Items that need follow-up or were unresolved]

### Next Meeting
[Date/time if discussed]

## Rules

- Extract action items even if they are buried in discussion text
- If an owner is not explicitly assigned, note it as "TBD"
- If no due date is mentioned, leave the field as "TBD"
- Prioritize decisions and action items over general discussion
- Keep the summary concise. The reader should understand the meeting outcome in 30 seconds.

---
name: adr-writer
description: Creates Architecture Decision Records (ADRs) following the team's standard template. Use this when asked to write an ADR, document an architecture decision, or create a decision record.
---

## Instructions

Create an Architecture Decision Record using the following template. Save the file as `docs/adr/NNNN-title.md` where NNNN is the next sequential number. Check existing files in `docs/adr/` to determine the next number.

### Template

# ADR-NNNN: [Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]

## Context
[What is the issue? What forces are at play? Be specific about constraints,
requirements, and the problem being solved.]

## Decision
[What is the change being proposed or decided? State it clearly in one sentence,
then elaborate.]

## Alternatives Considered
### [Alternative 1]
- **Pros:** ...
- **Cons:** ...

### [Alternative 2]
- **Pros:** ...
- **Cons:** ...

## Consequences
### Positive
- [What becomes easier?]

### Negative
- [What becomes harder? What are the tradeoffs?]

### Neutral
- [What changes that is neither good nor bad?]

## References
- [Links to relevant docs, RFCs, discussions, or prior ADRs]

## Rules

- Always check the `docs/adr/` directory for existing ADRs before choosing a number
- Status should default to "Proposed" unless told otherwise
- Include at least two alternatives. "Do nothing" counts as an alternative.
- Consequences must include at least one negative consequence. Every decision has tradeoffs. If you cannot identify one, think harder.
- Write for a reader six months from now who has no context on this decision

---
name: sql-migration
description: Generates database migration files following team conventions. Use this when asked to create a migration, alter a table, add a column, create an index, or make any schema change.
---

## Instructions

Generate a database migration following these project conventions:

### File Naming
- Pattern: `migrations/YYYYMMDDHHMMSS_description.sql`
- Use the current timestamp for the filename
- Description should be snake_case and descriptive (e.g., `add_index_users_email`)

### Migration Structure
Every migration file must contain both an UP and DOWN section:

```sql
-- migrate:up
-- Description: [what this migration does]
-- Author: [GitHub handle]
-- Ticket: [ticket ID if provided]

[SQL statements here]

-- migrate:down
-- WARNING: This will [describe what rollback does]

[Rollback SQL statements here]
```

### Rules
1. **Never** use `DROP TABLE` or `DROP DATABASE` without explicit user confirmation
2. **Always** include a rollback in the down section. If a rollback is destructive (data loss), add a comment warning about it.
3. Use `IF NOT EXISTS` / `IF EXISTS` where supported by the target database
4. For adding columns, always specify a DEFAULT value or explicitly note that NULL is intentional
5. For creating indexes, use `CREATE INDEX CONCURRENTLY` on PostgreSQL to avoid table locks
6. Include a comment block at the top explaining the purpose of the migration
7. If the migration modifies data (not just schema), add a count query before and after to verify the expected number of rows were affected

### Common Patterns

**Adding a column:**
```sql
ALTER TABLE table_name ADD COLUMN column_name type DEFAULT value;
```

**Adding an index:**
```sql
CREATE INDEX CONCURRENTLY idx_table_column ON table_name (column_name);
```

**Renaming a column:**
```sql
ALTER TABLE table_name RENAME COLUMN old_name TO new_name;
```

---
name: pipeline-validator
description: Validates data pipeline configurations and suggests improvements. Use this when asked to review a pipeline, validate ETL config, check a DAG, or audit data pipeline code.
---

## Instructions

Review the specified data pipeline configuration or code and check for the following:

### Validation Checklist

1. **Schema validation**
   - Are input and output schemas explicitly defined?
   - Are data types specified for all fields?
   - Are nullable fields documented?

2. **Error handling**
   - Is there a dead letter queue or error output for failed records?
   - Are retries configured with backoff?
   - Is there alerting on pipeline failure?

3. **Idempotency**
   - Can the pipeline be re-run safely without duplicating data?
   - Are there deduplication keys defined?
   - Is there a watermark or checkpoint mechanism?

4. **Performance**
   - Are partitioning keys appropriate for the data volume?
   - Are there any full table scans that could be filtered?
   - Is incremental processing used where possible?

5. **Data quality**
   - Are there null checks on required fields?
   - Are there range/format validations on critical fields?
   - Is there row count validation between source and target?

6. **Security**
   - Are credentials stored in a secret manager (not hardcoded)?
   - Is data encrypted in transit and at rest?
   - Are PII fields identified and handled appropriately?

### Output Format

For each issue found, report:
- **Severity:** Critical / Warning / Suggestion
- **Location:** File and line reference
- **Issue:** What is wrong
- **Fix:** Specific recommended change

End with a summary: total issues by severity and an overall assessment.

---
name: notebook-cleaner
description: Cleans and standardizes Jupyter notebooks for sharing or review. Use this when asked to clean a notebook, prepare a notebook for review, or standardize notebook formatting.
---

## Instructions

Clean the specified Jupyter notebook (.ipynb file) by performing the following:

### Cleanup Steps

1. **Remove outputs** - Clear all cell outputs and execution counts. Notebooks should be committed clean.
2. **Order imports** - Ensure all import statements are in the first code cell, organized as:
   - Standard library imports
   - Third-party imports
   - Local/project imports
3. **Add section headers** - Ensure the notebook has Markdown cells with headers that follow this structure:
   - `# Title` - Notebook purpose
   - `## Setup` - Imports and configuration
   - `## Data Loading` - Where data is read
   - `## Analysis` or `## Processing` - The main work
   - `## Results` or `## Output` - Findings or outputs
   - `## Conclusions` (if applicable)
4. **Check for hardcoded paths** - Flag any absolute file paths. Suggest using relative paths or environment variables.
5. **Check for credentials** - Flag any API keys, passwords, or tokens. Suggest using environment variables or a `.env` file.
6. **Add docstrings** - Ensure any function definitions have docstrings explaining parameters and return values.
7. **Remove dead code** - Flag commented-out code blocks and empty cells.

### Output

Provide a summary of changes made and any items that need manual attention.

### Rules
- Do not modify the analytical logic or results
- Preserve all Markdown explanations
- If the notebook is too large to process in one pass, work section by section

---
name: pr-review
description: Performs a structured code review against team standards. Use this when asked to review a PR, review code changes, do a code review, or check a pull request.
---

## Instructions

Review the code changes using the following structured checklist. Use the GitHub MCP server tools to read the PR diff and details.

### Review Checklist

#### Correctness
- [ ] Does the code do what the PR description says it does?
- [ ] Are edge cases handled?
- [ ] Are error paths handled gracefully?
- [ ] Are there any obvious bugs or logic errors?

#### Tests
- [ ] Are there tests for new functionality?
- [ ] Do existing tests still pass?
- [ ] Are edge cases tested?
- [ ] Is test coverage adequate for the change size?

#### Security
- [ ] No secrets or credentials in the diff
- [ ] User inputs are validated and sanitized
- [ ] No SQL injection vectors
- [ ] No XSS vectors in frontend code
- [ ] Dependencies added are from trusted sources

#### Performance
- [ ] No N+1 query patterns
- [ ] No unnecessary loops over large datasets
- [ ] No blocking calls in async code paths
- [ ] Database queries use appropriate indexes

#### Maintainability
- [ ] Code is readable without extensive comments
- [ ] Functions are appropriately sized
- [ ] No duplicated logic that should be extracted
- [ ] Naming is clear and consistent

### Output Format

For each item, mark it as:
- PASS - No issues
- WARN - Minor concern, non-blocking
- FAIL - Must be addressed before merge
- N/A - Not applicable to this change

End with a summary: overall recommendation (Approve / Request Changes / Comment) with rationale.

---
name: test-generator
description: Generates test files with comprehensive test cases following project conventions. Use this when asked to write tests, generate tests, add test coverage, or create unit tests.
---

## Instructions

Generate tests for the specified code. Follow these rules:

### Test Structure
1. Read the source file to understand the public API
2. Determine the test framework by checking existing test files in the project:
   - JavaScript/TypeScript: look for jest.config, vitest.config, or .mocharc
   - Python: look for pytest.ini, pyproject.toml, or setup.cfg
   - Go: use the standard testing package
   - Ruby: look for .rspec or Gemfile for rspec/minitest
3. Create the test file in the corresponding test directory following existing project patterns
4. Name the test file to match the source file (e.g., `user_service.py` -> `test_user_service.py`)

### Test Cases to Generate

For each public function or method, generate:

1. **Happy path** - Normal expected input and output
2. **Edge cases** - Empty inputs, boundary values, nil/null/undefined
3. **Error cases** - Invalid inputs, expected exceptions
4. **Type variations** (where applicable) - Different valid types that the function accepts

### Rules
- One assertion per test (prefer focused, descriptive tests)
- Use descriptive test names: `test_create_user_with_duplicate_email_raises_conflict`
- Do not mock what you do not own (mock your interfaces, not third-party libraries)
- Set up test data in each test or use a shared fixture. Do not rely on test execution order.
- If the function has side effects (database, file system, network), note which tests need mocking
- Include at least one integration test suggestion as a comment at the bottom of the file

---
name: api-scaffolder
description: Scaffolds new REST API endpoints with validation, error handling, and tests. Use this when asked to create an API endpoint, add a new route, scaffold a REST endpoint, or build a CRUD API.
---

## Instructions

Scaffold a new API endpoint by generating the following files. Detect the project's framework and language by reading existing route/controller files.

### Files to Generate

1. **Route/Controller** - The endpoint handler with:
   - Input validation (reject bad requests early)
   - Authentication check (verify the user is authenticated)
   - Authorization check (verify the user has permission)
   - Business logic call (delegate to a service layer)
   - Structured error responses with appropriate HTTP status codes
   - Request/response logging

2. **Service layer** (if the project uses one) - Business logic separated from HTTP concerns

3. **Input validation schema** - Define expected request body, query params, and path params with types and constraints

4. **Tests** - Use the /test-generator skill patterns for the generated code

5. **Route registration** - Add the route to the existing router/app configuration

### Error Response Format

All error responses must follow this structure:

```json
{
  "error": {
    "code": "DESCRIPTIVE_ERROR_CODE",
    "message": "Human readable message",
    "details": {}
  }
}
```

### HTTP Status Code Guide
- 200: Success (GET, PUT, PATCH)
- 201: Created (POST that creates a resource)
- 204: No Content (DELETE)
- 400: Bad Request (validation failure)
- 401: Unauthorized (no/invalid auth)
- 403: Forbidden (valid auth, insufficient permissions)
- 404: Not Found
- 409: Conflict (duplicate resource)
- 422: Unprocessable Entity (valid syntax, semantic error)
- 500: Internal Server Error (catch-all, should be rare)

### Rules
- Never return 200 for errors
- Always validate input before processing
- Sanitize user input before database queries
- Do not expose internal error details to the client in production
- Include rate limiting considerations as a comment if the endpoint is public

---
name: commit-message
description: Generates standardized commit messages from staged changes. Use this when asked to write a commit message, generate a commit message, or create a conventional commit.
---

## Instructions

Analyze the currently staged changes (use `git diff --staged`) and generate a commit message following the Conventional Commits specification.

### Format

```
<type>(<scope>): <subject>

<body>

<footer>
```

### Types
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Formatting, whitespace (no logic change)
- `refactor`: Code change that neither fixes a bug nor adds a feature
- `perf`: Performance improvement
- `test`: Adding or updating tests
- `build`: Build system or dependencies
- `ci`: CI/CD changes
- `chore`: Maintenance tasks

### Rules
- Subject line: max 72 characters, imperative mood ("Add" not "Added" or "Adds"), no period at the end
- Scope: the module, component, or area affected (optional but preferred)
- Body: explain *what* and *why*, not *how*. Wrap at 80 characters.
- Footer: reference issue/ticket numbers if applicable (e.g., `Closes #123`)
- If the staged changes span multiple concerns, suggest splitting into multiple commits
- If the changes are a breaking change, add `BREAKING CHANGE:` in the footer

### Output
Provide the commit message in a code block, ready to copy. If you suggest splitting the commit, provide commands for each partial commit.