@codeharbor/agent-playbook 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeharbor/agent-playbook",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "One-click installer and workflow fixer for agent-playbook across Claude Code and Codex.",
   "license": "MIT",
   "type": "commonjs",
@@ -9,11 +9,14 @@
   },
   "scripts": {
     "test": "node --test test/*.test.js",
-    "lint": "node -c src/cli.js"
+    "lint": "node -c src/cli.js",
+    "prepack": "node scripts/sync-skills.js copy",
+    "postpack": "node scripts/sync-skills.js clean"
   },
   "files": [
     "bin",
     "src",
+    "skills",
     "templates",
     "README.md",
     "LICENSE"

package/skills/api-designer/README.md

@@ -0,0 +1,36 @@
+# API Designer
+
+> A Claude Code skill for REST and GraphQL API design.
+
+## Installation
+
+This skill is part of the [agent-playbook](https://github.com/Charon-Fan/agent-playbook) collection.
+
+## Usage
+
+```
+You: Design an API for user management
+You: Create API specification
+You: Review this API design
+```
+
+## API Design Principles
+
+1. **Resource-Oriented**: Nouns, not verbs
+2. **Consistent Naming**: kebab-case for URLs
+3. **Proper HTTP Methods**: GET, POST, PUT, DELETE
+4. **Status Codes**: Correct HTTP status codes
+5. **Versioning**: Plan for API evolution
+
+## Scripts
+
+Generate API scaffold:
+```bash
+python scripts/generate_api.py <resource-name>
+```
+
+## Resources
+
+- [REST API Tutorial](https://restfulapi.net/)
+- [GraphQL Best Practices](https://graphql.org/learn/best-practices/)
+- [API Design Guidelines](https://github.com/microsoft/api-guidelines)

package/skills/api-designer/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: api-designer
+description: REST and GraphQL API architect for designing robust, scalable APIs. Use when designing new APIs or improving existing ones.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch
+---
+
+# API Designer
+
+Expert in designing REST and GraphQL APIs that are robust, scalable, and maintainable.
+
+## When This Skill Activates
+
+Activates when you:
+- Design a new API
+- Review API design
+- Improve existing API
+- Create API specifications
+
+## REST API Design Principles
+
+### 1. Resource-Oriented Design
+
+**Good:**
+```
+GET    /users          # List users
+POST   /users          # Create user
+GET    /users/{id}     # Get specific user
+PATCH  /users/{id}     # Update user
+DELETE /users/{id}     # Delete user
+```
+
+**Avoid:**
+```
+POST   /getUsers       # Should be GET
+POST   /users/create  # Redundant
+GET    /users/get/{id} # Redundant
+```
+
+### 2. HTTP Methods
+
+| Method | Safe | Idempotent | Purpose |
+|--------|------|------------|---------|
+| GET | ✓ | ✓ | Read resource |
+| POST | ✗ | ✗ | Create resource |
+| PUT | ✗ | ✓ | Replace resource |
+| PATCH | ✗ | ✗ | Update resource |
+| DELETE | ✗ | ✓ | Delete resource |
+
+### 3. Status Codes
+
+| Code | Meaning | Usage |
+|------|---------|-------|
+| 200 | OK | Successful GET, PATCH, DELETE |
+| 201 | Created | Successful POST |
+| 204 | No Content | Successful DELETE with no body |
+| 400 | Bad Request | Invalid input |
+| 401 | Unauthorized | Missing or invalid auth |
+| 403 | Forbidden | Authenticated but not authorized |
+| 404 | Not Found | Resource doesn't exist |
+| 409 | Conflict | Resource already exists |
+| 422 | Unprocessable | Valid syntax but semantic errors |
+| 429 | Too Many Requests | Rate limit exceeded |
+| 500 | Internal Server Error | Server error |
+
+### 4. Naming Conventions
+
+- **URLs**: kebab-case (`/user-preferences`)
+- **JSON**: camelCase (`{"userId": "123"}`)
+- **Query params**: snake_case or camelCase (`?page_size=10`)
+
+### 5. Pagination
+
+```http
+GET /users?page=1&page_size=20
+
+Response:
+{
+  "data": [...],
+  "pagination": {
+    "page": 1,
+    "page_size": 20,
+    "total": 100,
+    "total_pages": 5
+  }
+}
+```
+
+### 6. Filtering and Sorting
+
+```http
+GET /users?status=active&sort=-created_at,name
+
+# -created_at = descending
+# name = ascending
+```
+
+## GraphQL API Design
+
+### Schema Design
+
+```graphql
+type Query {
+  user(id: ID!): User
+  users(limit: Int, offset: Int): UserConnection!
+}
+
+type Mutation {
+  createUser(input: CreateUserInput!): CreateUserPayload!
+  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
+}
+
+type User {
+  id: ID!
+  email: String!
+  profile: Profile
+  posts(first: Int, after: String): PostConnection!
+}
+
+type UserConnection {
+  edges: [UserEdge!]!
+  pageInfo: PageInfo!
+}
+
+type UserEdge {
+  node: User!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+```
+
+### Best Practices
+
+- **Nullability**: Default to non-null, nullable only when appropriate
+- **Connections**: Use cursor-based pagination for lists
+- **Payloads**: Use mutation payloads for consistent error handling
+- **Descriptions**: Document all types and fields
+
+## API Versioning
+
+### Approaches
+
+**URL Versioning** (Recommended):
+```
+/api/v1/users
+/api/v2/users
+```
+
+**Header Versioning**:
+```
+GET /users
+Accept: application/vnd.myapi.v2+json
+```
+
+### Versioning Guidelines
+
+- Start with v1
+- Maintain backwards compatibility when possible
+- Deprecate old versions with notice
+- Document breaking changes
+
+## Authentication & Authorization
+
+### Authentication Methods
+
+1. **JWT Bearer Token**
+```http
+Authorization: Bearer <token>
+```
+
+2. **API Key**
+```http
+X-API-Key: <key>
+```
+
+3. **OAuth 2.0**
+```http
+Authorization: Bearer <access_token>
+```
+
+### Authorization
+
+- Use roles/permissions
+- Document required permissions per endpoint
+- Return 403 for authorization failures
+
+## Rate Limiting
+
+```http
+HTTP/1.1 200 OK
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 999
+X-RateLimit-Reset: 1631234567
+```
+
+**Recommended limits:**
+- Public APIs: 100-1000 requests/hour
+- Authenticated APIs: 1000-10000 requests/hour
+- Webhooks: 10-100 requests/minute
+
+## Documentation Requirements
+
+- All endpoints documented
+- Request/response examples
+- Authentication requirements
+- Error response formats
+- Rate limits
+- SDK examples (if available)
+
+## Scripts
+
+Generate API scaffold:
+```bash
+python scripts/generate_api.py <resource-name>
+```
+
+Validate API design:
+```bash
+python scripts/validate_api.py openapi.yaml
+```
+
+## References
+
+- `references/rest-patterns.md` - REST design patterns
+- `references/graphql-patterns.md` - GraphQL design patterns
+- [REST API Tutorial](https://restfulapi.net/)
+- [GraphQL Best Practices](https://graphql.org/learn/best-practices/)

package/skills/api-designer/references/graphql-patterns.md

@@ -0,0 +1,12 @@
+# GraphQL Patterns
+
+## Schema Design
+- Use clear type names
+- Avoid overly generic fields
+
+## Pagination
+- Prefer cursor-based pagination
+
+## Mutations
+- Use input objects for complex mutations
+- Return updated entities and errors

package/skills/api-designer/references/rest-patterns.md

@@ -0,0 +1,17 @@
+# REST Patterns
+
+## Resource Naming
+- Use nouns (e.g., /users)
+- Use plural for collections
+
+## Methods
+- GET for retrieval
+- POST for creation
+- PUT/PATCH for updates
+- DELETE for removal
+
+## Status Codes
+- 200 OK
+- 201 Created
+- 204 No Content
+- 400/401/403/404 for errors

package/skills/api-designer/scripts/generate_api.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+# Template generator for API design.
+
+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 API design.")
+    parser.add_argument("--output", default="api-design.md", help="Output file path")
+    parser.add_argument("--name", default="example", help="Primary resource name")
+    parser.add_argument("--owner", default="team", help="Owning team or service")
+    parser.add_argument("--force", action="store_true", help="Overwrite existing file")
+    args = parser.parse_args()
+
+    content = textwrap.dedent(
+        f"""\
+        # API Design
+
+        ## Overview
+        Describe the API for {args.name}.
+
+        ## Ownership
+        - Owner: {args.owner}
+        - Stakeholders: TBD
+
+        ## Goals
+        - Provide CRUD for {args.name}
+        - Maintain backward compatibility
+
+        ## Non-Goals
+        - Bulk export
+        - Cross-service transactions
+
+        ## Resources
+        - {args.name}
+        - {args.name}-metadata
+
+        ## Endpoints
+        | Method | Path | Description | Auth |
+        | --- | --- | --- | --- |
+        | GET | /{args.name} | List {args.name} | Required |
+        | POST | /{args.name} | Create {args.name} | Required |
+
+        ## Authentication
+        - OAuth2 bearer tokens
+        - Service-to-service mTLS
+
+        ## Error Model
+        - Use RFC7807 problem details
+        - Standard error codes and retry hints
+
+        ## Pagination and Filtering
+        - Cursor-based pagination
+        - Filter by status, owner, and created_at
+
+        ## Rate Limits
+        - 100 rps per token, burst 200
+
+        ## Observability
+        - Structured logs with request_id
+        - Metrics: latency, error rate, saturation
+
+        ## Open Questions
+        - Define data retention policy
+        """
+    ).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-designer/scripts/validate_api.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+# Template validator for API design.
+
+from pathlib import Path
+import argparse
+
+DEFAULT_REQUIRED = [
+    "## Overview",
+    "## Ownership",
+    "## Resources",
+    "## Endpoints",
+    "## Authentication",
+    "## Error Model",
+    "## Pagination",
+    "## Rate Limits",
+]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate a generated artifact.")
+    parser.add_argument("--input", default="api-design.md", 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")
+    text_lower = text.lower()
+    required = DEFAULT_REQUIRED + args.require
+    missing = [section for section in required if section.lower() not in text_lower]
+    if missing:
+        print("Missing required sections: " + ", ".join(missing))
+        return 1
+
+    print(f"Validated {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/api-documenter/README.md

@@ -0,0 +1,41 @@
+# API Documenter
+
+> A Claude Code skill for OpenAPI/Swagger API documentation.
+
+## Installation
+
+This skill is part of the [agent-playbook](https://github.com/Charon-Fan/agent-playbook) collection.
+
+## Usage
+
+```
+You: Document this API
+You: Create OpenAPI spec
+You: Generate API documentation
+```
+
+## OpenAPI Specification
+
+The skill generates OpenAPI 3.0 specifications following:
+- RESTful conventions
+- Clear resource naming
+- Complete request/response documentation
+- Authentication requirements
+- Error response formats
+
+## Scripts
+
+Generate OpenAPI spec:
+```bash
+python scripts/generate_openapi.py
+```
+
+Validate OpenAPI spec:
+```bash
+python scripts/validate_openapi.py openapi.yaml
+```
+
+## Resources
+
+- [OpenAPI Specification](https://swagger.io/specification/)
+- [Swagger Tools](https://swagger.io/tools/)

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.