@codeharbor/agent-playbook 0.1.0 → 0.1.2

package/skills/api-documenter/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: api-documenter
+description: API documentation specialist for OpenAPI/Swagger specifications. Use when documenting REST or GraphQL APIs.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# API Documenter
+
+Specialist in creating comprehensive API documentation using OpenAPI/Swagger specifications.
+
+## When This Skill Activates
+
+Activates when you:
+- Ask to document an API
+- Create OpenAPI/Swagger specs
+- Need API reference documentation
+- Mention "API docs"
+
+## OpenAPI Specification Structure
+
+```yaml
+openapi: 3.0.3
+info:
+  title: API Title
+  version: 1.0.0
+  description: API description
+servers:
+  - url: https://example.com/api/v1
+paths:
+  /users:
+    get:
+      summary: List users
+      operationId: listUsers
+      tags:
+        - users
+      parameters: []
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+```
+
+## Endpoint Documentation
+
+For each endpoint, document:
+
+### Required Fields
+- **summary**: Brief description
+- **operationId**: Unique identifier
+- **description**: Detailed explanation
+- **tags**: For grouping
+- **responses**: All possible responses
+
+### Recommended Fields
+- **parameters**: All parameters with details
+- **requestBody**: For POST/PUT/PATCH
+- **security**: Authentication requirements
+- **deprecated**: If applicable
+
+### Example
+
+```yaml
+/users/{id}:
+  get:
+    summary: Get a user by ID
+    operationId: getUserById
+    description: Retrieves a single user by their unique identifier
+    tags:
+      - users
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: The user ID
+    responses:
+      '200':
+        description: User found
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/User'
+      '404':
+        description: User not found
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Error'
+```
+
+## Schema Documentation
+
+### Best Practices
+
+1. **Use references** for shared schemas
+2. **Add descriptions** to all properties
+3. **Specify format** for strings (email, uuid, date-time)
+4. **Add examples** for complex schemas
+5. **Mark required fields**
+
+### Example
+
+```yaml
+components:
+  schemas:
+    User:
+      type: object
+      required:
+        - id
+        - email
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique user identifier
+          example: "550e8400-e29b-41d4-a716-446655440000"
+        email:
+          type: string
+          format: email
+          description: User's email address
+          example: "user@example.com"
+        createdAt:
+          type: string
+          format: date-time
+          description: Account creation timestamp
+```
+
+## Authentication Documentation
+
+Document auth requirements:
+
+```yaml
+security:
+  - bearerAuth: []
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: Use your JWT token from /auth/login
+```
+
+## Error Responses
+
+Standard error format:
+
+```yaml
+components:
+  schemas:
+    Error:
+      type: object
+      properties:
+        error:
+          type: string
+          description: Error message
+        code:
+          type: string
+          description: Application-specific error code
+        details:
+          type: object
+          description: Additional error details
+```
+
+Common HTTP status codes:
+- **200**: Success
+- **201**: Created
+- **204**: No Content
+- **400**: Bad Request
+- **401**: Unauthorized
+- **403**: Forbidden
+- **404**: Not Found
+- **409**: Conflict
+- **422**: Unprocessable Entity
+- **500**: Internal Server Error
+
+## Scripts
+
+Generate OpenAPI spec from code:
+```bash
+python scripts/generate_openapi.py
+```
+
+Validate OpenAPI spec:
+```bash
+python scripts/validate_openapi.py openapi.yaml
+```
+
+## References
+
+- `references/openapi-template.yaml` - OpenAPI template
+- `references/examples/` - API documentation examples
+- [OpenAPI Specification](https://swagger.io/specification/)

package/skills/api-documenter/references/examples/README.md

@@ -0,0 +1,3 @@
+# OpenAPI Examples
+
+This directory contains small OpenAPI examples for reference.

package/skills/api-documenter/references/examples/openapi-example.yaml

@@ -0,0 +1,10 @@
+openapi: 3.0.3
+info:
+  title: Sample API
+  version: 0.1.0
+paths:
+  /health:
+    get:
+      responses:
+        '200':
+          description: OK

package/skills/api-documenter/references/openapi-template.yaml

@@ -0,0 +1,5 @@
+openapi: 3.0.3
+info:
+  title: Example API
+  version: 1.0.0
+paths: {}

package/skills/api-documenter/scripts/generate_openapi.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+# Template generator for OpenAPI schema.
+
+from pathlib import Path
+import argparse
+import textwrap
+
+
+def write_output(path: Path, content: str, force: bool) -> bool:
+    if path.exists() and not force:
+        print(f"{path} already exists (use --force to overwrite)")
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return True
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate a starter OpenAPI schema.")
+    parser.add_argument("--output", default="openapi.yaml", help="Output file path")
+    parser.add_argument("--name", default="example", help="Resource name")
+    parser.add_argument("--version", default="1.0.0", help="API version")
+    parser.add_argument(
+        "--base-url", default="https://example.com", help="Server base URL"
+    )
+    parser.add_argument("--force", action="store_true", help="Overwrite existing file")
+    args = parser.parse_args()
+
+    schema_name = "".join(part.capitalize() for part in args.name.split("-"))
+    if not schema_name:
+        schema_name = "Example"
+
+    content = textwrap.dedent(
+        f"""\
+        openapi: 3.0.3
+        info:
+          title: {args.name} API
+          version: {args.version}
+          description: API description for {args.name}
+        servers:
+          - url: {args.base_url}
+        paths:
+          /{args.name}:
+            get:
+              summary: List {args.name}
+              responses:
+                "200":
+                  description: OK
+                  content:
+                    application/json:
+                      schema:
+                        type: object
+                        properties:
+                          items:
+                            type: array
+                            items:
+                              $ref: "#/components/schemas/{schema_name}"
+        components:
+          schemas:
+            {schema_name}:
+              type: object
+              properties:
+                id:
+                  type: string
+                name:
+                  type: string
+          securitySchemes:
+            bearerAuth:
+              type: http
+              scheme: bearer
+        security:
+          - bearerAuth: []
+        """
+    ).strip() + "\n"
+
+    output = Path(args.output)
+    if not write_output(output, content, args.force):
+        return 1
+    print(f"Wrote {output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/api-documenter/scripts/validate_openapi.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+# Template validator for OpenAPI schema.
+
+from pathlib import Path
+import argparse
+
+DEFAULT_REQUIRED = [
+    "openapi:",
+    "info:",
+    "servers:",
+    "paths:",
+    "components:",
+    "securitySchemes:",
+]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate a generated artifact.")
+    parser.add_argument("--input", default="openapi.yaml", help="Input file path")
+    parser.add_argument(
+        "--require",
+        action="append",
+        default=[],
+        help="Additional required section heading",
+    )
+    args = parser.parse_args()
+
+    path = Path(args.input)
+    if not path.exists():
+        print(f"Missing file: {path}")
+        return 1
+
+    text = path.read_text(encoding="utf-8", errors="ignore")
+    required = DEFAULT_REQUIRED + args.require
+    missing = [token for token in required if token not in text]
+    if missing:
+        print("Missing required sections: " + ", ".join(missing))
+        return 1
+
+    print(f"Validated {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/architecting-solutions/README.md

@@ -0,0 +1,22 @@
+# Architecting Solutions
+
+> A Claude Code skill for technical solution and architecture design.
+
+## Installation
+
+This skill is part of the [agent-playbook](https://github.com/Charon-Fan/agent-playbook) collection.
+
+## Usage
+
+```
+You: Design solution for a new billing system
+You: Provide an architecture design for multi-tenant analytics
+You: Technical design for a data migration plan
+```
+
+## Focus Areas
+
+1. **Clarify requirements** and success criteria
+2. **Analyze constraints** and existing patterns
+3. **Propose options** with trade-offs
+4. **Document the decision** in a PRD-style output in `docs/`