Skill File Examples

---
name: writing-difficult-email
description: Invoke when drafting an email that delivers bad news, declines a request, or addresses a conflict.
---

# Writing a Difficult Email

## Context
Difficult emails are high-stakes precisely because they're easy to get wrong. Burying the news, being vague, or defaulting to jargon damages trust. This skill ensures the email lands with clarity and care.

## Process

1. **Clarify the outcome first** — before writing a word, answer: what do you want the reader to feel, decide, or do? Write that in one sentence.
2. **Open humanly** — acknowledge context or relationship before getting to business. One sentence is enough.
3. **State the news clearly in the second paragraph** — don't bury it at the end. Readers who sense bad news and can't find it feel manipulated.
4. **Explain the reasoning briefly** — one to three sentences. Don't over-explain; it reads as defensive.
5. **Offer an alternative or next step if possible** — a declined request with an alternative is far better received than a flat no.
6. **Close with a clear action or open door** — "Let me know if you'd like to discuss" only if you mean it.
7. **Read it once from the recipient's perspective** — would you feel respected receiving this?

## Checklist

- [ ] Outcome defined before writing
- [ ] News stated clearly, not buried
- [ ] Reasoning explained briefly
- [ ] Alternative or next step offered where possible
- [ ] Reviewed from recipient's perspective

## Anti-Patterns

- **Never bury the news at the end** — readers who have to read to the last line to find the point feel manipulated.
- **Never use corporate non-language** — "at this time", "going forward", "per my last email" erode trust.
- **Never apologise for things you're not sorry about** — vague apologies read as insincere.

---
name: writing-project-status-update
description: Use when sending a progress update on any project to keep stakeholders informed and decisions unblocked.
---

# Writing a Project Status Update

## Context
A good status update tells stakeholders exactly where things stand without making them work to find out. Bad updates bury the headline, skip blockers, or describe activity instead of progress. This skill ensures your update is clear, honest, and decision-ready.

## Process

1. **Lead with the headline status** — one sentence: on track, at risk, or needs attention. Don't make the reader hunt for this.
2. **Summarise what's been completed** — 2–4 bullet points of meaningful completions since the last update. Results, not tasks.
3. **Describe what's in progress** — what is actively being worked on, and by whom.
4. **Call out blockers explicitly** — anything preventing progress must be named, with an owner and a proposed resolution.
5. **State what comes next** — the 2–3 things that will be completed before the next update.
6. **Flag any decisions needed** — if you need something from the reader, make it explicit at the end.
7. **Keep it scannable** — use short bullets or headings. A status update should take under two minutes to read.

## Checklist

- [ ] Headline status in the first sentence
- [ ] Completions described as results, not tasks
- [ ] Blockers named with owner and resolution path
- [ ] Next steps listed
- [ ] Decisions needed are explicit
- [ ] Readable in under 2 minutes

## Anti-Patterns

- **Never write "good progress"** without specifying what was completed — it says nothing.
- **Never bury blockers** in a progress paragraph — they need to be immediately visible.
- **Never write a wall of text** — if it requires a sit-down to read, it won't get read.

---
name: preparing-meeting-agenda
description: Use before any meeting you are running to ensure it has a clear purpose, structure, and outcome.
---

# Preparing a Meeting Agenda

## Context
A meeting without a clear agenda wastes everyone's time. An agenda commits the organiser to a purpose and gives attendees a chance to prepare. This skill takes five minutes and makes the difference between a meeting that produces decisions and one that produces another meeting.

## Process

1. **Define the single outcome** — complete this sentence: "This meeting will have succeeded if we ___." If you can't, the meeting may not be necessary.
2. **List agenda items as questions, not topics** — "Should we move the deadline?" is better than "Project timeline." Questions signal that a decision is needed.
3. **Assign a time box to each item** — be realistic. Most items take twice as long as planned.
4. **Assign an owner to each item** — who is leading that part of the discussion?
5. **Put the most important item first** — don't risk running out of time on what matters most.
6. **Send the agenda at least 24 hours in advance** — include any pre-read material people need.
7. **Reserve the last 5 minutes for action items** — who does what by when.

## Anti-Patterns

- **Never call a meeting that could be an email** — if no decision or discussion is required, send an update instead.
- **Never list a topic without a goal** — "Budget" as an agenda item tells no one what needs to happen.
- **Never skip the outcome statement** — it is the single most important thing to define before sending the invite.

---
name: writing-commit-messages
description: Use when writing a git commit message to follow conventional commits and ensure clarity.
---

# Writing Commit Messages

## Context
A good commit message makes git history searchable and useful. Bad commit messages make debugging, reverting, and understanding history painful. This skill enforces conventional commits format consistently.

