add folders in plugins
This commit is contained in:
mohitagw15856
Vendored
BIN
Binary file not shown.
@@ -0,0 +1,146 @@
|
||||
---
|
||||
name: api-docs-writer
|
||||
description: "Write clear, developer-facing API documentation. Use when asked to document an API endpoint, write API reference docs, create a developer guide, or turn a raw spec/Postman collection into documentation. Produces endpoint documentation with descriptions, parameters, request/response examples, and error codes."
|
||||
---
|
||||
|
||||
# API Docs Writer Skill
|
||||
|
||||
This skill transforms raw API specs, endpoint descriptions, or Postman collections into clean, developer-facing documentation following OpenAPI-adjacent conventions. Output is ready for a developer portal, README, or Notion/Confluence page.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **API or endpoint details** (raw spec, Postman export, or verbal description)
|
||||
- **Auth method** (API key / Bearer token / OAuth 2.0 / None)
|
||||
- **Base URL**
|
||||
- **Audience** (internal developers / external partners / public)
|
||||
- **Output format** (Markdown / OpenAPI YAML / Plain prose)
|
||||
|
||||
## Output Structure
|
||||
|
||||
For each endpoint, produce the following:
|
||||
|
||||
---
|
||||
|
||||
## `[METHOD] /path/to/endpoint`
|
||||
|
||||
**Summary:** [One line — what this endpoint does]
|
||||
|
||||
**Description:** [2–4 sentences. When to use this endpoint. What it returns. Any important behaviour to know (pagination, rate limits, async processing, etc.)]
|
||||
|
||||
**Authentication:** [Required / Optional — method]
|
||||
|
||||
---
|
||||
|
||||
### Request
|
||||
|
||||
**Headers:**
|
||||
|
||||
| Header | Required | Description |
|
||||
|---|---|---|
|
||||
| `Authorization` | Yes | `Bearer <token>` |
|
||||
| `Content-Type` | Yes | `application/json` |
|
||||
|
||||
**Path Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `id` | string | Yes | Unique identifier for the resource |
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|---|---|---|---|---|
|
||||
| `limit` | integer | No | 20 | Max results per page (1–100) |
|
||||
| `cursor` | string | No | — | Pagination cursor from previous response |
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"field_name": "value",
|
||||
"another_field": 42
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `field_name` | string | Yes | [Plain description of what this field does] |
|
||||
| `another_field` | integer | No | [Description. Include valid range or enum values if applicable] |
|
||||
|
||||
---
|
||||
|
||||
### Response
|
||||
|
||||
**Success Response: `200 OK`**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "abc123",
|
||||
"status": "active",
|
||||
"created_at": "2025-04-01T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `id` | string | Unique identifier for the created/retrieved resource |
|
||||
| `status` | string | Current status. Enum: `active`, `inactive`, `pending` |
|
||||
| `created_at` | ISO 8601 string | Timestamp of creation in UTC |
|
||||
|
||||
---
|
||||
|
||||
### Error Codes
|
||||
|
||||
| Status Code | Error Code | Description | How to Resolve |
|
||||
|---|---|---|---|
|
||||
| `400` | `INVALID_REQUEST` | Request body is malformed or missing required fields | Check request body against schema above |
|
||||
| `401` | `UNAUTHORIZED` | Missing or invalid authentication token | Verify your API key or refresh your token |
|
||||
| `404` | `NOT_FOUND` | The requested resource does not exist | Check the ID in the path parameter |
|
||||
| `429` | `RATE_LIMITED` | Too many requests | Back off and retry after `Retry-After` header value |
|
||||
| `500` | `INTERNAL_ERROR` | Unexpected server error | Retry with exponential backoff; contact support if persists |
|
||||
|
||||
---
|
||||
|
||||
### Code Examples
|
||||
|
||||
Produce examples in at least 2 languages relevant to the audience (default: cURL + Python):
|
||||
|
||||
**cURL:**
|
||||
```bash
|
||||
curl -X POST https://api.example.com/v1/endpoint \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"field_name": "value"}'
|
||||
```
|
||||
|
||||
**Python:**
|
||||
```python
|
||||
import requests
|
||||
|
||||
response = requests.post(
|
||||
"https://api.example.com/v1/endpoint",
|
||||
headers={"Authorization": "Bearer YOUR_TOKEN"},
|
||||
json={"field_name": "value"}
|
||||
)
|
||||
data = response.json()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every parameter is documented (type, required/optional, description)
|
||||
- [ ] Response fields are fully documented with types
|
||||
- [ ] All relevant error codes are listed with resolution guidance
|
||||
- [ ] Code examples are copy-paste runnable (no pseudocode)
|
||||
- [ ] 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"
|
||||
@@ -0,0 +1,117 @@
|
||||
---
|
||||
name: architecture-decision-record
|
||||
description: "Create an Architecture Decision Record (ADR) for any technical decision. Use when asked to document a technical decision, write an ADR, record an architecture choice, or capture why a technology or approach was selected. Produces a structured ADR with context, decision, consequences, and tradeoffs."
|
||||
---
|
||||
|
||||
# Architecture Decision Record (ADR) Skill
|
||||
|
||||
This skill produces a complete Architecture Decision Record (ADR) following the Nygard format — the most widely adopted standard. ADRs document the reasoning behind significant technical decisions so future team members understand not just *what* was decided, but *why*.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Decision title** (brief, e.g. "Use PostgreSQL as primary datastore")
|
||||
- **Context** (what situation led to this decision needing to be made?)
|
||||
- **Options considered** (at least 2; if only 1 is given, prompt for alternatives that were considered or ruled out)
|
||||
- **Decision made** (which option was chosen)
|
||||
- **Reason for choice**
|
||||
- **Status** (Proposed / Accepted / Deprecated / Superseded)
|
||||
- **Author and date**
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# ADR-[NNN]: [Decision Title]
|
||||
|
||||
**Date:** [YYYY-MM-DD]
|
||||
**Status:** [Proposed / Accepted / Deprecated / Superseded by ADR-NNN]
|
||||
**Author(s):** [Name(s)]
|
||||
**Deciders:** [Who had final say — individual or team]
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
[3–6 sentences. Describe the situation, constraints, and forces at play that made this decision necessary. Include: the problem being solved, relevant system state, team constraints, timeline pressures, or non-negotiable requirements. Write as if explaining to someone joining the team 18 months from now who has no prior context.]
|
||||
|
||||
**Key constraints:**
|
||||
- [Constraint 1: e.g. "Must be deployable on-premise for enterprise customers"]
|
||||
- [Constraint 2: e.g. "Team has no prior Go experience"]
|
||||
- [Add as many as are relevant]
|
||||
|
||||
---
|
||||
|
||||
## Options Considered
|
||||
|
||||
For each option, produce:
|
||||
|
||||
### Option [N]: [Name]
|
||||
|
||||
**Description:** [What this option is — 1–3 sentences]
|
||||
|
||||
**Pros:**
|
||||
- [Pro 1]
|
||||
- [Pro 2]
|
||||
|
||||
**Cons:**
|
||||
- [Con 1]
|
||||
- [Con 2]
|
||||
|
||||
**Why this was ruled out (if not chosen):** [Honest reason]
|
||||
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
**We will [chosen option].**
|
||||
|
||||
[2–4 sentences explaining the decision in plain language. This should be readable in isolation — someone should understand the decision from this paragraph alone without reading the full document.]
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive Consequences
|
||||
- [What this decision enables or improves]
|
||||
- [What risk it mitigates]
|
||||
|
||||
### Negative Consequences / Accepted Tradeoffs
|
||||
- [What we're giving up or taking on as a result of this decision]
|
||||
- [Technical debt or limitations introduced]
|
||||
- [What must now be true for this decision to remain valid]
|
||||
|
||||
### Risks
|
||||
- [What could cause this decision to be wrong in hindsight]
|
||||
- [What would trigger us to revisit this decision]
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
[Optional but valuable: any specific patterns, gotchas, or guidance for the team implementing based on this decision. Link to relevant tickets, RFCs, or design docs if applicable.]
|
||||
|
||||
---
|
||||
|
||||
## Review Date
|
||||
|
||||
[Optional: "This decision should be reviewed if [condition] — e.g. team grows beyond 20 engineers, or traffic exceeds 10M requests/day."]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Context explains the *why* — not just the *what*
|
||||
- [ ] At least 2 options are documented (including the rejected ones)
|
||||
- [ ] Rejected options include honest reasons for rejection
|
||||
- [ ] Consequences include *negative* consequences — no decision is consequence-free
|
||||
- [ ] 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]"
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
name: code-review-checklist
|
||||
description: "Generate a tailored code review checklist for any PR, language, or risk level. Use when asked to create a code review checklist, review guidelines, PR standards, or quality gates for a codebase. Produces a structured, prioritised checklist adapted to the specific language, PR type, and risk level."
|
||||
---
|
||||
|
||||
# Code Review Checklist Skill
|
||||
|
||||
This skill generates a structured, prioritised code review checklist tailored to a specific PR, language, and risk level. It helps reviewers be thorough without being bureaucratic.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Programming language(s)** (e.g. Python, TypeScript, Go, Java)
|
||||
- **PR type** (new feature / bug fix / refactor / performance improvement / security patch / infrastructure change)
|
||||
- **Risk level** (Low: internal tooling, Low traffic / Medium: user-facing feature / High: payment, auth, data pipeline, public API)
|
||||
- **Team context** (optional: team size, seniority mix, any known recurring issues)
|
||||
|
||||
## Output Structure
|
||||
|
||||
### 1. Checklist Header
|
||||
|
||||
**PR:** [Title if provided]
|
||||
**Language:** [Language]
|
||||
**Type:** [PR Type]
|
||||
**Risk Level:** [Low / Medium / High]
|
||||
**Estimated review depth:** [Quick scan ~15 min / Standard ~30 min / Deep review ~60 min+]
|
||||
|
||||
---
|
||||
|
||||
### 2. The Checklist
|
||||
|
||||
Organise into sections. Mark each item with a priority indicator:
|
||||
- 🔴 **MUST** — Blocking. PR should not merge without this.
|
||||
- 🟡 **SHOULD** — Important. Address before merge unless there's a good reason not to.
|
||||
- 🟢 **CONSIDER** — Nice to have. Worth a comment but not blocking.
|
||||
|
||||
#### Section A: Correctness
|
||||
- 🔴 Does the code do what the ticket/requirement describes?
|
||||
- 🔴 Are edge cases handled? (nulls, empty arrays, zero values, max values)
|
||||
- 🔴 Are error states handled and surfaced appropriately?
|
||||
- 🟡 Does the happy path have adequate test coverage?
|
||||
- 🟡 Are failure paths tested?
|
||||
|
||||
#### Section B: Security (scale with risk level — expand for High risk PRs)
|
||||
- 🔴 [High risk only] Is user input sanitised before use in queries or commands?
|
||||
- 🔴 [High risk only] Are auth/permission checks in place?
|
||||
- 🟡 Are secrets/credentials committed anywhere? (check .env handling)
|
||||
- 🟡 Are third-party dependencies known-safe versions?
|
||||
|
||||
#### Section C: Performance
|
||||
- 🟡 Are there N+1 query patterns in database calls?
|
||||
- 🟡 Is there unnecessary work inside loops?
|
||||
- 🟢 Are database queries indexed appropriately?
|
||||
- 🟢 Is caching considered where appropriate?
|
||||
|
||||
#### Section D: Readability & Maintainability
|
||||
- 🟡 Are function and variable names clear without needing a comment to explain them?
|
||||
- 🟡 Are complex logic blocks explained with inline comments?
|
||||
- 🟢 Is the code consistent with existing patterns in the codebase?
|
||||
- 🟢 Are there any magic numbers that should be named constants?
|
||||
|
||||
#### Section E: Language-Specific Checks
|
||||
[Populate this section based on the specified language. Examples below:]
|
||||
|
||||
**Python:**
|
||||
- 🟡 Are type hints used on function signatures?
|
||||
- 🟡 Are exceptions caught specifically (not bare `except:`)?
|
||||
- 🟢 Does it follow PEP 8 (or the team's linter config)?
|
||||
|
||||
**TypeScript/JavaScript:**
|
||||
- 🔴 Are there any `any` types that should be properly typed?
|
||||
- 🟡 Are async/await patterns used consistently (no mixed Promise.then chains)?
|
||||
- 🟢 Are there unnecessary re-renders in React components?
|
||||
|
||||
**Go:**
|
||||
- 🔴 Are errors checked (not ignored with `_`)?
|
||||
- 🟡 Are goroutines properly managed to prevent leaks?
|
||||
- 🟢 Are exported functions documented?
|
||||
|
||||
#### Section F: PR Hygiene
|
||||
- 🟡 Is the PR a reasonable size? (>500 lines diff suggests it should be split)
|
||||
- 🟡 Does the PR description explain *why*, not just *what*?
|
||||
- 🟢 Are there linked tickets or context in the PR description?
|
||||
- 🟢 Are migration scripts or deployment notes included if needed?
|
||||
|
||||
---
|
||||
|
||||
### 3. Risk-Specific Additions
|
||||
|
||||
For **High risk** PRs, always add:
|
||||
- 🔴 Has this been tested in a staging environment?
|
||||
- 🔴 Is there a rollback plan?
|
||||
- 🔴 Has a second reviewer been assigned?
|
||||
|
||||
For **Infrastructure / DB changes**, always add:
|
||||
- 🔴 Are migrations backward-compatible?
|
||||
- 🔴 Has the migration been tested against production data volume?
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Checklist is tailored to the specified language (not generic)
|
||||
- [ ] Risk level is reflected in the MUST vs SHOULD balance
|
||||
- [ ] Language-specific section covers the most common issues for that language
|
||||
- [ ] PR hygiene section is always present
|
||||
- [ ] High-risk additions are included when risk level = High
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Generate a code review checklist for a Python bug fix PR"
|
||||
- "Give me a review checklist for a high-risk TypeScript auth change"
|
||||
- "What should I check in this Go PR?"
|
||||
- "Create PR review standards for our team"
|
||||
@@ -0,0 +1,144 @@
|
||||
---
|
||||
name: incident-postmortem
|
||||
description: "Write a structured incident postmortem or post-incident review. Use when asked to write a postmortem, incident report, P1/P2 review, outage report, or RCA (root cause analysis). Generates a blameless postmortem with timeline, root cause, contributing factors, impact summary, and action items."
|
||||
---
|
||||
|
||||
# Incident Postmortem Skill
|
||||
|
||||
This skill produces a complete, blameless incident postmortem document following industry-standard format. Output is ready to share with engineering teams, leadership, and affected stakeholders.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Incident title / ID**
|
||||
- **Severity** (P1 / P2 / P3 or SEV1 / SEV2 / SEV3)
|
||||
- **Date and duration** of the incident
|
||||
- **What happened** (rough notes are fine — the skill will structure them)
|
||||
- **Services or systems affected**
|
||||
- **Customer impact** (how many users, what was degraded)
|
||||
- **How it was detected**
|
||||
- **How it was resolved**
|
||||
- **Initial thoughts on root cause**
|
||||
- **Action items already identified** (optional)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Incident Postmortem: [Incident Title]
|
||||
|
||||
**Incident ID:** [ID]
|
||||
**Severity:** [P1/P2/P3]
|
||||
**Date:** [Date]
|
||||
**Duration:** [Start time → Resolution time — total duration]
|
||||
**Status:** [Resolved / Monitoring / Ongoing]
|
||||
**Author:** [Leave blank for user to fill]
|
||||
**Last updated:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
[3–5 sentences. Describe what happened, who was affected, and what was done to resolve it. Written for a non-technical stakeholder. No jargon. No blame.]
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
| Dimension | Details |
|
||||
|---|---|
|
||||
| **Users affected** | [Number or percentage] |
|
||||
| **Services degraded** | [List affected services] |
|
||||
| **Business impact** | [Revenue, SLA breach, support tickets, etc. if known] |
|
||||
| **Duration** | [Total time from first detection to full resolution] |
|
||||
|
||||
---
|
||||
|
||||
## Timeline
|
||||
|
||||
List events in chronological order. Each entry: `[HH:MM UTC] — [What happened. Who did what. What changed.]`
|
||||
|
||||
Rules for timeline entries:
|
||||
- Use passive or system-focused language — avoid "X made a mistake"
|
||||
- Include: first symptom, detection, escalation, hypothesis tested, fix applied, confirmation of resolution
|
||||
- Note time between key events (e.g. "22 minutes between detection and escalation")
|
||||
|
||||
---
|
||||
|
||||
## Root Cause
|
||||
|
||||
**Primary root cause:** [One clear sentence. Technical but plain. "A misconfigured deployment config caused..."]
|
||||
|
||||
**Contributing factors:**
|
||||
- [Factor 1 — e.g. lack of canary deployment meant change hit 100% of traffic immediately]
|
||||
- [Factor 2 — e.g. alert threshold was set too high to catch the initial degradation]
|
||||
- [Factor 3 — add as many as are relevant]
|
||||
|
||||
**Why did our existing safeguards not prevent this?**
|
||||
[Honest paragraph explaining why monitoring, tests, or processes didn't catch this earlier. This is where blameless analysis matters most — focus on system gaps, not individual failures.]
|
||||
|
||||
---
|
||||
|
||||
## Detection
|
||||
|
||||
- **How was it first detected?** [Customer report / automated alert / internal monitoring / manual observation]
|
||||
- **Time from incident start to detection:** [X minutes]
|
||||
- **Should we have detected this faster?** [Yes / No — and why]
|
||||
|
||||
---
|
||||
|
||||
## Resolution
|
||||
|
||||
**What fixed it?** [Clear description of the actual fix — one paragraph]
|
||||
**Why did this work?** [Brief technical explanation]
|
||||
**Was there a temporary mitigation before full resolution?** [Yes/No — describe if yes]
|
||||
|
||||
---
|
||||
|
||||
## Action Items
|
||||
|
||||
| # | Action | Owner | Due Date | Priority |
|
||||
|---|---|---|---|---|
|
||||
| 1 | [Specific, testable action] | [Team or person] | [Date] | P1/P2/P3 |
|
||||
|
||||
Rules for action items:
|
||||
- Each action must be specific enough to close as "done" or "not done" — no vague items like "improve monitoring"
|
||||
- Distinguish between: **Prevent recurrence** (fix the root cause), **Improve detection** (catch it faster next time), **Improve response** (resolve it faster next time)
|
||||
- Assign a real owner — not "team" or "TBD" if avoidable
|
||||
- Flag P1 actions as items that block the incident from being marked fully closed
|
||||
|
||||
---
|
||||
|
||||
## What Went Well
|
||||
|
||||
[3–5 honest observations about the response. Include: fast collaboration, good runbooks used, effective escalation, clear communication. This section builds team confidence and reinforces good habits.]
|
||||
|
||||
---
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
[3–5 key insights from this incident that are worth sharing beyond this team. Write these as transferable lessons — e.g. "Our runbook for database failover didn't account for read-replica lag. All runbooks involving database failover should be reviewed."]
|
||||
|
||||
---
|
||||
|
||||
## Communication Log
|
||||
|
||||
[Optional — list external communications sent: status page updates, customer emails, support responses. Include timestamps.]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Timeline has no blame-focused language
|
||||
- [ ] Root cause is specific (not "human error")
|
||||
- [ ] Contributing factors explain the systemic gaps
|
||||
- [ ] 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]"
|
||||
Reference in New Issue
Block a user