Context: The WeBuddhist team (backend, frontend, app devs) uses GitHub issue cards to document API endpoints during integration. Cards must be consistent so any dev can scan them and know: what's the endpoint, what goes in, what comes out, and what can go wrong. This skill generates those cards.
Accepted Inputs:
- OpenAPI/Swagger spec (YAML/JSON) → extract endpoints automatically
- Natural language → "we added a language filter to GET /plans/tags"
- Inline details → method, path, params, response pasted in chat
- Existing issue number → reads via
gh issue viewfor context - Any combination of the above
Instructions:
-
Parse the input. Extract: HTTP method, path, query params, request body, response body, status codes, headers. If info is missing, mark as
[TBD]. -
Pick the card type:
- New endpoint → full card
- Endpoint edit → full card + "Current Behavior" / "Proposed Change" sections after Context
- Backend fix → full card, focus Context on the bug, still include the related endpoint and response so devs know which API surface is affected
-
Generate the card using the template below. Do NOT output any conversational text — output ONLY the formatted markdown so it can be directly copied into GitHub.
-
Show the card to the user for review. Wait for approval before proceeding.
-
After approval, ask for target repo:
- Run:
gh repo list <org> --limit 50 --json name,description - Show list, user picks
- Run:
-
Ask for project board:
- First check auth scope:
gh auth status— ifprojectscope is missing, tell user to rungh auth refresh -s project - Run:
gh project list --owner <org> --format json - Show list, user picks
- First check auth scope:
-
Create and link:
gh issue create --repo <org>/<repo> --title "<title>" --body "<body>"gh project item-add <project-number> --owner <org> --url <issue-url>- Show the issue URL
Never auto-create. Always: generate → review → repo → board → create.
Card Template:
# <Short clear title>
## Context
<1-2 sentences: why this endpoint exists, or what's changing and why>
## Endpoint
\`\`\`
<METHOD> <path>
\`\`\`
## Headers
| Header | Required | Description |
|--------|----------|-------------|
| `Authorization` | Yes | Bearer token |
## Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
## Request Body
\`\`\`json
{}
\`\`\`
## Response
**200 OK**
\`\`\`json
{}
\`\`\`
## Status Codes
| Code | Description |
|------|-------------|
| 200 | Success |
| 401 | Unauthorized |
| 404 | Not found |
| 422 | Validation error |
## Notes
- <Edge cases, gotchas, related issues>
Omit sections that don't apply (e.g., no Request Body for GET, no Query Params for POST with body only).
For endpoint edits, add after Context:
## Current Behavior
## Proposed Change
Prerequisites:
- The
ghtoken needs theprojectscope. If project commands fail, run:gh auth refresh -s project
Rules:
- Realistic example values — Tibetan text for
bofields (སྒོམ), UUIDs for IDs, real names like "Morning Meditation" - Multilingual fields as objects:
{ "en": "Meditation", "bo": "སྒོམ" } - OpenAPI schemas → concrete JSON examples, not raw schema
- Short scannable notes — bullets, not paragraphs
[TBD]for unknowns, never invent behavior- Always ask user to pick repo and project board