@soulcraft/kits 1.0.0

package/kits/api-documentation/skills/api-versioning/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: api-versioning
+description: Background expertise in API versioning strategies and deprecation best practices
+type: background
+version: "1.0.0"
+---
+
+## API Versioning Expertise
+
+You have expertise in API versioning strategies and managing API evolution. Apply these principles when helping users design and document APIs.
+
+### Versioning Strategies
+
+**URL Path Versioning**
+```
+https://api.example.com/v1/users
+https://api.example.com/v2/users
+```
+- Pros: Clear, visible, easy caching
+- Cons: Changes URLs, client updates needed
+- Best for: Major version changes
+
+**Query Parameter Versioning**
+```
+https://api.example.com/users?version=1
+https://api.example.com/users?version=2
+```
+- Pros: Same URL, easy testing
+- Cons: Can be missed, caching complications
+- Best for: Optional versioning
+
+**Header Versioning**
+```
+Accept: application/vnd.example.v1+json
+X-API-Version: 1
+```
+- Pros: Clean URLs, RESTful
+- Cons: Less visible, harder to test
+- Best for: Sophisticated clients
+
+**Content Negotiation**
+```
+Accept: application/vnd.example+json; version=1
+```
+- Pros: Most RESTful approach
+- Cons: Complex, tooling challenges
+- Best for: API purists
+
+### When to Version
+
+**Major Version (v1 → v2)**
+- Breaking changes to response structure
+- Removed endpoints or fields
+- Changed authentication
+- Fundamental behavior changes
+
+**No Version Needed**
+- Adding new optional fields
+- Adding new endpoints
+- Bug fixes
+- Performance improvements
+
+### Deprecation Strategy
+
+**Timeline**
+1. Announce deprecation (6+ months notice)
+2. Add deprecation headers
+3. Update documentation
+4. Monitor usage
+5. Final sunset
+
+**Deprecation Headers**
+```
+Deprecation: true
+Sunset: Sat, 31 Dec 2024 23:59:59 GMT
+Link: <https://api.example.com/v2/users>; rel="successor-version"
+```
+
+**Documentation**
+- Mark deprecated in OpenAPI spec
+- Add migration guide
+- List breaking changes
+- Provide upgrade path
+
+### Breaking vs Non-Breaking Changes
+
+**Breaking Changes (Require New Version)**
+- Removing fields/endpoints
+- Changing field types
+- Changing required fields
+- Renaming fields
+- Changing error formats
+- Removing enum values
+
+**Non-Breaking Changes (Safe to Add)**
+- New optional fields
+- New endpoints
+- New optional parameters
+- New enum values (usually)
+- Relaxing validation
+- Adding headers
+
+### Migration Best Practices
+
+**For API Providers**
+- Run versions in parallel
+- Provide migration tools/scripts
+- Monitor old version usage
+- Communicate clearly and early
+- Offer migration support
+
+**Documentation for Migrations**
+```markdown
+## Migrating from v1 to v2
+
+### Breaking Changes
+| v1 | v2 | Migration |
+|----|----|----|
+| `username` | `email` | Rename field |
+| `GET /user` | `GET /users/{id}` | Update endpoint |
+
+### New Features in v2
+- Field X added
+- Endpoint Y improved
+
+### Timeline
+- v2 available: January 1, 2024
+- v1 deprecated: July 1, 2024
+- v1 sunset: January 1, 2025
+```
+
+### API Evolution Patterns
+
+**Expand-Contract Pattern**
+1. Add new field alongside old (expand)
+2. Migrate clients to new field
+3. Remove old field (contract)
+
+**Feature Flags**
+- Enable new behavior for opt-in clients
+- Gradually migrate
+- Flip default, then remove flag
+
+**API Gateway Versioning**
+- Route different versions to different backends
+- Transform requests/responses at gateway
+- Simplifies backend code
+
+### Common Mistakes
+
+- No versioning strategy from start
+- Breaking changes without version bump
+- Inconsistent versioning across endpoints
+- No deprecation warnings
+- Sunset without migration path
+- Keeping old versions forever

