# API Docs > Api Docs - Skill: `dnyoussef/api-docs` (Agent Skill, multi-file: 18 files) - Install (CLI): `npx skillmds@latest add dnyoussef/api-docs` - Raw SKILL.md: https://api.skillmd.com/api/skills/dnyoussef/api-docs/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: DNYoussef (https://skillmd.com/u/dnyoussef) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/dnyoussef/api-docs --- /*============================================================================*/ /* API-DOCS SKILL :: VERILINGUA x VERIX EDITION */ /*============================================================================*/ --- name: api-docs version: 1.0.0 description: | [assert|neutral] Generate and maintain comprehensive API documentation using OpenAPI 3.0, Swagger UI, and GraphQL Playground. Use when documenting REST APIs, GraphQL services, or creating API reference materials. Ensu [ground:given] [conf:0.95] [state:confirmed] category: delivery tags: - delivery - development - workflow author: ruv cognitive_frame: primary: aspectual goal_analysis: first_order: "Execute api-docs workflow" second_order: "Ensure quality and consistency" third_order: "Enable systematic delivery processes" --- /*----------------------------------------------------------------------------*/ /* S0 META-IDENTITY */ /*----------------------------------------------------------------------------*/ [define|neutral] SKILL := { name: "api-docs", category: "delivery", version: "1.0.0", layer: L1 } [ground:given] [conf:1.0] [state:confirmed] /*----------------------------------------------------------------------------*/ /* S1 COGNITIVE FRAME */ /*----------------------------------------------------------------------------*/ [define|neutral] COGNITIVE_FRAME := { frame: "Aspectual", source: "Russian", force: "Complete or ongoing?" } [ground:cognitive-science] [conf:0.92] [state:confirmed] ## Kanitsal Cerceve (Evidential Frame Activation) Kaynak dogrulama modu etkin. /*----------------------------------------------------------------------------*/ /* S2 TRIGGER CONDITIONS */ /*----------------------------------------------------------------------------*/ [define|neutral] TRIGGER_POSITIVE := { keywords: ["api-docs", "delivery", "workflow"], context: "user needs api-docs capability" } [ground:given] [conf:1.0] [state:confirmed] /*----------------------------------------------------------------------------*/ /* S3 CORE CONTENT */ /*----------------------------------------------------------------------------*/ # API Documentation Generator (Gold Tier) ## Kanitsal Cerceve (Evidential Frame Activation) Kaynak dogrulama modu etkin. ## When to Use This Skill - **API Development**: Building or documenting REST APIs, GraphQL APIs, or other web services - **API Versioning**: Managing multiple API versions or migration strategies - **Developer Experience**: Creating interactive documentation for API consumers - **OpenAPI/Swagger**: Generating or maintaining OpenAPI specifications - **Integration Work**: Helping external teams understand and use your APIs ## When NOT to Use This Skill - **Non-API Documentation**: General code documentation, user manuals, or internal wikis - **No API Surface**: Pure frontend apps, CLI tools, or embedded systems without APIs - **Legacy Systems**: APIs without code access or with undocumented proprietary protocols - **Incompatible Stacks**: Non-HTTP protocols (MQTT, gRPC) requiring specialized tooling ## Success Criteria - [ ] API endpoints fully documented with request/response schemas - [ ] Authentication and authorization flows clearly explained - [ ] Interactive API explorer (Swagger UI/GraphQL Playground) functional - [ ] Error codes and handling strategies documented - [ ] Rate limiting and usage guidelines specified - [ ] Code examples provided for common use cases - [ ] Versioning strategy documented if applicable ## Edge Cases to Handle - **Missing Type Annotations**: Infer schemas from runtime behavior or database models - **Dynamic Routes**: Document parameterized endpoints and path variables - **Nested Resources**: Handle complex resource hierarchies and relationships - **File Uploads**: Document multipart/form-data and binary payloads - **Webhooks**: Document callback URLs and event payloads - **Deprecated Endpoints**: Mark sunset dates and migration paths ## Guardrails - **NEVER** expose internal implementation details or security vulnerabilities in public docs - **ALWAYS** validate generated specs against OpenAPI/GraphQL schema validators - **NEVER** ship documentation without testing example requests - **ALWAYS** include authentication requirements for protected endpoints - **NEVER** assume default values - explicitly document all parameters - **ALWAYS** document error responses, not just success cases ## Evidence-Based Validation - [ ] Run generated OpenAPI spec through swagger-cli validate - [ ] Test all documented endpoints with actual HTTP requests - [ ] Verify GraphQL schema with graphql-schema-linter - [ ] Check accessibility of interactive docs with axe-core - [ ] Validate examples compile and execute successfully - [ ] Review documentation with API consumers for clarity Generate production-quality API documentation with OpenAPI 3.0, automated validation, and interactive documentation formats. ## When to Use This Skill Use when documenting new or existing APIs, creating REST API specifications, maintaining GraphQL schema documentation, or generating interactive API explorers with Swagger UI/GraphQL Playground. Ideal for API-first development, maintaining accurate documentation, and ensuring OpenAPI 3.0 compliance. ## API Documentation Types ### REST API Documentation - OpenAPI 3.0 specifications - Endpoint descriptions and parameters - Request/response examples - Authentication schemes - Error codes and handling ### GraphQL Documentation - Schema definitions - Query and mutation documentation - Type system reference - Resolver documentation ## Process 1. **Analyze API structure** - Identify all endpoints/operations - Document request/response schemas - Define authentication requirements - Catalog error responses 2. **Generate OpenAPI/GraphQL spec** - Write structured YAML/SDL definitions - Include comprehensive examples - Document edge cases - Add usage guidelines 3. **Create interactive documentation** - Configure Swagger UI for REST APIs - Set up GraphQL Playground - Add authentication testing support - Enable "Try It Out" fu /*----------------------------------------------------------------------------*/ /* S4 SUCCESS CRITERIA */ /*----------------------------------------------------------------------------*/ [define|neutral] SUCCESS_CRITERIA := { primary: "Skill execution completes successfully", quality: "Output meets quality thresholds", verification: "Results validated against requirements" } [ground:given] [conf:1.0] [state:confirmed] /*----------------------------------------------------------------------------*/ /* S5 MCP INTEGRATION */ /*----------------------------------------------------------------------------*/ [define|neutral] MCP_INTEGRATION := { memory_mcp: "Store execution results and patterns", tools: ["mcp__memory-mcp__memory_store", "mcp__memory-mcp__vector_search"] } [ground:witnessed:mcp-config] [conf:0.95] [state:confirmed] /*----------------------------------------------------------------------------*/ /* S6 MEMORY NAMESPACE */ /*----------------------------------------------------------------------------*/ [define|neutral] MEMORY_NAMESPACE := { pattern: "skills/delivery/api-docs/{project}/{timestamp}", store: ["executions", "decisions", "patterns"], retrieve: ["similar_tasks", "proven_patterns"] } [ground:system-policy] [conf:1.0] [state:confirmed] [define|neutral] MEMORY_TAGGING := { WHO: "api-docs-{session_id}", WHEN: "ISO8601_timestamp", PROJECT: "{project_name}", WHY: "skill-execution" } [ground:system-policy] [conf:1.0] [state:confirmed] /*----------------------------------------------------------------------------*/ /* S7 SKILL COMPLETION VERIFICATION */ /*----------------------------------------------------------------------------*/ [direct|emphatic] COMPLETION_CHECKLIST := { agent_spawning: "Spawn agents via Task()", registry_validation: "Use registry agents only", todowrite_called: "Track progress with TodoWrite", work_delegation: "Delegate to specialized agents" } [ground:system-policy] [conf:1.0] [state:confirmed] /*----------------------------------------------------------------------------*/ /* S8 ABSOLUTE RULES */ /*----------------------------------------------------------------------------*/ [direct|emphatic] RULE_NO_UNICODE := forall(output): NOT(unicode_outside_ascii) [ground:windows-compatibility] [conf:1.0] [state:confirmed] [direct|emphatic] RULE_EVIDENCE := forall(claim): has(ground) AND has(confidence) [ground:verix-spec] [conf:1.0] [state:confirmed] [direct|emphatic] RULE_REGISTRY := forall(agent): agent IN AGENT_REGISTRY [ground:system-policy] [conf:1.0] [state:confirmed] /*----------------------------------------------------------------------------*/ /* PROMISE */ /*----------------------------------------------------------------------------*/ [commit|confident] API_DOCS_VERILINGUA_VERIX_COMPLIANT [ground:self-validation] [conf:0.99] [state:confirmed]