developer-ai 1.0.0

package/skills/api-design/SKILL.md

@@ -0,0 +1,419 @@
+---
+name: api-design
+description: Guide for designing RESTful and GraphQL APIs. Use when creating new APIs, refactoring existing endpoints, or establishing API conventions. Covers REST principles, versioning, error handling, authentication, and documentation.
+---
+
+# API Design Skill
+
+This skill provides comprehensive guidance for designing clean, consistent, and developer-friendly APIs.
+
+## Overview
+
+Good API design creates intuitive interfaces that are easy to use, maintain, and evolve. This skill covers REST API design principles and best practices.
+
+## REST API Principles
+
+### Resource Naming
+
+**Use Nouns, Not Verbs**
+```
+# GOOD
+GET    /users
+GET    /users/123
+POST   /users
+PUT    /users/123
+DELETE /users/123
+
+# BAD
+GET    /getUsers
+POST   /createUser
+PUT    /updateUser
+DELETE /deleteUser
+```
+
+**Use Plural Names**
+```
+# GOOD
+/users
+/products
+/orders
+
+# BAD (inconsistent)
+/user
+/product
+/order
+```
+
+**Use Kebab-Case**
+```
+# GOOD
+/user-profiles
+/order-items
+
+# BAD
+/userProfiles
+/user_profiles
+```
+
+### HTTP Methods
+
+| Method | Use Case | Idempotent |
+|--------|----------|------------|
+| GET | Retrieve resources | Yes |
+| POST | Create new resources | No |
+| PUT | Replace entire resource | Yes |
+| PATCH | Partial update | Yes |
+| DELETE | Remove resource | Yes |
+
+### Resource Relationships
+
+**Nested Resources**
+```
+# User's orders
+GET /users/123/orders
+
+# Order's items
+GET /orders/456/items
+```
+
+**Keep Nesting Shallow**
+```
+# GOOD (max 2 levels)
+GET /users/123/orders
+
+# BAD (too deep)
+GET /users/123/orders/456/items/789/variants
+```
+
+## Request & Response Design
+
+### Request Body
+
+**POST/PUT Request**
+```json
+{
+  "name": "John Doe",
+  "email": "john@example.com",
+  "role": "admin"
+}
+```
+
+**PATCH Request (Partial Update)**
+```json
+{
+  "name": "Jane Doe"
+}
+```
+
+### Response Format
+
+**Single Resource**
+```json
+{
+  "id": "123",
+  "name": "John Doe",
+  "email": "john@example.com",
+  "createdAt": "2024-01-15T10:30:00Z",
+  "updatedAt": "2024-01-20T14:45:00Z"
+}
+```
+
+**Collection with Pagination**
+```json
+{
+  "data": [
+    { "id": "1", "name": "Item 1" },
+    { "id": "2", "name": "Item 2" }
+  ],
+  "pagination": {
+    "page": 1,
+    "perPage": 20,
+    "total": 150,
+    "totalPages": 8
+  },
+  "links": {
+    "self": "/items?page=1",
+    "next": "/items?page=2",
+    "last": "/items?page=8"
+  }
+}
+```
+
+## Status Codes
+
+### Success Codes
+- **200 OK** - Successful GET, PUT, PATCH
+- **201 Created** - Successful POST with new resource
+- **204 No Content** - Successful DELETE
+
+### Client Error Codes
+- **400 Bad Request** - Invalid request body
+- **401 Unauthorized** - Missing/invalid authentication
+- **403 Forbidden** - Authenticated but not authorized
+- **404 Not Found** - Resource doesn't exist
+- **409 Conflict** - Resource conflict (duplicate)
+- **422 Unprocessable Entity** - Validation errors
+
+### Server Error Codes
+- **500 Internal Server Error** - Server-side error
+- **503 Service Unavailable** - Temporary outage
+
+## Error Handling
+
+### Error Response Format
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Validation failed",
+    "details": [
+      {
+        "field": "email",
+        "message": "Invalid email format"
+      },
+      {
+        "field": "name",
+        "message": "Name is required"
+      }
+    ]
+  },
+  "requestId": "req_abc123"
+}
+```
+
+### Error Code Convention
+```javascript
+// Define consistent error codes
+const ErrorCodes = {
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  NOT_FOUND: 'NOT_FOUND',
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  FORBIDDEN: 'FORBIDDEN',
+  CONFLICT: 'CONFLICT',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+};
+```
+
+## Authentication
+
+### JWT Authentication
+```
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+```
+
+### API Key Authentication
+```
+X-API-Key: your-api-key
+```
+or
+```
+Authorization: ApiKey your-api-key
+```
+
+## Versioning
+
+### URL Versioning (Recommended)
+```
+/api/v1/users
+/api/v2/users
+```
+
+### Header Versioning
+```
+Accept: application/vnd.api+json;version=1
+```
+
+## Filtering, Sorting & Pagination
+
+### Filtering
+```
+GET /users?status=active&role=admin
+GET /products?price[gte]=100&price[lte]=500
+GET /orders?createdAt[after]=2024-01-01
+```
+
+### Sorting
+```
+GET /users?sort=name         # Ascending
+GET /users?sort=-createdAt   # Descending
+GET /users?sort=role,-name   # Multiple fields
+```
+
+### Pagination
+
+**Offset-based**
+```
+GET /users?page=2&perPage=20
+```
+
+**Cursor-based (for large datasets)**
+```
+GET /users?cursor=abc123&limit=20
+```
+
+## Rate Limiting
+
+### Response Headers
+```
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 998
+X-RateLimit-Reset: 1640000000
+```
+
+### Rate Limit Error
+```json
+{
+  "error": {
+    "code": "RATE_LIMIT_EXCEEDED",
+    "message": "Too many requests",
+    "retryAfter": 60
+  }
+}
+```
+
+## API Documentation
+
+### OpenAPI Specification
+```yaml
+openapi: 3.0.0
+info:
+  title: User API
+  version: 1.0.0
+
+paths:
+  /users:
+    get:
+      summary: List all users
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserList'
+
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        email:
+          type: string
+          format: email
+```
+
+## Implementation Example
+
+### Express.js API
+```javascript
+const express = require('express');
+const app = express();
+
+// GET /users
+app.get('/api/v1/users', async (req, res) => {
+  try {
+    const { page = 1, perPage = 20, sort, status } = req.query;
+    
+    const users = await User.findMany({
+      where: status ? { status } : undefined,
+      skip: (page - 1) * perPage,
+      take: perPage,
+      orderBy: parseSort(sort),
+    });
+    
+    const total = await User.count();
+    
+    res.json({
+      data: users,
+      pagination: {
+        page: Number(page),
+        perPage: Number(perPage),
+        total,
+        totalPages: Math.ceil(total / perPage),
+      },
+    });
+  } catch (error) {
+    res.status(500).json({
+      error: {
+        code: 'INTERNAL_ERROR',
+        message: 'An error occurred',
+      },
+    });
+  }
+});
+
+// POST /users
+app.post('/api/v1/users', async (req, res) => {
+  try {
+    const { name, email } = req.body;
+    
+    // Validation
+    const errors = validateUser({ name, email });
+    if (errors.length) {
+      return res.status(422).json({
+        error: {
+          code: 'VALIDATION_ERROR',
+          message: 'Validation failed',
+          details: errors,
+        },
+      });
+    }
+    
+    const user = await User.create({ name, email });
+    
+    res.status(201).json(user);
+  } catch (error) {
+    if (error.code === 'P2002') {
+      return res.status(409).json({
+        error: {
+          code: 'CONFLICT',
+          message: 'User with this email already exists',
+        },
+      });
+    }
+    throw error;
+  }
+});
+```
+
+## API Design Checklist
+
+### Naming & Structure
+- [ ] Resources use plural nouns
+- [ ] URLs use kebab-case
+- [ ] Relationships modeled with nested routes
+- [ ] Nesting kept shallow (max 2 levels)
+
+### Requests & Responses
+- [ ] Consistent response format
+- [ ] Appropriate HTTP methods used
+- [ ] Status codes follow standards
+- [ ] Error responses include code and details
+
+### Features
+- [ ] Filtering support
+- [ ] Sorting support
+- [ ] Pagination implemented
+- [ ] Rate limiting configured
+
+### Security
+- [ ] Authentication required where needed
+- [ ] Authorization checks in place
+- [ ] Input validation on all endpoints
+- [ ] Sensitive data not exposed
+
+### Documentation
+- [ ] OpenAPI spec maintained
+- [ ] Examples provided
+- [ ] Error codes documented
+- [ ] Authentication documented

package/skills/code-review/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: code-review
+description: Guide for conducting thorough code reviews. Use when reviewing pull requests, providing feedback on code quality, checking for security issues, performance problems, or maintainability concerns. Includes checklists and best practices for effective code review.
+---
+
+# Code Review Skill
+
+This skill provides comprehensive guidance for conducting effective code reviews that improve code quality and team collaboration.
+
+## Overview
+
+Code reviews serve multiple purposes: catching bugs, ensuring code quality, sharing knowledge, and maintaining consistency. This skill helps you conduct thorough, constructive reviews.
+
+## Code Review Checklist
+
+### Functionality
+- [ ] Code does what it's supposed to do
+- [ ] Edge cases are handled
+- [ ] Error handling is appropriate
+- [ ] No obvious bugs or logic errors
+- [ ] Feature requirements are met
+
+### Code Quality
+- [ ] Code is readable and understandable
+- [ ] Functions are focused and single-purpose
+- [ ] No unnecessary complexity
+- [ ] DRY principle followed (no excessive duplication)
+- [ ] Naming is clear and consistent
+
+### Security
+- [ ] No hardcoded secrets or credentials
+- [ ] Input validation is present
+- [ ] SQL injection prevention (parameterized queries)
+- [ ] XSS prevention (proper escaping)
+- [ ] Authentication/authorization checks in place
+- [ ] Sensitive data handled properly
+
+### Performance
+- [ ] No obvious performance issues
+- [ ] Database queries are optimized
+- [ ] No N+1 query problems
+- [ ] Appropriate caching considerations
+- [ ] Memory leaks addressed
+
+### Testing
+- [ ] Adequate test coverage
+- [ ] Tests are meaningful (not just for coverage)
+- [ ] Edge cases tested
+- [ ] Tests are maintainable
+
+### Documentation
+- [ ] Complex logic is commented
+- [ ] Public APIs are documented
+- [ ] README updated if needed
+- [ ] Breaking changes documented
+
+## Feedback Guidelines
+
+### Be Constructive
+**Good:**
+```
+Consider using `Array.map()` here instead of a for loop - 
+it's more idiomatic and makes the transformation clearer.
+```
+
+**Avoid:**
+```
+This loop is wrong. Use map.
+```
+
+### Be Specific
+**Good:**
+```
+This function is doing too much - it's handling both 
+validation and database operations. Consider splitting into 
+`validateUser()` and `saveUser()` for better testability.
+```
+
+**Avoid:**
+```
+Break this up.
+```
+
+### Ask Questions When Unsure
+**Good:**
+```
+I'm not sure I understand the reason for this approach.
+Could you explain why we're caching this result here?
+```
+
+### Acknowledge Good Work
+```
+Nice use of the builder pattern here! 
+Makes the complex object creation much more readable.
+```
+
+## Common Issues to Look For
+
+### Security Issues
+
+**Hardcoded Secrets**
+```javascript
+// BAD
+const apiKey = "sk-1234567890abcdef";
+
+// GOOD
+const apiKey = process.env.API_KEY;
+```
+
+**SQL Injection**
+```javascript
+// BAD
+const query = `SELECT * FROM users WHERE id = ${userId}`;
+
+// GOOD
+const query = 'SELECT * FROM users WHERE id = $1';
+await db.query(query, [userId]);
+```
+
+**XSS Vulnerabilities**
+```javascript
+// BAD
+element.innerHTML = userInput;
+
+// GOOD
+element.textContent = userInput;
+// or use proper sanitization
+```
+
+### Performance Issues
+
+**N+1 Queries**
+```javascript
+// BAD
+const users = await User.findAll();
+for (const user of users) {
+  user.posts = await Post.findAll({ where: { userId: user.id } });
+}
+
+// GOOD
+const users = await User.findAll({
+  include: [{ model: Post }]
+});
+```
+
+**Unnecessary Re-renders (React)**
+```javascript
+// BAD - creates new object every render
+<Component style={{ color: 'red' }} />
+
+// GOOD
+const styles = { color: 'red' };
+<Component style={styles} />
+```
+
+### Code Smells
+
+**Long Functions**
+- Over 50 lines usually means it should be split
+- Hard to test, hard to understand
+
+**Deep Nesting**
+```javascript
+// BAD
+if (condition1) {
+  if (condition2) {
+    if (condition3) {
+      // do something
+    }
+  }
+}
+
+// GOOD - early returns
+if (!condition1) return;
+if (!condition2) return;
+if (!condition3) return;
+// do something
+```
+
+**Magic Numbers**
+```javascript
+// BAD
+if (user.age >= 18) { }
+setTimeout(fn, 86400000);
+
+// GOOD
+const LEGAL_AGE = 18;
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+if (user.age >= LEGAL_AGE) { }
+setTimeout(fn, ONE_DAY_MS);
+```
+
+## Review Process
+
+### Before Reviewing
+1. Understand the context (read the PR description)
+2. Understand what problem is being solved
+3. Check related issues/tickets
+
+### During Review
+1. Start with high-level structure
+2. Look for architectural issues first
+3. Then dive into implementation details
+4. Run the code locally if needed
+5. Check test coverage
+
+### After Review
+1. Summarize your feedback
+2. Indicate approval/changes needed clearly
+3. Be available for discussion
+
+## Handling Disagreements
+
+### When You Disagree
+1. Focus on technical merits, not preferences
+2. Provide evidence or examples
+3. Be open to being wrong
+4. Escalate to team if needed
+
+### When to Block vs Suggest
+**Block for:**
+- Security vulnerabilities
+- Data loss risks
+- Breaking changes without migration
+- Critical bugs
+
+**Suggest for:**
+- Style preferences
+- Minor optimizations
+- Alternative approaches
+
+## Review Response Templates
+
+### Approval
+```
+LGTM! Clean implementation. One minor suggestion 
+that can be addressed in a follow-up PR: [suggestion]
+```
+
+### Request Changes
+```
+Good progress! A few things need addressing before merge:
+
+1. [Critical] Security: Need to sanitize user input on line 45
+2. [Important] The database query could cause N+1 issues
+3. [Minor] Consider renaming `data` to `userData` for clarity
+```
+
+### Questions
+```
+Looks good overall. A few questions:
+
+1. Why did we choose [approach A] over [approach B]?
+2. How does this interact with [other feature]?
+3. Are there any edge cases we should consider for [scenario]?
+```
+
+## Self-Review Checklist
+
+Before submitting your own PR:
+- [ ] Code compiles and runs
+- [ ] All tests pass
+- [ ] Linter shows no errors
+- [ ] PR description is clear
+- [ ] Changes are focused and atomic
+- [ ] No debugging code left in
+- [ ] Sensitive data not exposed