## Process

1. **Choose the type:** feat, fix, docs, refactor, test, chore, perf, style, ci, build.
2. **Add the scope** in parentheses if the change is isolated: `feat(auth):`, `fix(api):`. Omit for wide changes.
3. **Write the subject line:** lowercase, present tense, imperative mood, under 72 characters.
   - ✓ `feat(auth): add JWT refresh token rotation`
   - ✗ `Added jwt refresh tokens`
4. **Add a body paragraph** (separated by a blank line) when the change is complex — explain *why*, not *what*.
5. **Add trailers** at the bottom for issue references: `Closes #123`, `Fixes #456`.

## Anti-Patterns

- **Never write vague messages** — `fix stuff`, `updates`, `wip` are useless history.
- **Never put the ticket number in the subject** — use a `Refs: #123` trailer instead.
- **Never mix multiple changes** in one commit — split them so each is independently revertable.

---
name: running-one-on-one
description: Invoke before or during a 1:1 meeting with a direct report to ensure the conversation is meaningful.
---

# Running a 1:1 Meeting

## Context
A 1:1 is not a status update — it is the primary space for trust, growth, and early problem detection. When it becomes a status readout, it loses its value and people stop bringing real issues. This skill keeps 1:1s useful, consistent, and grounded.

## Process

1. **Review notes from the last 1:1** (2 min before) — what did you commit to? What did they? Follow up on both.
2. **Start with their agenda** — open with "What's on your mind?" or "What do you most want to cover today?" Their priorities come first.
3. **Listen more than you talk** — your role is to understand their perspective, not to fill silence with your own.
4. **Ask at least one forward-looking question** — "What are you most excited about in the next month?" or "What would make this role better for you?"
5. **Raise your topics second** — feedback, project updates, and information-sharing happen after their agenda is addressed.
6. **End with clear commitments** — what will you do before the next 1:1? What will they? Write both down.
7. **Write up notes immediately after** — one paragraph is enough. The act of writing reveals what you understood.

## Checklist

- [ ] Previous commitments reviewed
- [ ] Their agenda heard first
- [ ] At least one growth or forward-looking question asked
- [ ] Feedback given if needed
- [ ] Commitments captured in writing

## Anti-Patterns

- **Never let 1:1s become status updates** — use async tools for project status; protect 1:1 time for people.
- **Never cancel a 1:1** — it signals that the person is low priority. Reschedule instead.
- **Never leave without at least one written commitment** — verbal commitments evaporate.

---
name: preparing-a-presentation
description: Use when preparing any presentation — for a client, leadership, or a team — to ensure it lands clearly and drives a decision.
---

# Preparing a Presentation

## Context
Most presentations fail for the same reasons: they start with background instead of the point, they contain too many slides, and they end without a clear ask. This skill is for any presentation where you need an audience to understand something and do something as a result.

## Process

1. **Define the single outcome** — complete this sentence before opening any slide tool: "After this presentation, the audience will ___." One outcome. If you can't complete it, you're not ready to build slides yet.

2. **Know your audience** — what do they already know? What do they care about? What objections will they have? A CFO and a project team need the same facts presented completely differently.

