From e366a77cf0b948bd5732e3a47915678d02d47296 Mon Sep 17 00:00:00 2001 From: mohitagw15856 Date: Wed, 20 May 2026 07:36:10 +0000 Subject: [PATCH] Quality-improve 10 v7.0.0-era engineering skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Applies three consistent fixes across the v7.0.0 batch: - Rename `## Output Structure` → `## Output Format` for consistency - Wrap output template in `---` document separators (code-review-checklist, debugging-log-analyser needed full structural upgrade; remaining 8 already had the wrapper) - Remove `## Example Trigger Phrases` section from all 10 skills Skills updated: code-review-checklist, debugging-log-analyser, changelog-generator, pr-description-writer, system-design-interview, test-strategy-doc, runbook-writer, incident-postmortem, api-docs-writer, architecture-decision-record Both `skills/` and `plugins/pm-engineering/skills/` copies synced. https://claude.ai/code/session_01C3HwChrccJd145vJ6Z7ajF --- .../skills/api-docs-writer/SKILL.md | 9 +-------- .../architecture-decision-record/SKILL.md | 9 +-------- .../skills/changelog-generator/SKILL.md | 11 ++-------- .../skills/code-review-checklist/SKILL.md | 18 ++++++++--------- .../skills/debugging-log-analyser/SKILL.md | 20 +++++++++---------- .../skills/incident-postmortem/SKILL.md | 9 +-------- .../skills/pr-description-writer/SKILL.md | 11 ++-------- .../skills/runbook-writer/SKILL.md | 11 ++-------- .../skills/system-design-interview/SKILL.md | 11 ++-------- .../skills/test-strategy-doc/SKILL.md | 11 ++-------- skills/api-docs-writer/SKILL.md | 9 +-------- skills/architecture-decision-record/SKILL.md | 9 +-------- skills/changelog-generator/SKILL.md | 11 ++-------- skills/code-review-checklist/SKILL.md | 18 ++++++++--------- skills/debugging-log-analyser/SKILL.md | 20 +++++++++---------- skills/incident-postmortem/SKILL.md | 9 +-------- skills/pr-description-writer/SKILL.md | 11 ++-------- skills/runbook-writer/SKILL.md | 11 ++-------- skills/system-design-interview/SKILL.md | 11 ++-------- skills/test-strategy-doc/SKILL.md | 11 ++-------- 20 files changed, 60 insertions(+), 180 deletions(-) diff --git a/plugins/pm-engineering/skills/api-docs-writer/SKILL.md b/plugins/pm-engineering/skills/api-docs-writer/SKILL.md index 29b4a69..e6d9977 100644 --- a/plugins/pm-engineering/skills/api-docs-writer/SKILL.md +++ b/plugins/pm-engineering/skills/api-docs-writer/SKILL.md @@ -16,7 +16,7 @@ Ask the user for these if not provided: - **Audience** (internal developers / external partners / public) - **Output format** (Markdown / OpenAPI YAML / Plain prose) -## Output Structure +## Output Format For each endpoint, produce the following: @@ -137,10 +137,3 @@ data = response.json() - [ ] Auth method is clearly stated at the top - [ ] Enum values are listed where applicable - [ ] Pagination documented if the endpoint is a list endpoint - -## Example Trigger Phrases - -- "Document this API endpoint: [paste spec or description]" -- "Turn this Postman collection into developer docs" -- "Write API reference docs for [endpoint]" -- "Write a developer guide for our [product] API" diff --git a/plugins/pm-engineering/skills/architecture-decision-record/SKILL.md b/plugins/pm-engineering/skills/architecture-decision-record/SKILL.md index 0948d6a..a61c362 100644 --- a/plugins/pm-engineering/skills/architecture-decision-record/SKILL.md +++ b/plugins/pm-engineering/skills/architecture-decision-record/SKILL.md @@ -18,7 +18,7 @@ Ask the user for these if not provided: - **Status** (Proposed / Accepted / Deprecated / Superseded) - **Author and date** -## Output Structure +## Output Format --- @@ -108,10 +108,3 @@ For each option, produce: - [ ] Decision is stated in plain language in the Decision section - [ ] Risks section identifies what would invalidate this decision - [ ] Written for someone with no prior context on this decision - -## Example Trigger Phrases - -- "Write an ADR for using [technology]" -- "Document our decision to [architectural choice]" -- "Create an architecture decision record for [topic]" -- "Help me write up why we chose [option] over [alternative]" diff --git a/plugins/pm-engineering/skills/changelog-generator/SKILL.md b/plugins/pm-engineering/skills/changelog-generator/SKILL.md index 64c8dd1..5716403 100644 --- a/plugins/pm-engineering/skills/changelog-generator/SKILL.md +++ b/plugins/pm-engineering/skills/changelog-generator/SKILL.md @@ -1,6 +1,6 @@ --- name: changelog-generator -description: "Convert a git log, commit list, or release notes into a polished, user-facing changelog. Use when writing release notes, generating a CHANGELOG.md entry, or documenting what changed in a version. Produces a structured changelog section with version header, categorised changes, and migration notes. Optimised for Opus 4.7 and newer models." +description: "Convert a git log, commit list, or release notes into a polished, user-facing changelog. Use when writing release notes, generating a CHANGELOG.md entry, or documenting what changed in a version. Produces a structured changelog section with version header, categorised changes, and migration notes." --- # Changelog Generator Skill @@ -16,7 +16,7 @@ Ask for these if not provided: - **Audience** (developers using an API / end users of a product / internal team — affects language) - **Any breaking changes** (flag these explicitly if known) -## Output Structure +## Output Format Follow [Keep a Changelog](https://keepachangelog.com) format: @@ -73,10 +73,3 @@ Follow [Keep a Changelog](https://keepachangelog.com) format: - [ ] Version and date header is correct - [ ] Empty sections are omitted - [ ] Tone is imperative mood throughout - -## Example Trigger Phrases -- "Write a changelog for version [X]" + [paste commits] -- "Generate release notes from these commits" -- "Turn this git log into a CHANGELOG entry" -- "Write the CHANGELOG.md update for this release" -- "What changed in this release?" + [paste commit list] diff --git a/plugins/pm-engineering/skills/code-review-checklist/SKILL.md b/plugins/pm-engineering/skills/code-review-checklist/SKILL.md index 38b87fa..29edd69 100644 --- a/plugins/pm-engineering/skills/code-review-checklist/SKILL.md +++ b/plugins/pm-engineering/skills/code-review-checklist/SKILL.md @@ -1,6 +1,6 @@ --- name: code-review-checklist -description: "Generate a tailored code review checklist for any pull request based on the language, type of change, and risk level. Use when asked to review code, check a PR, review a pull request, or generate a code review checklist. Produces a focused checklist with language-specific checks, risk-level-appropriate depth, and a clear approve/request-changes recommendation. Optimised for Opus 4.7 and newer models." +description: "Generate a tailored code review checklist for any pull request based on the language, type of change, and risk level. Use when asked to review code, check a PR, review a pull request, or generate a code review checklist. Produces a focused checklist with language-specific checks, risk-level-appropriate depth, and a clear approve/request-changes recommendation." --- # Code Review Checklist Skill @@ -16,10 +16,12 @@ Ask the user for these if not provided: - **PR description** (paste the description or link to the PR) - **Author context** (new starter / experienced / external contributor) -## Output Structure +## Output Format + +--- + +# Code Review: [PR Title or Reference] -### 1. Review Summary -**PR:** [Title or reference] **Scope assessment:** [Small / Medium / Large / Too large — should be split] **Recommended review depth:** [Skim / Standard / Deep dive] **Estimated review time:** [Minutes] @@ -94,14 +96,10 @@ Language-specific correctness checks — choose based on the language stated: ### 7. Common Pitfalls for This Change Type Based on the change type and language, flag 2-3 things reviewers typically miss for this combination. +--- + ## Quality Checks - [ ] Checklist is tailored to the stated language (not generic) - [ ] Change-type-specific section is included - [ ] Risk-appropriate depth matches stated risk level - [ ] Decision framework is explicit - -## Example Trigger Phrases -- "Generate a code review checklist for [PR description]" -- "What should I check in this pull request?" -- "Give me a code review checklist for a [language] [change type]" -- "Review checklist for a high-risk PR in [language]" \ No newline at end of file diff --git a/plugins/pm-engineering/skills/debugging-log-analyser/SKILL.md b/plugins/pm-engineering/skills/debugging-log-analyser/SKILL.md index b1c9347..ffeb2b3 100644 --- a/plugins/pm-engineering/skills/debugging-log-analyser/SKILL.md +++ b/plugins/pm-engineering/skills/debugging-log-analyser/SKILL.md @@ -1,6 +1,6 @@ --- name: debugging-log-analyser -description: "Parse error logs, stack traces, and crash reports into a structured root cause diagnosis. Use when sharing a log, stack trace, error output, or crash dump. Produces a structured diagnosis with probable root cause, affected code path, suggested fix, and next debugging steps. Optimised for Opus 4.7 and newer models." +description: "Parse error logs, stack traces, and crash reports into a structured root cause diagnosis. Use when sharing a log, stack trace, error output, or crash dump. Produces a structured diagnosis with probable root cause, affected code path, suggested fix, and next debugging steps." --- # Debugging Log Analyser Skill @@ -16,10 +16,13 @@ Ask for these if not provided: - **Environment** (local dev / staging / production) - **What they've already tried** (if anything) -## Output Structure +## Output Format -### 1. Error Classification -**Error type:** [Runtime exception / Build error / Config error / Network error / Memory/resource error / Unknown] +--- + +# Debugging Report: [Service/App Name] + +**Error type:** [Runtime exception / Build error / Config error / Network error / Memory error / Unknown] **Severity:** [Fatal / Critical / Warning / Informational] **Recurrence pattern:** [One-off / Intermittent / Consistent / On-startup / Under load] @@ -64,16 +67,11 @@ One or two concrete things that would prevent this class of error recurring: - Add monitoring/alerting for [condition] - Test that covers [scenario] +--- + ## Quality Checks - [ ] Root cause is specific (not "there might be a null pointer issue") - [ ] At least one concrete code-level fix is suggested - [ ] Next steps are actionable commands, not vague advice - [ ] Language-specific idioms are used correctly - [ ] Prevention is proactive (not just "add error handling") - -## Example Trigger Phrases -- "Why is this crashing?" + [paste log] -- "Can you analyse this stack trace?" -- "I'm getting this error, what does it mean?" -- "Debug this log for me" -- "What's causing this exception?" diff --git a/plugins/pm-engineering/skills/incident-postmortem/SKILL.md b/plugins/pm-engineering/skills/incident-postmortem/SKILL.md index 744397f..af1e3ff 100644 --- a/plugins/pm-engineering/skills/incident-postmortem/SKILL.md +++ b/plugins/pm-engineering/skills/incident-postmortem/SKILL.md @@ -21,7 +21,7 @@ Ask the user for these if not provided: - **Initial thoughts on root cause** - **Action items already identified** (optional) -## Output Structure +## Output Format --- @@ -135,10 +135,3 @@ Rules for action items: - [ ] Every action item has an owner and due date - [ ] "What went well" section is genuine, not token - [ ] Executive summary is readable by non-technical leadership - -## Example Trigger Phrases - -- "Write a postmortem for the [incident name] outage" -- "Help me write a P1 incident report" -- "Generate an RCA document for [service] going down on [date]" -- "Draft a blameless postmortem from these notes: [paste notes]" diff --git a/plugins/pm-engineering/skills/pr-description-writer/SKILL.md b/plugins/pm-engineering/skills/pr-description-writer/SKILL.md index 5dca74c..f488f07 100644 --- a/plugins/pm-engineering/skills/pr-description-writer/SKILL.md +++ b/plugins/pm-engineering/skills/pr-description-writer/SKILL.md @@ -1,6 +1,6 @@ --- name: pr-description-writer -description: "Write a clear, structured pull request description from a git diff, branch summary, or commit list. Use when asked to write a PR description, draft a pull request, or document code changes. Produces a description with summary, motivation, changes made, testing steps, and reviewer guidance. Optimised for Opus 4.7 and newer models." +description: "Write a clear, structured pull request description from a git diff, branch summary, or commit list. Use when asked to write a PR description, draft a pull request, or document code changes. Produces a description with summary, motivation, changes made, testing steps, and reviewer guidance." --- # PR Description Writer Skill @@ -16,7 +16,7 @@ Ask for these if not provided: - **Risk level** (low / medium / high — affects how much reviewer guidance to include) - **PR type** (feature / bug fix / refactor / dependency upgrade / config change / hotfix) -## Output Structure +## Output Format ### Title A clear, imperative-mood title under 72 characters: @@ -78,10 +78,3 @@ Flag anything that warrants extra attention: - [ ] Changes list describes logical changes (not file-by-file changes) - [ ] Testing steps are reproducible by someone unfamiliar with the code - [ ] Risk-appropriate reviewer guidance is included - -## Example Trigger Phrases -- "Write a PR description for these changes" + [paste diff or description] -- "Draft a pull request for [feature]" -- "I need a PR description — here's what I changed" -- "Summarise these commits into a PR description" -- "Write the PR body for this branch" diff --git a/plugins/pm-engineering/skills/runbook-writer/SKILL.md b/plugins/pm-engineering/skills/runbook-writer/SKILL.md index b75922d..4571add 100644 --- a/plugins/pm-engineering/skills/runbook-writer/SKILL.md +++ b/plugins/pm-engineering/skills/runbook-writer/SKILL.md @@ -1,6 +1,6 @@ --- name: runbook-writer -description: "Write an operational runbook for a service, incident type, or deployment procedure. Use when asked to write a runbook, create an ops guide, document an operational procedure, or prepare an incident response playbook. Produces a runbook with overview, prerequisites, step-by-step procedures, rollback steps, troubleshooting table, and escalation paths. Optimised for Opus 4.7 and newer models." +description: "Write an operational runbook for a service, incident type, or deployment procedure. Use when asked to write a runbook, create an ops guide, document an operational procedure, or prepare an incident response playbook. Produces a runbook with overview, prerequisites, step-by-step procedures, rollback steps, troubleshooting table, and escalation paths." --- # Runbook Writer Skill @@ -16,7 +16,7 @@ Ask for these if not provided: - **Audience** (new on-call engineers / experienced SREs / DevOps team) - **Tech stack** (where relevant — e.g. Kubernetes, AWS RDS, Node.js) -## Output Structure +## Output Format --- **Runbook:** [Runbook Title] @@ -135,10 +135,3 @@ After completing the runbook: - [ ] Rollback procedure is complete and independently testable - [ ] Escalation paths name specific contacts, not just team names - [ ] Runbook can be followed by someone who has never touched this system - -## Example Trigger Phrases -- "Write a runbook for [service] deployment" -- "Create an incident response runbook for [alert type]" -- "I need a runbook for [procedure]" -- "Document the operational procedure for [X]" -- "Write an ops playbook for [scenario]" diff --git a/plugins/pm-engineering/skills/system-design-interview/SKILL.md b/plugins/pm-engineering/skills/system-design-interview/SKILL.md index e3a10e8..496cedb 100644 --- a/plugins/pm-engineering/skills/system-design-interview/SKILL.md +++ b/plugins/pm-engineering/skills/system-design-interview/SKILL.md @@ -1,6 +1,6 @@ --- name: system-design-interview -description: "Structure a complete system design answer for interview questions or real architecture sessions. Use when asked to design a system, answer a system design interview question, or architect a solution at scale. Produces a structured answer covering requirements, capacity estimates, high-level design, component deep-dives, trade-offs, and follow-up considerations. Optimised for Opus 4.7 and newer models." +description: "Structure a complete system design answer for interview questions or real architecture sessions. Use when asked to design a system, answer a system design interview question, or architect a solution at scale. Produces a structured answer covering requirements, capacity estimates, high-level design, component deep-dives, trade-offs, and follow-up considerations." --- # System Design Interview Skill @@ -15,7 +15,7 @@ Ask for these if not provided: - **Scale target** (rough numbers: DAU, requests/sec, data volume — or "assume typical web scale") - **Constraints or priorities** (e.g. prioritise availability over consistency, minimise cost, low-latency reads) -## Output Structure +## Output Format ### 1. Clarifying Questions Before designing, list 4–6 questions that would change the design. Examples: @@ -126,10 +126,3 @@ Things to tackle in production but out of scope for this design session: - [ ] At least 2 component deep-dives with technology choices justified - [ ] Trade-offs section is honest (not just benefits of chosen approach) - [ ] Data flow is described end-to-end for the critical path - -## Example Trigger Phrases -- "Help me answer a system design interview: [question]" -- "Design [system] for a system design interview" -- "How would I architect [system] at scale?" -- "I have a system design interview — the question is [X]" -- "Design a [URL shortener / chat system / notification service / feed]" diff --git a/plugins/pm-engineering/skills/test-strategy-doc/SKILL.md b/plugins/pm-engineering/skills/test-strategy-doc/SKILL.md index 68dc7ec..bcfd3dc 100644 --- a/plugins/pm-engineering/skills/test-strategy-doc/SKILL.md +++ b/plugins/pm-engineering/skills/test-strategy-doc/SKILL.md @@ -1,6 +1,6 @@ --- name: test-strategy-doc -description: "Write a test strategy document from a feature spec, PRD, or system description. Use when asked to create a test plan, write a test strategy, define QA approach, or plan testing for a feature or release. Produces a complete test strategy with scope, risk assessment, test types, coverage targets, and a prioritised test case outline. Optimised for Opus 4.7 and newer models." +description: "Write a test strategy document from a feature spec, PRD, or system description. Use when asked to create a test plan, write a test strategy, define QA approach, or plan testing for a feature or release. Produces a complete test strategy with scope, risk assessment, test types, coverage targets, and a prioritised test case outline." --- # Test Strategy Document Skill @@ -16,7 +16,7 @@ Ask for these if not provided: - **Timeline** (when does this need to ship — affects prioritisation) - **Team context** (who is doing the testing — developers / dedicated QA / both) -## Output Structure +## Output Format ### 1. Test Scope @@ -118,10 +118,3 @@ Testing is complete when: - [ ] P0 test cases cover the highest-risk paths specifically - [ ] Each test type names a concrete tool (not "some testing framework") - [ ] Definition of Done is measurable (not "tests are done when QA is happy") - -## Example Trigger Phrases -- "Write a test strategy for [feature]" + [paste spec or PRD] -- "Create a test plan for [system]" -- "How should we test [feature]?" -- "I need a QA plan for this sprint" -- "What tests do we need for [X]?" diff --git a/skills/api-docs-writer/SKILL.md b/skills/api-docs-writer/SKILL.md index 29b4a69..e6d9977 100644 --- a/skills/api-docs-writer/SKILL.md +++ b/skills/api-docs-writer/SKILL.md @@ -16,7 +16,7 @@ Ask the user for these if not provided: - **Audience** (internal developers / external partners / public) - **Output format** (Markdown / OpenAPI YAML / Plain prose) -## Output Structure +## Output Format For each endpoint, produce the following: @@ -137,10 +137,3 @@ data = response.json() - [ ] Auth method is clearly stated at the top - [ ] Enum values are listed where applicable - [ ] Pagination documented if the endpoint is a list endpoint - -## Example Trigger Phrases - -- "Document this API endpoint: [paste spec or description]" -- "Turn this Postman collection into developer docs" -- "Write API reference docs for [endpoint]" -- "Write a developer guide for our [product] API" diff --git a/skills/architecture-decision-record/SKILL.md b/skills/architecture-decision-record/SKILL.md index 0948d6a..a61c362 100644 --- a/skills/architecture-decision-record/SKILL.md +++ b/skills/architecture-decision-record/SKILL.md @@ -18,7 +18,7 @@ Ask the user for these if not provided: - **Status** (Proposed / Accepted / Deprecated / Superseded) - **Author and date** -## Output Structure +## Output Format --- @@ -108,10 +108,3 @@ For each option, produce: - [ ] Decision is stated in plain language in the Decision section - [ ] Risks section identifies what would invalidate this decision - [ ] Written for someone with no prior context on this decision - -## Example Trigger Phrases - -- "Write an ADR for using [technology]" -- "Document our decision to [architectural choice]" -- "Create an architecture decision record for [topic]" -- "Help me write up why we chose [option] over [alternative]" diff --git a/skills/changelog-generator/SKILL.md b/skills/changelog-generator/SKILL.md index 64c8dd1..5716403 100644 --- a/skills/changelog-generator/SKILL.md +++ b/skills/changelog-generator/SKILL.md @@ -1,6 +1,6 @@ --- name: changelog-generator -description: "Convert a git log, commit list, or release notes into a polished, user-facing changelog. Use when writing release notes, generating a CHANGELOG.md entry, or documenting what changed in a version. Produces a structured changelog section with version header, categorised changes, and migration notes. Optimised for Opus 4.7 and newer models." +description: "Convert a git log, commit list, or release notes into a polished, user-facing changelog. Use when writing release notes, generating a CHANGELOG.md entry, or documenting what changed in a version. Produces a structured changelog section with version header, categorised changes, and migration notes." --- # Changelog Generator Skill @@ -16,7 +16,7 @@ Ask for these if not provided: - **Audience** (developers using an API / end users of a product / internal team — affects language) - **Any breaking changes** (flag these explicitly if known) -## Output Structure +## Output Format Follow [Keep a Changelog](https://keepachangelog.com) format: @@ -73,10 +73,3 @@ Follow [Keep a Changelog](https://keepachangelog.com) format: - [ ] Version and date header is correct - [ ] Empty sections are omitted - [ ] Tone is imperative mood throughout - -## Example Trigger Phrases -- "Write a changelog for version [X]" + [paste commits] -- "Generate release notes from these commits" -- "Turn this git log into a CHANGELOG entry" -- "Write the CHANGELOG.md update for this release" -- "What changed in this release?" + [paste commit list] diff --git a/skills/code-review-checklist/SKILL.md b/skills/code-review-checklist/SKILL.md index 38b87fa..29edd69 100644 --- a/skills/code-review-checklist/SKILL.md +++ b/skills/code-review-checklist/SKILL.md @@ -1,6 +1,6 @@ --- name: code-review-checklist -description: "Generate a tailored code review checklist for any pull request based on the language, type of change, and risk level. Use when asked to review code, check a PR, review a pull request, or generate a code review checklist. Produces a focused checklist with language-specific checks, risk-level-appropriate depth, and a clear approve/request-changes recommendation. Optimised for Opus 4.7 and newer models." +description: "Generate a tailored code review checklist for any pull request based on the language, type of change, and risk level. Use when asked to review code, check a PR, review a pull request, or generate a code review checklist. Produces a focused checklist with language-specific checks, risk-level-appropriate depth, and a clear approve/request-changes recommendation." --- # Code Review Checklist Skill @@ -16,10 +16,12 @@ Ask the user for these if not provided: - **PR description** (paste the description or link to the PR) - **Author context** (new starter / experienced / external contributor) -## Output Structure +## Output Format + +--- + +# Code Review: [PR Title or Reference] -### 1. Review Summary -**PR:** [Title or reference] **Scope assessment:** [Small / Medium / Large / Too large — should be split] **Recommended review depth:** [Skim / Standard / Deep dive] **Estimated review time:** [Minutes] @@ -94,14 +96,10 @@ Language-specific correctness checks — choose based on the language stated: ### 7. Common Pitfalls for This Change Type Based on the change type and language, flag 2-3 things reviewers typically miss for this combination. +--- + ## Quality Checks - [ ] Checklist is tailored to the stated language (not generic) - [ ] Change-type-specific section is included - [ ] Risk-appropriate depth matches stated risk level - [ ] Decision framework is explicit - -## Example Trigger Phrases -- "Generate a code review checklist for [PR description]" -- "What should I check in this pull request?" -- "Give me a code review checklist for a [language] [change type]" -- "Review checklist for a high-risk PR in [language]" \ No newline at end of file diff --git a/skills/debugging-log-analyser/SKILL.md b/skills/debugging-log-analyser/SKILL.md index b1c9347..ffeb2b3 100644 --- a/skills/debugging-log-analyser/SKILL.md +++ b/skills/debugging-log-analyser/SKILL.md @@ -1,6 +1,6 @@ --- name: debugging-log-analyser -description: "Parse error logs, stack traces, and crash reports into a structured root cause diagnosis. Use when sharing a log, stack trace, error output, or crash dump. Produces a structured diagnosis with probable root cause, affected code path, suggested fix, and next debugging steps. Optimised for Opus 4.7 and newer models." +description: "Parse error logs, stack traces, and crash reports into a structured root cause diagnosis. Use when sharing a log, stack trace, error output, or crash dump. Produces a structured diagnosis with probable root cause, affected code path, suggested fix, and next debugging steps." --- # Debugging Log Analyser Skill @@ -16,10 +16,13 @@ Ask for these if not provided: - **Environment** (local dev / staging / production) - **What they've already tried** (if anything) -## Output Structure +## Output Format -### 1. Error Classification -**Error type:** [Runtime exception / Build error / Config error / Network error / Memory/resource error / Unknown] +--- + +# Debugging Report: [Service/App Name] + +**Error type:** [Runtime exception / Build error / Config error / Network error / Memory error / Unknown] **Severity:** [Fatal / Critical / Warning / Informational] **Recurrence pattern:** [One-off / Intermittent / Consistent / On-startup / Under load] @@ -64,16 +67,11 @@ One or two concrete things that would prevent this class of error recurring: - Add monitoring/alerting for [condition] - Test that covers [scenario] +--- + ## Quality Checks - [ ] Root cause is specific (not "there might be a null pointer issue") - [ ] At least one concrete code-level fix is suggested - [ ] Next steps are actionable commands, not vague advice - [ ] Language-specific idioms are used correctly - [ ] Prevention is proactive (not just "add error handling") - -## Example Trigger Phrases -- "Why is this crashing?" + [paste log] -- "Can you analyse this stack trace?" -- "I'm getting this error, what does it mean?" -- "Debug this log for me" -- "What's causing this exception?" diff --git a/skills/incident-postmortem/SKILL.md b/skills/incident-postmortem/SKILL.md index 744397f..af1e3ff 100644 --- a/skills/incident-postmortem/SKILL.md +++ b/skills/incident-postmortem/SKILL.md @@ -21,7 +21,7 @@ Ask the user for these if not provided: - **Initial thoughts on root cause** - **Action items already identified** (optional) -## Output Structure +## Output Format --- @@ -135,10 +135,3 @@ Rules for action items: - [ ] Every action item has an owner and due date - [ ] "What went well" section is genuine, not token - [ ] Executive summary is readable by non-technical leadership - -## Example Trigger Phrases - -- "Write a postmortem for the [incident name] outage" -- "Help me write a P1 incident report" -- "Generate an RCA document for [service] going down on [date]" -- "Draft a blameless postmortem from these notes: [paste notes]" diff --git a/skills/pr-description-writer/SKILL.md b/skills/pr-description-writer/SKILL.md index 5dca74c..f488f07 100644 --- a/skills/pr-description-writer/SKILL.md +++ b/skills/pr-description-writer/SKILL.md @@ -1,6 +1,6 @@ --- name: pr-description-writer -description: "Write a clear, structured pull request description from a git diff, branch summary, or commit list. Use when asked to write a PR description, draft a pull request, or document code changes. Produces a description with summary, motivation, changes made, testing steps, and reviewer guidance. Optimised for Opus 4.7 and newer models." +description: "Write a clear, structured pull request description from a git diff, branch summary, or commit list. Use when asked to write a PR description, draft a pull request, or document code changes. Produces a description with summary, motivation, changes made, testing steps, and reviewer guidance." --- # PR Description Writer Skill @@ -16,7 +16,7 @@ Ask for these if not provided: - **Risk level** (low / medium / high — affects how much reviewer guidance to include) - **PR type** (feature / bug fix / refactor / dependency upgrade / config change / hotfix) -## Output Structure +## Output Format ### Title A clear, imperative-mood title under 72 characters: @@ -78,10 +78,3 @@ Flag anything that warrants extra attention: - [ ] Changes list describes logical changes (not file-by-file changes) - [ ] Testing steps are reproducible by someone unfamiliar with the code - [ ] Risk-appropriate reviewer guidance is included - -## Example Trigger Phrases -- "Write a PR description for these changes" + [paste diff or description] -- "Draft a pull request for [feature]" -- "I need a PR description — here's what I changed" -- "Summarise these commits into a PR description" -- "Write the PR body for this branch" diff --git a/skills/runbook-writer/SKILL.md b/skills/runbook-writer/SKILL.md index b75922d..4571add 100644 --- a/skills/runbook-writer/SKILL.md +++ b/skills/runbook-writer/SKILL.md @@ -1,6 +1,6 @@ --- name: runbook-writer -description: "Write an operational runbook for a service, incident type, or deployment procedure. Use when asked to write a runbook, create an ops guide, document an operational procedure, or prepare an incident response playbook. Produces a runbook with overview, prerequisites, step-by-step procedures, rollback steps, troubleshooting table, and escalation paths. Optimised for Opus 4.7 and newer models." +description: "Write an operational runbook for a service, incident type, or deployment procedure. Use when asked to write a runbook, create an ops guide, document an operational procedure, or prepare an incident response playbook. Produces a runbook with overview, prerequisites, step-by-step procedures, rollback steps, troubleshooting table, and escalation paths." --- # Runbook Writer Skill @@ -16,7 +16,7 @@ Ask for these if not provided: - **Audience** (new on-call engineers / experienced SREs / DevOps team) - **Tech stack** (where relevant — e.g. Kubernetes, AWS RDS, Node.js) -## Output Structure +## Output Format --- **Runbook:** [Runbook Title] @@ -135,10 +135,3 @@ After completing the runbook: - [ ] Rollback procedure is complete and independently testable - [ ] Escalation paths name specific contacts, not just team names - [ ] Runbook can be followed by someone who has never touched this system - -## Example Trigger Phrases -- "Write a runbook for [service] deployment" -- "Create an incident response runbook for [alert type]" -- "I need a runbook for [procedure]" -- "Document the operational procedure for [X]" -- "Write an ops playbook for [scenario]" diff --git a/skills/system-design-interview/SKILL.md b/skills/system-design-interview/SKILL.md index e3a10e8..496cedb 100644 --- a/skills/system-design-interview/SKILL.md +++ b/skills/system-design-interview/SKILL.md @@ -1,6 +1,6 @@ --- name: system-design-interview -description: "Structure a complete system design answer for interview questions or real architecture sessions. Use when asked to design a system, answer a system design interview question, or architect a solution at scale. Produces a structured answer covering requirements, capacity estimates, high-level design, component deep-dives, trade-offs, and follow-up considerations. Optimised for Opus 4.7 and newer models." +description: "Structure a complete system design answer for interview questions or real architecture sessions. Use when asked to design a system, answer a system design interview question, or architect a solution at scale. Produces a structured answer covering requirements, capacity estimates, high-level design, component deep-dives, trade-offs, and follow-up considerations." --- # System Design Interview Skill @@ -15,7 +15,7 @@ Ask for these if not provided: - **Scale target** (rough numbers: DAU, requests/sec, data volume — or "assume typical web scale") - **Constraints or priorities** (e.g. prioritise availability over consistency, minimise cost, low-latency reads) -## Output Structure +## Output Format ### 1. Clarifying Questions Before designing, list 4–6 questions that would change the design. Examples: @@ -126,10 +126,3 @@ Things to tackle in production but out of scope for this design session: - [ ] At least 2 component deep-dives with technology choices justified - [ ] Trade-offs section is honest (not just benefits of chosen approach) - [ ] Data flow is described end-to-end for the critical path - -## Example Trigger Phrases -- "Help me answer a system design interview: [question]" -- "Design [system] for a system design interview" -- "How would I architect [system] at scale?" -- "I have a system design interview — the question is [X]" -- "Design a [URL shortener / chat system / notification service / feed]" diff --git a/skills/test-strategy-doc/SKILL.md b/skills/test-strategy-doc/SKILL.md index 68dc7ec..bcfd3dc 100644 --- a/skills/test-strategy-doc/SKILL.md +++ b/skills/test-strategy-doc/SKILL.md @@ -1,6 +1,6 @@ --- name: test-strategy-doc -description: "Write a test strategy document from a feature spec, PRD, or system description. Use when asked to create a test plan, write a test strategy, define QA approach, or plan testing for a feature or release. Produces a complete test strategy with scope, risk assessment, test types, coverage targets, and a prioritised test case outline. Optimised for Opus 4.7 and newer models." +description: "Write a test strategy document from a feature spec, PRD, or system description. Use when asked to create a test plan, write a test strategy, define QA approach, or plan testing for a feature or release. Produces a complete test strategy with scope, risk assessment, test types, coverage targets, and a prioritised test case outline." --- # Test Strategy Document Skill @@ -16,7 +16,7 @@ Ask for these if not provided: - **Timeline** (when does this need to ship — affects prioritisation) - **Team context** (who is doing the testing — developers / dedicated QA / both) -## Output Structure +## Output Format ### 1. Test Scope @@ -118,10 +118,3 @@ Testing is complete when: - [ ] P0 test cases cover the highest-risk paths specifically - [ ] Each test type names a concrete tool (not "some testing framework") - [ ] Definition of Done is measurable (not "tests are done when QA is happy") - -## Example Trigger Phrases -- "Write a test strategy for [feature]" + [paste spec or PRD] -- "Create a test plan for [system]" -- "How should we test [feature]?" -- "I need a QA plan for this sprint" -- "What tests do we need for [X]?"