diff --git a/.gitignore b/.gitignore index edcc064..9da0463 100644 --- a/.gitignore +++ b/.gitignore @@ -1,12 +1,64 @@ -```markdown -# Documentation -docs/specification.md ``` +# Compiled and binary files +*.pyc +*.class +*.o +*.obj +*.out +*.exe +*.dll +*.so +*.a -Wait, I need to reconsider this. The file `docs/specification.md` is a source file being modified, not a build artifact or temporary file. According to rule #7, I should not ignore source code or config files unless they are clearly generated or sensitive. Since this appears to be a regular markdown documentation file, it should NOT be added to .gitignore. +# Dependencies +node_modules/ +venv/ +.venv/ +__pycache__/ +.mypy_cache/ +.pytest_cache/ +dist/ +build/ +target/ +.gradle/ -Given that only a source file (`.md`) was modified and there are no build artifacts, dependencies, or temp files in the changes, the correct output is empty. +# Editor/IDE files +.vscode/ +.idea/ +*.swp +*.swo +*.tmp -```markdown +# System/Environment files +.DS_Store +Thumbs.db +.env +.env.local +*.env.* +# Logs and coverage +*.log +coverage/ +htmlcov/ +.coverage + +# Compressed files +*.zip +*.gz +*.tar +*.tgz +*.bz2 +*.xz +*.7z +*.rar +*.zst +*.lz4 +*.lzh +*.cab +*.arj +*.rpm +*.deb +*.Z +*.lz +*.lzo ``` \ No newline at end of file diff --git a/skills/example-skill/api-documentation-generator/SKILL.md b/skills/example-skill/api-documentation-generator/SKILL.md new file mode 100644 index 0000000..cbbd531 --- /dev/null +++ b/skills/example-skill/api-documentation-generator/SKILL.md @@ -0,0 +1,453 @@ +--- +name: api-documentation-generator +description: > + Generate comprehensive API documentation from code, OpenAPI/Swagger specs, + or endpoint descriptions. Use when the user provides function signatures, + route definitions, Postman collections, or raw API code and requests + "document this API", "generate usage examples", or "create a reference guide". + Do NOT use for writing API design proposals, generating mock servers, + testing API endpoints, or documenting non-API code (libraries, CLIs, UI components). +version: "1.0" +tags: [api, documentation, openapi, rest, graphql, sdk] +context_priority: high +--- + +# API Documentation Generator + +This skill guides creation of clear, comprehensive API documentation from +various input sources (code, specs, or descriptions). The user provides +endpoint definitions, function signatures, or existing API code and optionally +specifies output format (Markdown, OpenAPI, HTML, SDK docs). Apply the workflow +below, then return structured documentation with examples, error codes, and +usage guidelines. + +## 🎯 When to Use + +- User shares API route definitions, controller code, or function signatures +- User provides an OpenAPI/Swagger spec and requests improvements or format conversion +- User asks to "document this endpoint", "generate API reference", or "write usage examples" +- Input includes Postman collections, Insomnia exports, or curl command lists +- **Do NOT use** when the user wants to design a new API from scratch without + existing code — refer them to API design workflows first +- **Do NOT use** for generating mock servers, test suites, or API gateway configs — + these are separate tooling concerns +- **Do NOT use** for documenting non-API code (utility libraries, CLI tools, + React components) unless they expose HTTP/GraphQL/gRPC endpoints + +## 🧠 Core Workflow + +**Step 1 — Ingest & Detect Format** +Parse the input to identify its type and extract relevant metadata: +- **Code-first**: Controller files (Express, Flask, FastAPI, Spring), route definitions +- **Spec-first**: OpenAPI YAML/JSON, Swagger 2.0, RAML, API Blueprint +- **Collection-based**: Postman JSON, Insomnia exports, curl/wget commands +- **Ad-hoc**: Informal descriptions, markdown tables, or verbal endpoint descriptions + +Detect: +- API style: REST, GraphQL, gRPC, WebSocket, RPC +- Authentication method: API keys, OAuth2, JWT, Basic Auth, mTLS +- Data formats: JSON, XML, Protocol Buffers, form-data +- Framework conventions: Express middleware, Flask decorators, FastAPI annotations + +If the format is ambiguous or incomplete, ask one targeted clarifying question +before proceeding (e.g., "Is this a REST API or GraphQL schema?"). + +**Step 2 — Extract Endpoint Metadata** +For each endpoint, catalog: + +1. **Route Information** + - HTTP method(s): GET, POST, PUT, PATCH, DELETE, OPTIONS + - Path pattern with parameters: `/users/{id}/posts/{postId}` + - Query parameters with types and defaults: `?limit=10&offset=0` + - Path parameters with constraints: `{id}` must be integer > 0 + +2. **Request Schema** + - Headers required/optional: `Authorization`, `Content-Type`, custom headers + - Body schema (for POST/PUT/PATCH): JSON structure, validation rules, examples + - Form data fields (for multipart/form-data): field names, file upload support + +3. **Response Schema** + - Success responses by status code: 200, 201, 204 + - Error responses: 400, 401, 403, 404, 409, 422, 500 + - Response body structure with types and nested objects + - Pagination format if applicable: cursor-based, offset-based, page-based + +4. **Side Effects & Behavior** + - Idempotency: Is repeated execution safe? + - Rate limiting: Requests per minute/hour, burst allowances + - Caching behavior: Cache headers, ETag support, invalidation rules + - Async operations: Does it return immediately or require polling/webhook? + +**Step 3 — Enrich with Usage Context** +Add practical guidance that raw specs often omit: + +1. **Authentication Examples** + - Show exactly how to authenticate for each supported method + - Include token acquisition flow if relevant (OAuth2 grant types) + - Demonstrate header/certificate placement for each auth type + +2. **Common Usage Patterns** + - Typical request/response cycles for primary use cases + - Chaining multiple endpoints for complex workflows + - Handling pagination for list endpoints + - Batch operations if supported + +3. **Error Handling Guide** + - Map error codes to human-readable explanations + - Provide retry strategies (exponential backoff, circuit breaker) + - Distinguish client errors (fix your request) from server errors (retry later) + - Include troubleshooting tips for common failure modes + +4. **Edge Cases & Gotchas** + - Rate limit exhaustion behavior + - Partial failure handling in batch operations + - Timeouts and long-running operation patterns + - Versioning strategy and deprecation timeline + +**Step 4 — Generate Documentation Structure** +Organize content following industry-standard API doc conventions: + +``` +1. Overview + - API purpose and scope + - Base URL and environment variants (prod, staging, sandbox) + - Authentication summary + - Versioning scheme + +2. Quick Start + - First API call example (copy-paste ready) + - Authentication setup walkthrough + - Common integration patterns + +3. Authentication + - Supported methods with detailed setup + - Token lifecycle and refresh flows + - Security best practices + +4. Endpoints (grouped by resource/domain) + - Per-endpoint sections with full request/response details + +5. Error Handling + - Error code reference table + - Retry guidelines + - Debugging tips + +6. Rate Limiting + - Limits by endpoint or tier + - Headers for monitoring quota + - Upgrade paths for higher limits + +7. Webhooks (if applicable) + - Event types and payloads + - Subscription management + - Signature verification + +8. SDKs & Code Examples + - Official/community library links + - Multi-language snippets (curl, Python, JS, Java, Go) + +9. Changelog + - Version history with breaking change highlights +``` + +**Step 5 — Validate & Return Output** +Cross-check generated docs against source material: +- Verify all endpoints from input are documented +- Confirm request/response schemas match exactly (no invented fields) +- Test code examples for syntax accuracy (language-specific validation) +- Ensure authentication flow is complete and actionable + +Provide structured JSON index followed by full Markdown documentation. + +## 📋 Output Format + +Return two sections: + +**Section 1 — Documentation Index (JSON)** + +```json +{ + "status": "success | partial | error", + "metadata": { + "api_name": "Inferred or provided name", + "api_version": "v1, 2.0, etc.", + "base_url": "https://api.example.com", + "api_style": "rest | graphql | grpc | websocket", + "auth_methods": ["bearer_token", "api_key"], + "endpoints_count": 12, + "input_format": "openapi | code | postman | ad-hoc" + }, + "endpoints": [ + { + "id": "EP1", + "method": "GET", + "path": "/users/{id}", + "summary": "Retrieve a user by ID", + "operation_id": "getUserById", + "tags": ["Users"], + "authenticated": true, + "rate_limited": true, + "deprecated": false, + "has_request_body": false, + "response_codes": [200, 404, 401], + "pagination": null + } + ], + "authentication": { + "methods": [ + { + "type": "bearer_token", + "header": "Authorization", + "format": "Bearer ", + "acquisition": "POST /oauth/token with client credentials" + } + ] + }, + "errors_documented": [ + {"code": 400, "meaning": "Bad Request"}, + {"code": 401, "meaning": "Unauthorized"}, + {"code": 404, "meaning": "Not Found"}, + {"code": 429, "meaning": "Rate Limit Exceeded"} + ], + "warnings": [ + { + "type": "missing_info | ambiguous_schema | incomplete_auth_flow", + "detail": "Description of what was unclear or missing from input", + "suggestion": "How to resolve (e.g., 'Provide response schema for 409 Conflict')" + } + ] +} +``` + +**Section 2 — Full Documentation (Markdown)** + +Generate complete Markdown documentation with the following structure: + +```markdown +# API Reference: [API Name] + +**Version:** v1 +**Base URL:** `https://api.example.com/v1` +**Auth:** Bearer Token, API Key + +--- + +## Quick Start + +Make your first API call: + +```bash +curl -X GET "https://api.example.com/v1/users/me" \ + -H "Authorization: Bearer YOUR_API_TOKEN" +``` + +Response: +```json +{ + "id": "usr_123", + "email": "user@example.com", + "created_at": "2026-01-15T10:30:00Z" +} +``` + +--- + +## Authentication + +### Bearer Token + +Include the token in the `Authorization` header: + +``` +Authorization: Bearer eyJhbGciOiJIUzI1NiIs... +``` + +#### Obtaining a Token + +```bash +curl -X POST "https://api.example.com/oauth/token" \ + -H "Content-Type: application/json" \ + -d '{ + "grant_type": "client_credentials", + "client_id": "YOUR_CLIENT_ID", + "client_secret": "YOUR_CLIENT_SECRET" + }' +``` + +--- + +## Endpoints + +### Users + +#### GET `/users/{id}` + +Retrieve a user by their unique identifier. + +**Parameters:** + +| Name | In | Type | Required | Description | +|------|----|------|----------|-------------| +| id | path | string | Yes | User ID (prefix `usr_`) | + +**Response:** `200 OK` + +```json +{ + "id": "usr_123", + "email": "user@example.com", + "name": "Jane Doe", + "created_at": "2026-01-15T10:30:00Z" +} +``` + +**Errors:** + +| Code | Meaning | Description | +|------|---------|-------------| +| 404 | Not Found | User with given ID does not exist | +| 401 | Unauthorized | Missing or invalid authentication token | + +**Example:** + +```python +import requests + +response = requests.get( + "https://api.example.com/v1/users/usr_123", + headers={"Authorization": "Bearer YOUR_TOKEN"} +) +print(response.json()) +``` + +[Continue for all endpoints...] + +--- + +## Error Handling + +### Error Response Format + +All errors follow this schema: + +```json +{ + "error": { + "code": "RESOURCE_NOT_FOUND", + "message": "User usr_999 does not exist", + "details": {...} + } +} +``` + +### Common Errors + +| HTTP Code | Error Code | Description | Resolution | +|-----------|------------|-------------|------------| +| 400 | INVALID_REQUEST | Request body fails validation | Check schema and retry | +| 401 | UNAUTHORIZED | Missing or expired token | Refresh token and retry | +| 429 | RATE_LIMITED | Too many requests | Wait and implement backoff | + +### Retry Strategy + +For 429 and 5xx errors, implement exponential backoff: + +```python +import time + +def retry_with_backoff(func, max_retries=3): + for i in range(max_retries): + try: + return func() + except RateLimitError: + wait_time = (2 ** i) + random.uniform(0, 1) + time.sleep(wait_time) + raise MaxRetriesExceeded() +``` + +--- + +## Rate Limiting + +| Tier | Requests/min | Requests/day | +|------|--------------|--------------| +| Free | 60 | 1,000 | +| Pro | 600 | 50,000 | +| Enterprise | Custom | Custom | + +Monitor your quota via response headers: + +``` +X-RateLimit-Limit: 60 +X-RateLimit-Remaining: 45 +X-RateLimit-Reset: 1647352800 +``` + +--- + +## Changelog + +### v1.2.0 (2026-03-01) +- Added: `PATCH /users/{id}` for partial updates +- Deprecated: `PUT /users/{id}` (remove by v2.0) + +### v1.1.0 (2026-01-15) +- Added: Pagination for list endpoints +- Fixed: Date format inconsistency in responses +``` + +## ⚠️ Fallback Behavior + +If the input cannot be parsed as API definitions (no routes, no endpoints, +no recognizable spec format), respond with: + +```json +{ + "status": "error", + "message": "Input does not appear to be API definitions. Expected OpenAPI spec, route handlers, Postman collection, or endpoint descriptions.", + "suggestion": "Please provide your API code, spec file, or describe your endpoints with methods and paths." +} +``` + +If critical information is missing (e.g., response schemas, authentication method), +return partial documentation with explicit warnings: + +```json +{ + "status": "partial", + "message": "Documentation generated but some sections are incomplete due to missing input data.", + "warnings": [ + { + "type": "missing_response_schema", + "detail": "No response schema provided for POST /users; inferred from request body", + "suggestion": "Provide explicit response examples for accurate documentation" + }, + { + "type": "unknown_auth_method", + "detail": "Authentication method not specified; documented common patterns generically", + "suggestion": "Specify auth type (bearer, api_key, oauth2) for tailored guidance" + } + ], + "documentation_generated": true +} +``` + +If the API appears incomplete or inconsistent (e.g., referenced resources without +corresponding endpoints, circular dependencies in schemas), flag these issues: + +```json +{ + "status": "partial", + "warnings": [ + { + "type": "inconsistent_api_design", + "detail": "Endpoint DELETE /users/{id}/posts references 'posts' resource with no dedicated endpoints", + "suggestion": "Consider adding CRUD endpoints for posts or clarify relationship semantics" + } + ] +} +``` + +Never invent endpoints, fabricate response schemas, or assume authentication +flows without evidence. If uncertain, document what is known and explicitly +flag gaps for human review. diff --git a/skills/example-skill/meeting-transcriber/SKILL.md b/skills/example-skill/meeting-transcriber/SKILL.md new file mode 100644 index 0000000..c90aa65 --- /dev/null +++ b/skills/example-skill/meeting-transcriber/SKILL.md @@ -0,0 +1,245 @@ +--- +name: meeting-transcriber +description: > + Transform raw meeting transcripts, voice-to-text outputs, or conversation notes + into structured summaries with action items, decisions, and key discussion points. + Use when the user provides a transcript dump, Zoom/Teams export, or rough notes + and requests "summarize this meeting", "extract action items", or "what did we decide?". + Do NOT use for generating meeting agendas from scratch, scheduling meetings, + transcribing audio files directly, or analyzing non-meeting conversations + (e.g., customer support chats, interviews, depositions). +version: "1.0" +tags: [meetings, transcription, summarization, action-items, productivity] +context_priority: high +--- + +# Meeting Transcriber + +This skill guides transformation of raw meeting transcripts into structured, +actionable summaries. The user provides unstructured text from a meeting +(transcript, voice-to-text output, or rough notes) and optionally specifies +focus areas (decisions only, action items, full summary). Apply the workflow +below, then return a structured summary with clear ownership and deadlines. + +## 🎯 When to Use + +- User pastes a meeting transcript, Zoom/Teams/Google Meet export, or voice-to-text output +- User shares rough meeting notes and requests "clean this up" or "what did we decide?" +- User asks to extract action items, decisions, or key discussion points from a conversation +- Transcript contains multiple speakers, timestamps, or disorganized dialogue +- **Do NOT use** when the user wants to generate a meeting agenda from scratch, + schedule meetings, or transcribe raw audio/video files — refer them to appropriate + transcription or scheduling tools +- **Do NOT use** for non-meeting conversations (customer support logs, job interviews, + legal depositions, therapy sessions) — these require domain-specific workflows +- **Do NOT use** when the input is already a clean, structured summary — no processing needed + +## 🧠 Core Workflow + +**Step 1 — Ingest & Parse** +Detect the input format: raw transcript (speaker labels + timestamps), voice-to-text +(no speaker separation), or bullet notes. Identify: +- Number of speakers (detect patterns like "Speaker 1:", "[John]:", etc.) +- Presence of timestamps and their format +- Meeting metadata if available (date, title, attendees list) +If speaker labels are missing or inconsistent, normalize to `Speaker 1`, `Speaker 2`, etc. +and flag this limitation in warnings. + +**Step 2 — Segment by Topic** +Group dialogue into thematic clusters using keyword detection and conversation flow: +- Detect topic shifts via phrases like "moving on to", "next item", "let's discuss" +- Cluster related exchanges even if interrupted by tangents +- Label each segment with a descriptive heading (e.g., "Q3 Budget Review", "API Redesign Discussion") +If the transcript lacks clear topic boundaries, segment by time intervals (every 5-10 min) +and infer topics post-hoc from content analysis. + +**Step 3 — Extract Structured Elements** +For each segment, identify and categorize: + +1. **Decisions** — Look for explicit agreement markers: + - "Let's do X", "We agreed on Y", "Decision: Z", "Okay, we'll go with..." + - Capture the decision, who proposed it, who approved it, and any dissenting opinions + - Flag ambiguous outcomes ("we'll think about it") as `⚠️ pending` rather than decisions + +2. **Action Items** — Extract tasks with the following schema: + - **Owner**: Who is responsible (detect "I'll...", "[Name] will...", "assign this to...") + - **Task**: What needs to be done (verb-first description) + - **Deadline**: When it's due (explicit dates, "by EOW", "before next meeting") + - **Priority**: Infer from urgency language ("ASAP", "blocker", "nice-to-have") + If owner/deadline is missing, flag as `⚠️ incomplete action item` and suggest follow-up + +3. **Key Discussion Points** — Summarize substantive exchanges: + - Capture arguments for/against proposals with attribution + - Note data points, metrics, or evidence cited + - Flag unresolved debates or open questions requiring future discussion + +4. **Risks & Blockers** — Identify impediments mentioned: + - Dependencies on other teams, technical constraints, resource gaps + - Capture severity and proposed mitigation if discussed + +**Step 4 — Validate & Cross-Check** +Review extracted elements against the original transcript: +- Verify action item owners are actual participants (not misattributed) +- Confirm deadlines are realistic and explicitly stated (not inferred unless obvious) +- Check that decisions reflect consensus, not unilateral statements +- Flag any contradictions (e.g., two conflicting decisions in same meeting) +If confidence is low on any extraction, include it with a `⚠️ low-confidence` warning +rather than silently omitting or fabricating details. + +**Step 5 — Return Output** +Provide structured JSON report followed by optional human-readable executive summary. +Always include attendee inference, meeting duration (if timestamps available), and +completeness score (% of action items with clear owner + deadline). + +## 📋 Output Format + +Return two sections: + +**Section 1 — Meeting Summary Report** + +```json +{ + "status": "success | partial | error", + "metadata": { + "meeting_title": "Inferred or provided title", + "meeting_date": "YYYY-MM-DD or null", + "duration_minutes": 0, + "attendees_inferred": ["Alice", "Bob", "Charlie"], + "attendees_provided": [], + "speakers_detected": 3, + "segments_identified": 5 + }, + "decisions": [ + { + "id": "D1", + "topic": "Segment name where decision was made", + "decision": "Clear statement of what was decided", + "proposed_by": "Name or null", + "approved_by": ["Name1", "Name2"], + "dissenting_opinions": ["Name expressed concern about X"], + "confidence": "high | medium | low", + "timestamp": "HH:MM:SS or null" + } + ], + "action_items": [ + { + "id": "A1", + "owner": "Name or ⚠️ unassigned", + "task": "Verb-first task description", + "deadline": "YYYY-MM-DD or relative (EOW, next meeting) or ⚠️ unspecified", + "priority": "critical | high | medium | low", + "related_decision_id": "D1 or null", + "status": "new | in_progress | blocked", + "notes": "Additional context or dependencies mentioned" + } + ], + "discussion_summary": [ + { + "topic": "Descriptive heading", + "summary": "2-3 sentence synthesis of key points", + "key_contributors": ["Name1", "Name2"], + "outcome": "decision_made | deferred | ongoing_discussion", + "related_decision_ids": ["D1"], + "related_action_item_ids": ["A1", "A2"] + } + ], + "risks_blockers": [ + { + "description": "Clear statement of the blocker", + "severity": "critical | high | medium | low", + "owner": "Name responsible for resolving or null", + "mitigation_proposed": "What was suggested or null", + "dependencies": ["Team X", "External vendor", "Budget approval"] + } + ], + "open_questions": [ + "Question that requires follow-up or research before next meeting" + ], + "warnings": [ + { + "type": "missing_speaker_labels | ambiguous_decision | incomplete_action_item | low_confidence", + "detail": "Description of the issue and its impact on reliability", + "suggestion": "How to resolve or verify (e.g., 'Confirm with Alice if she owns A3')" + } + ], + "completeness_score": 0.85 +} +``` + +**Section 2 — Executive Summary (Optional)** + +If requested, provide a markdown-formatted one-pager: + +```markdown +## Meeting Summary: [Title] +**Date:** YYYY-MM-DD | **Duration:** X min | **Attendees:** Alice, Bob, Charlie + +### 🔑 Key Decisions +- **D1:** [Decision statement] — Approved by [Names] + +### ✅ Action Items +| ID | Owner | Task | Deadline | Priority | +|----|-------|------|----------|----------| +| A1 | Alice | Deploy v2.3 | 2026-05-01 | High | + +### ⚠️ Blockers +- [Blocker description] — Owner: [Name], Severity: High + +### ❓ Open Questions +- [Question requiring follow-up] +``` + +## ⚠️ Fallback Behavior + +If the input cannot be identified as a meeting transcript (no dialogue structure, +no action items, no decisions), respond with: + +```json +{ + "status": "error", + "message": "Input does not appear to be a meeting transcript. Expected dialogue with multiple speakers, action items, or decision discussions.", + "suggestion": "Please paste the transcript directly or clarify if this is a different type of document (e.g., monologue, article, chat log)." +} +``` + +If the transcript is severely garbled (voice-to-text errors >30%, missing context), +return a partial extraction with explicit warnings: + +```json +{ + "status": "partial", + "message": "Transcript quality is low; some extractions may be inaccurate.", + "warnings": [ + { + "type": "low_transcript_quality", + "detail": "Voice-to-text errors detected; speaker attribution unreliable", + "suggestion": "Manual review recommended before distributing summary" + } + ], + "extractions_attempted": {...} +} +``` + +If action items or decisions are completely absent (e.g., brainstorming session +with no conclusions), explicitly state this rather than fabricating structure: + +```json +{ + "status": "success", + "metadata": {...}, + "decisions": [], + "action_items": [], + "discussion_summary": [...], + "warnings": [ + { + "type": "no_decisions_or_actions", + "detail": "Meeting was exploratory; no concrete decisions or action items identified", + "suggestion": "Consider scheduling a follow-up to finalize next steps" + } + ] +} +``` + +Never invent action items, assign owners without evidence, or fabricate deadlines. +If the user requests a specific output format (e.g., Jira tickets, Asana tasks, +email draft), adapt Section 2 accordingly while preserving the JSON report in Section 1.