3. **Build the narrative first, not the slides** — write a five-sentence story arc:
   - The situation (context they already know)
   - The complication (what changed or what the problem is)
   - The question (what decision or action is needed)
   - The answer (your recommendation or finding)
   - The next step (what you're asking them to do)

4. **One idea per slide** — if you need two sentences to describe what a slide is about, it's two slides. Titles should state the conclusion, not the topic: "Revenue is down 12% YoY" not "Revenue Overview."

5. **Lead with the answer, not the build-up** — put your recommendation on slide 2, not slide 12. Audiences who don't know where you're going stop listening.

6. **Prepare for the questions you hope they don't ask** — the hardest objections don't disappear if you avoid them. Have a clear answer ready.

7. **Rehearse out loud at least once** — reading in your head is not rehearsal. Say it aloud. You will find the gaps.

8. **Time the presentation** — aim for 60–70% of your allotted time in content, leaving 30–40% for questions.

## Checklist

- [ ] Single outcome defined before building slides
- [ ] Audience needs and objections considered
- [ ] Narrative arc written in plain prose first
- [ ] Each slide has one idea, conclusion-led title
- [ ] Recommendation appears early, not at the end
- [ ] Hardest objections prepared for
- [ ] Rehearsed out loud
- [ ] Timing checked with space for discussion

## Anti-Patterns

- **Never open with an agenda slide** — open with the point. Agenda slides are a stalling tactic.
- **Never use a slide as a teleprompter** — if you're reading your slides to the audience, send a document instead.
- **Never end with "any questions?"** — end with your ask or the single thing you want them to remember.
- **Never add a slide "just in case"** — every unnecessary slide dilutes the ones that matter. Move them to an appendix.

---
name: onboarding-a-new-client
description: Use when a new client has signed to ensure a smooth, professional start to the relationship.
---

# Onboarding a New Client

## Context
The onboarding period sets the tone for the entire client relationship. A smooth, professional start builds trust before a single deliverable is produced. A chaotic start — missed introductions, unclear next steps, admin confusion — undermines confidence that the work will go well.

## Process

1. **Send a welcome message within 24 hours of signing** — confirm you're glad to be working together, name their point of contact, and give them a clear next step.
2. **Schedule a kickoff call within the first week** — the goal is alignment, not delivery. Cover: their goals, their definition of success, their communication preferences, and any constraints.
3. **Gather all access and information in one go** — logins, documents, contacts, billing details. Send one comprehensive intake form. Don't ask piecemeal.
4. **Set up their workspace** — project tool, shared folder, communication channel. Test that they can access everything before the kickoff.
5. **Send a kickoff summary after the call** — document what was agreed: goals, timeline, deliverables, contacts, and how decisions will be made.
6. **Complete the first small deliverable quickly** — a fast early win builds disproportionate confidence. Deliver something real in the first two weeks.
7. **Schedule a 30-day check-in** — ask: how is the relationship going? What could be better? Early feedback prevents late surprises.

## Checklist

- [ ] Welcome message sent within 24 hours
- [ ] Kickoff call scheduled
- [ ] All access and information gathered in one intake
- [ ] Workspace set up and access tested
- [ ] Kickoff summary document sent
- [ ] First deliverable completed
- [ ] 30-day check-in scheduled

## Anti-Patterns

- **Never assume they know your process** — document everything, even the obvious.
- **Never ask for information in multiple piecemeal messages** — one intake saves both sides time.
- **Never skip the kickoff summary** — verbal agreements evaporate; written ones create accountability.

---
name: reviewing-pull-request
description: Invoke before reviewing any pull request to ensure a thorough, consistent review.
---

# Reviewing a Pull Request

## Context
Pull request review is the primary quality gate for every change in the codebase. A rushed review lets bugs through; an over-engineered review blocks progress. This skill ensures you cover all the important dimensions without wasting time.

## Process

1. **Read the PR description** — understand the *why* before reading code. If there is no description, request one before proceeding.
2. **Verify the branch is up to date** with the target branch. Stale branches hide merge conflicts.
3. **Review each changed file** looking for:
   - Missing error handling or uncaught exceptions
   - Untested edge cases or missing test coverage
   - Unclear variable, function, or class names
   - Performance issues: N+1 queries, unnecessary re-renders, missing indexes
   - Security issues: unsanitized input, exposed secrets, missing auth checks
4. **Leave line comments** for specific code issues with a clear explanation of what to change and why.
5. **Leave a general comment** if the overall approach needs rethinking — explain the concern and suggest an alternative.
6. **Verify CI passes** before approving.
7. **Approve only when all blocking issues are resolved.**

## Checklist

- [ ] PR description explains the why
- [ ] Branch is up to date with target
- [ ] All changed files reviewed
- [ ] Error handling verified
- [ ] Test coverage adequate
- [ ] No security issues
- [ ] CI green
- [ ] No unresolved blocking comments

## Anti-Patterns

- **Never approve with open blocking comments** — a TODO in the code is not a fix.
- **Never leave vague feedback** like "this could be better" — explain what to change and why.
- **Never skip the PR description** — reviewing code without understanding intent leads to missing the real issue.

---
name: running-discovery-session
description: Use when facilitating a discovery session with a client or stakeholder to surface real requirements, constraints, and success criteria.
---

# Running a Discovery Session

## Context
Discovery is the highest-leverage activity in any project. Misaligned requirements discovered in week one cost an hour to fix. Discovered in week ten, they cost a month. This skill guides a focused, structured discovery conversation that surfaces the real requirements — including the ones the stakeholder doesn't know they have yet.

## Process

1. **Send a pre-session brief 48 hours in advance** — explain the purpose, what you'll cover, and ask them to bring any relevant documents or existing work.

2. **Open with context, not questions** — spend 5 minutes explaining what good discovery looks like and why it matters. This sets expectations and gets people out of presentation mode.

3. **Start with goals, not requirements** — ask "What does success look like in six months?" before asking "What do you need?" Goals reveal the real problem; stated requirements often don't.

4. **Explore constraints explicitly** — ask about timeline, budget, team capacity, and political constraints. Constraints shape solutions more than requirements do.

5. **Ask about failures and frustrations** — "What has been tried before and didn't work?" and "What frustrates you most about the current situation?" reveal more than any forward-looking question.

6. **Probe assumptions** — when someone states a requirement, ask "What would happen if we couldn't do that?" Often assumed requirements are not actually critical.

7. **Summarise back throughout** — every 20 minutes, summarise what you've heard. Misunderstandings surface in the summary, not in the question.

8. **Close with priorities** — ask them to rank the top three outcomes. If everything is critical, ask what they'd cut if budget were reduced by 30%.

9. **Send a written summary within 24 hours** — capture goals, constraints, open questions, and agreed next steps. Ask them to confirm or correct it.

## Checklist

- [ ] Pre-session brief sent 48 hours in advance
- [ ] Goals explored before requirements
- [ ] Constraints documented
- [ ] Past failures and frustrations discussed
- [ ] Key assumptions challenged
- [ ] Priorities ranked
- [ ] Written summary sent within 24 hours and confirmed

## Anti-Patterns

- **Never let discovery become a requirements form** — you're trying to understand a problem, not populate a template.
- **Never accept "we need X" without asking "why?"** at least twice — the real need is almost always deeper.
- **Never skip the written summary** — verbal alignment evaporates; written alignment creates a shared contract.
- **Never run discovery without the decision-maker present** — proxy conversations produce proxy requirements.

---
name: writing-business-case
description: Use when proposing a significant investment, initiative, or change that requires stakeholder approval.
---

# Writing a Business Case

## Context
A business case answers the question every decision-maker is actually asking: "Is this worth it, and are you the right person to do it?" A weak business case either fails to get approved, or gets approved on false assumptions — both outcomes are bad. A strong business case builds from evidence, not enthusiasm.

## Process

1. **Define the problem, not the solution** — open with a clear, quantified description of the problem you're solving. "We lose approximately £40k/year to manual reconciliation errors" is a business case opener. "We should buy software X" is not.

2. **Establish the cost of inaction** — what happens if nothing is done? Quantify it in time, money, risk, or opportunity cost. Decision-makers approve things that fix costly problems.

3. **Present 2–3 options** — including a "do nothing" option. Showing alternatives demonstrates rigour and lets the reader feel in control of the decision.

4. **Analyse each option** — for each: estimated cost, estimated benefit, time to value, risks, and dependencies.

5. **Make a clear recommendation** — don't leave the decision unmade. State which option you recommend and why, in one paragraph.

6. **Include a financial summary** — even a rough ROI or payback period. Decision-makers need a number to justify the approval to others.

7. **Identify risks and mitigations** — name the top 3 risks and what you'd do about each. This shows you've thought it through.

8. **State exactly what you need** — end with a specific ask: budget, headcount, a decision, a sponsor. Make it easy to say yes.

## Checklist

- [ ] Problem quantified before solution proposed
- [ ] Cost of inaction stated
- [ ] At least two options compared, including "do nothing"
- [ ] Clear recommendation with reasoning
- [ ] Financial summary included
- [ ] Top risks named with mitigations
- [ ] Specific ask at the end

## Anti-Patterns

- **Never lead with the solution** — start with the problem. Solutions without problems sound like personal projects.
- **Never omit a financial summary** — "can't quantify it" almost always means "haven't tried."
- **Never leave the recommendation ambiguous** — "there are merits to both approaches" is not a conclusion.

---
name: writing-technical-spec
description: Invoke before starting implementation of any non-trivial feature to align the team on approach.
---

# Writing a Technical Spec

## Context
Starting implementation without a spec leads to misaligned expectations, rework, and scope creep. A spec doesn't need to be long — it needs to answer the questions that would cause the most wasted work if left unresolved.

## Process

1. **Write the problem statement** — what pain does this solve and for which users? Quantify if possible.
2. **List requirements** — separate must-haves from nice-to-haves. Be specific: "under 200ms p99" not "fast."
3. **Propose 2-3 approaches** — describe the trade-offs of each. Include a cost/complexity estimate.
4. **Recommend one approach** with clear reasoning — don't leave the decision unmade.
5. **Design the data model** — what entities are created, modified, or deleted? What are the key fields?
6. **Design the API contract** — endpoints, request/response shapes, error codes.
7. **Describe rollout** — feature flags, phased rollout, migration plan if applicable.
8. **List open questions** — unresolved decisions that need answers before implementation can start.
9. **Circulate for 48 hours** — collect feedback before marking as approved.

## Anti-Patterns

- **Never write a spec after implementation starts** — it becomes documentation theater, not decision-making.
- **Never leave the approach decision unmade** — "we'll decide in the PR" wastes implementation effort.
- **Never omit open questions** — hidden assumptions become production bugs.