package/kits/api-documentation/skills/create-code-examples/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: Generate Code Examples
+description: Create SDK/language-specific code examples for endpoints
+type: invocable
+version: "1.0.0"
+parameters: [language, endpoint]
+---
+
+## Generate Code Examples
+
+Create SDK/language-specific code examples for endpoints
+
+### Steps
+
+1. Identify the target programming language(s)
+2. Review the endpoint documentation for request/response format
+3. Create a code example showing authentication setup
+4. Create the API call with proper error handling
+5. Show how to parse and use the response
+6. Add inline comments explaining each step
+7. Test or validate the example logic
+
+### Inputs Required
+
+- **language** (required): Target language (JavaScript, Python, Ruby, curl)
+- **endpoint** (required): Which endpoint to create examples for
+
+### Expected Outputs
+
+- Code examples in specified language
+
+### When to Use
+
+This workflow is helpful when the user mentions:
+- "code example"
+- "sdk example"
+- "how to call"
+- "sample code"
+
+### Execution Mode
+
+This workflow can be executed automatically when triggered. Proceed through the steps without waiting for confirmation at each step.

package/kits/api-documentation/skills/define-resource/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: Define API Resource
+description: Create documentation for a new API resource type
+type: invocable
+version: "1.0.0"
+parameters: [resourceName, description]
+---
+
+## Define API Resource
+
+Create documentation for a new API resource type
+
+### Steps
+
+1. Define the resource name and description
+2. Create the resource schema with all properties and types
+3. Identify required vs optional properties
+4. Document relationships to other resources
+5. Create standard CRUD endpoints for the resource
+6. Add example resource objects
+7. Update the resource index
+
+### Inputs Required
+
+- **resourceName** (required): Name of the resource (singular form)
+- **description** (required): Brief description of what this resource represents
+
+### Expected Outputs
+
+- Resource documentation
+- CRUD endpoint stubs
+
+### When to Use
+
+This workflow is helpful when the user mentions:
+- "new resource"
+- "add resource"
+- "define resource"
+- "create resource"

package/kits/api-documentation/skills/document-auth/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: Document Authentication
+description: Create comprehensive authentication documentation
+type: invocable
+version: "1.0.0"
+parameters: [authMethod]
+---
+
+## Document Authentication
+
+Create comprehensive authentication documentation
+
+### Steps
+
+1. Identify the authentication method(s) supported
+2. Document how to obtain credentials (API keys, OAuth tokens)
+3. Show how to include credentials in requests (headers, query params)
+4. Document token refresh flows if applicable
+5. Add examples for each authentication method
+6. Document scopes and permissions if using OAuth
+7. Add security best practices section
+
+### Inputs Required
+
+- **authMethod** (required): Primary authentication method (API key, OAuth 2.0, Basic)
+
+### Expected Outputs
+
+- Authentication documentation
+
+### When to Use
+
+This workflow is helpful when the user mentions:
+- "authentication"
+- "auth"
+- "security"
+- "login"
+- "oauth"
+- "api key"

package/kits/api-documentation/skills/document-endpoint/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: Document API Endpoint
+description: Create comprehensive documentation for a new API endpoint
+type: invocable
+version: "1.0.0"
+parameters: [resource, action]
+---
+
+## Document API Endpoint
+
+Create comprehensive documentation for a new API endpoint
+
+### Steps
+
+1. Determine the HTTP method and URL path for the endpoint
+2. Define path parameters, query parameters, and request body schema
+3. Specify required and optional headers including authentication
+4. Document the success response format with status code and body schema
+5. Document all possible error responses with codes and messages
+6. Create realistic request and response examples
+7. Add curl or SDK code examples for quick testing
+8. Update the endpoints index with the new endpoint
+
+### Inputs Required
+
+- **resource** (required): The resource type (e.g., users, orders)
+- **action** (required): The action (list, get, create, update, delete, custom)
+
+### Expected Outputs
+
+- Endpoint documentation file
+- Updated endpoints index
+
+### When to Use
+
+This workflow is helpful when the user mentions:
+- "new endpoint"
+- "document endpoint"
+- "add endpoint"
+- "api endpoint"

package/kits/api-documentation/skills/kit-expertise/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: kit-expertise
+description: Domain expertise for API Documentation - applied automatically when working in this kit
+type: background
+version: "1.0.0"
+---
+
+## Your Role
+
+API Documentation Specialist helping you create clear, developer-friendly API documentation
+
+## Your Expertise
+
+- API documentation best practices
+- OpenAPI/Swagger specification
+- Endpoint design and naming
+- Request/response documentation
+- Authentication documentation
+- Error handling documentation
+- Code examples and SDKs
+- Developer experience optimization
+
+## Your Approach
+
+Assist the user with their requests efficiently
+
+## Things to Avoid
+
+- Incomplete endpoint documentation
+- Missing error codes
+- Outdated examples
+- Inconsistent formatting
+
+## Domain Knowledge
+
+### Key Terms
+
+**endpoint**
+URL path for accessing a specific resource
+
+**HTTP method**
+GET, POST, PUT, PATCH, DELETE operations
+
+**request body**
+Data sent to the API
+
+**response body**
+Data returned by the API
+
+**query parameter**
+Optional URL parameter
+
+**path parameter**
+Variable in the URL path
+
+**authentication**
+Method to verify API caller identity
+
+**rate limiting**
+Restrictions on API call frequency
+
+### Best Practices
+
+- Document all endpoints completely
+- Include request and response examples
+- List all possible error codes
+- Show authentication requirements
+- Provide code examples in multiple languages
+- Keep documentation in sync with API
+
+### Common Mistakes to Avoid
+
+- Outdated documentation
+- Missing error scenarios
+- No code examples
+- Inconsistent naming
+- Undocumented parameters
+- No versioning information

package/kits/api-documentation/skills/openapi-spec/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: openapi-spec
+description: Write clear, complete OpenAPI/Swagger specifications for REST APIs
+type: invocable
+version: "1.0.0"
+---
+
+## OpenAPI Specification Skill
+
+When the user invokes `/openapi`, help them write or improve OpenAPI (Swagger) specifications for their APIs.
+
+### Invocation Patterns
+
+- `/openapi` - Generate spec from existing code/docs
+- `/openapi validate` - Validate and improve existing spec
+- `/openapi endpoint [method] [path]` - Document specific endpoint
+
+### OpenAPI 3.0+ Structure
+
+```yaml
+openapi: 3.0.3
+info:
+  title: API Title
+  description: API description
+  version: 1.0.0
+servers:
+  - url: https://api.example.com/v1
+paths:
+  /resource:
+    get:
+      # endpoint definition
+components:
+  schemas:
+    # reusable schemas
+  securitySchemes:
+    # authentication methods
+```
+
+### Path Documentation
+
+```yaml
+/users/{userId}:
+  get:
+    summary: Get user by ID
+    description: |
+      Retrieves a single user by their unique identifier.
+      Returns 404 if user doesn't exist.
+    operationId: getUserById
+    tags:
+      - Users
+    parameters:
+      - name: userId
+        in: path
+        required: true
+        description: Unique user identifier
+        schema:
+          type: string
+          format: uuid
+    responses:
+      '200':
+        description: Successful response
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/User'
+      '404':
+        description: User not found
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Error'
+```
+
+### Schema Best Practices
+
+**Use Descriptive Schemas**
+```yaml
+components:
+  schemas:
+    User:
+      type: object
+      required:
+        - id
+        - email
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique identifier
+          example: "123e4567-e89b-12d3-a456-426614174000"
+        email:
+          type: string
+          format: email
+          description: User's email address
+          example: "user@example.com"
+        createdAt:
+          type: string
+          format: date-time
+          description: Account creation timestamp
+```
+
+**Common Formats**
+- `format: uuid` - UUIDs
+- `format: email` - Email addresses
+- `format: date-time` - ISO 8601 timestamps
+- `format: uri` - URLs
+- `format: int32/int64` - Integer sizes
+
+### Output Format
+
+```markdown
+## OpenAPI Specification
+
+### Endpoint: [Method] [Path]
+
+```yaml
+[Complete OpenAPI YAML for endpoint]
+```
+
+### Schema Definitions
+
+```yaml
+[Related component schemas]
+```
+
+### Documentation Checklist
+- [ ] Summary is concise (< 120 chars)
+- [ ] Description explains behavior
+- [ ] All parameters documented
+- [ ] All responses defined
+- [ ] Examples provided
+- [ ] Error responses included
+- [ ] Authentication specified
+```
+
+### Security Schemes
+
+```yaml
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+    apiKey:
+      type: apiKey
+      in: header
+      name: X-API-Key
+```
+
+### Response Patterns
+
+**Success Responses**
+- 200: OK (GET, PUT, PATCH)
+- 201: Created (POST)
+- 204: No Content (DELETE)
+
+**Error Responses**
+- 400: Bad Request (validation errors)
+- 401: Unauthorized (missing auth)
+- 403: Forbidden (insufficient permissions)
+- 404: Not Found
+- 422: Unprocessable Entity (business logic error)
+- 500: Internal Server Error
+
+### Quality Checklist
+
+- Every endpoint has summary + description
+- All parameters have descriptions
+- All schemas have examples
+- Error responses are documented
+- Authentication requirements specified
+- Consistent naming conventions
+- No broken $refs