diff --git a/common/src/templates/initial-agents-dir/skills/api-design-review/SKILL.md b/common/src/templates/initial-agents-dir/skills/api-design-review/SKILL.md new file mode 100644 index 0000000000..7484051735 --- /dev/null +++ b/common/src/templates/initial-agents-dir/skills/api-design-review/SKILL.md @@ -0,0 +1,121 @@ +--- +name: api-design-review +description: A structured guide for reviewing and designing RESTful and RPC-style APIs, covering endpoints, schemas, error handling, and best practices +license: MIT +metadata: + category: development + audience: developers +--- + +# API Design Review + +A structured guide for reviewing API designs, endpoints, and schemas. + +## When to use + +Use this skill when asked to review API endpoints, design new APIs, or evaluate API schemas and contracts. + +## Review Checklist + +### 1. Naming & Consistency + +- Are endpoint paths **plural nouns** (`/users`, `/orders`) not verbs (`/getUsers`, `/createOrder`)? +- Are URL segments **kebab-case** or **snake_case** consistently? +- Are query parameters consistently named (camelCase or snake_case)? +- Do related resources follow a consistent pattern (`/users/:id/orders` not `/orders?userId=:id`)? +- Is the API versioned (`/v1/`) in the URL path or header? + +### 2. RESTful Design + +- Are HTTP methods used correctly? (GET = read, POST = create, PUT = replace, PATCH = update, DELETE = remove) +- Are status codes meaningful? (200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable, 500 Server Error) +- Are responses consistent in structure across all endpoints? +- Are list endpoints paginated with consistent params (`page`, `limit`, `cursor`)? +- Are nested resources kept shallow (max 2-3 levels deep)? + +### 3. Request/Response Schemas + +- Are request bodies validated with consistent error messages? +- Are response fields using **camelCase** for JSON APIs? +- Are date/time fields using **ISO 8601** format? +- Are IDs opaque strings (UUIDs) rather than sequential integers? +- Are sensitive fields (passwords, tokens) excluded from responses? +- Is there a consistent envelope for paginated responses (`{ data, meta: { total, page, limit } }`)? + +### 4. Error Handling + +- Is there a consistent error response format (`{ error: { code, message, details } }`)? +- Are error messages human-readable and actionable? +- Are internal error details (stack traces, SQL queries) hidden from responses? +- Are rate limiting headers present (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`)? + +### 5. Security + +- Is authentication required for all endpoints unless explicitly public? +- Are authorization checks performed per resource, not just at the endpoint level? +- Are input sanitization and validation applied? +- Is HTTPS enforced? +- Are CORS headers properly configured? + +### 6. API Documentation + +- Is there an OpenAPI/Swagger specification? +- Are there clear examples for each endpoint? +- Are error scenarios documented? +- Are deprecation policies documented? + +## Quick Reference + +```typescript +// Good RESTful endpoint design +GET /v1/users // List users (paginated) +POST /v1/users // Create user +GET /v1/users/:id // Get user by ID +PATCH /v1/users/:id // Update user +DELETE /v1/users/:id // Delete user +GET /v1/users/:id/orders // List user's orders (nested resource) + +// Consistent error format +{ + "error": { + "code": "VALIDATION_ERROR", + "message": "Email is required", + "details": { + "field": "email", + "constraint": "required" + } + } +} + +// Consistent paginated response +{ + "data": [...], + "meta": { + "total": 100, + "page": 1, + "limit": 20, + "hasMore": true + } +} +``` + +## Output Format + +Summarize findings as: + +- 🔴 **Breaking**: Incompatible change or security issue +- 🟡 **Warning**: Should address before shipping +- 🟢 **Suggestion**: Best practice improvement +- ✅ **Praise**: Something done well + +## Quick Reference Commands + +- `read_files` — Read the API spec or endpoint files +- `code_search` — Find related endpoints or usage patterns +- `web_search` — Research API design standards or conventions + +## Notes + +- Design for your consumers, not your data model +- Consistency beats cleverness every time +- A good API is boring — predictable, simple, and hard to misuse diff --git a/common/src/templates/initial-agents-dir/skills/code-review-checklist/SKILL.md b/common/src/templates/initial-agents-dir/skills/code-review-checklist/SKILL.md new file mode 100644 index 0000000000..c591a969fb --- /dev/null +++ b/common/src/templates/initial-agents-dir/skills/code-review-checklist/SKILL.md @@ -0,0 +1,98 @@ +--- +name: code-review-checklist +description: A comprehensive code review checklist that guides agents through reviewing code changes for correctness, maintainability, performance, and security +license: MIT +metadata: + category: development + audience: developers +--- + +# Code Review Checklist + +A structured code review checklist for reviewing code changes systematically. + +## When to use + +Use this skill when asked to review code changes, perform a code review, or check for common issues in pull requests. + +## Review Dimensions + +### 1. Correctness + +- Do the changes actually solve the described problem? +- Are edge cases handled (empty states, null values, error conditions)? +- Are there any race conditions or timing issues? +- Do the changes break existing functionality? + +### 2. Maintainability + +- Is the code readable and self-documenting? +- Are functions and variables named clearly? +- Is there unnecessary complexity that could be simplified? +- Are there good comments explaining "why" (not "what")? +- Would a new team member understand this code? + +### 3. Performance + +- Are there any obvious performance bottlenecks? +- Are there unnecessary re-renders, recomputations, or network calls? +- Are large data structures handled efficiently? +- Is there proper memoization where appropriate? + +### 4. Security + +- Are user inputs properly validated and sanitized? +- Are there any injection vulnerabilities (SQL, XSS, command injection)? +- Are authentication/authorization checks in place? +- Are secrets/hardcoded credentials exposed? +- Are proper security headers or CSP policies applied? + +### 5. Testing + +- Are there tests for the new code? +- Do existing tests still pass? +- Are edge cases covered by tests? +- Are test names descriptive? +- Are there integration or e2e tests for critical paths? + +### 6. Architecture + +- Does the change follow the project's established patterns? +- Are new dependencies justified? +- Is the code placed in the right module/layer? +- Does it introduce unnecessary coupling or circular dependencies? + +## Output Format + +Summarize findings as: + +- 🔴 **Critical**: Must fix before merging +- 🟡 **Warning**: Should address soon +- 🟢 **Suggestion**: Nice to have improvement +- ✅ **Praise**: Something done well + +## Manual Testing Checklist (UI Changes) + +If review involves UI changes, also check: + +- Responsive/mobile layout +- Loading states and skeletons +- Error states and error messages +- Empty states +- Keyboard navigation and accessibility +- Dark/light theme compatibility (if applicable) +- Console errors or warnings + +## Quick Reference Commands + +When reviewing code, you can use these tools: + +- `read_files` — Read the changed files in full +- `code_search` — Search for related patterns or usages +- `run_terminal_command` — Run tests or linters + +## Notes + +- Be constructive, not critical. Suggest solutions, not just problems. +- Prioritize findings: security > correctness > performance > maintainability > style +- If unsure about a finding, mark it as a question rather than assuming the worst diff --git a/common/src/templates/initial-agents-dir/skills/testing-strategies/SKILL.md b/common/src/templates/initial-agents-dir/skills/testing-strategies/SKILL.md new file mode 100644 index 0000000000..1896902c9f --- /dev/null +++ b/common/src/templates/initial-agents-dir/skills/testing-strategies/SKILL.md @@ -0,0 +1,150 @@ +--- +name: testing-strategies +description: A practical guide for writing effective tests across unit, integration, and end-to-end levels, with patterns for TypeScript and React projects +license: MIT +metadata: + category: development + audience: developers +--- + +# Testing Strategies + +A practical guide for writing effective tests with the right scope, coverage, and patterns. + +## When to use + +Use this skill when asked to write tests, review test coverage, determine testing strategy, or improve test quality. + +## Testing Pyramid + +### 1. Unit Tests (fast, focused) + +- Test individual functions, classes, or modules in isolation +- Mock external dependencies (APIs, databases, file system) +- Cover: core logic, edge cases, error paths, boundary conditions +- Goal: ~70% of your test suite + +### 2. Integration Tests (medium, connective) + +- Test how modules work together (API + database, service + repository) +- Use real dependencies when practical, test doubles for external services +- Cover: data flow, contract between layers, error propagation +- Goal: ~20% of your test suite + +### 3. End-to-End Tests (slow, realistic) + +- Test complete user flows through the system +- Use real infrastructure (test databases, staging APIs) +- Cover: critical user journeys, deployment verification +- Goal: ~10% of your test suite + +## Test Patterns + +### Arrange-Act-Assert + +Structure every test with clear phases: + +```typescript +// Arrange +const { result } = renderHook(() => useCounter()) + +// Act +act(() => result.current.increment()) + +// Assert +expect(result.current.count).toBe(1) +``` + +### Describe-It (Behavior-Driven) + +Name tests as specifications: + +```typescript +describe('UserService', () => { + describe('getUser', () => { + it('returns user when found', async () => { ... }) + it('throws NotFoundError when missing', async () => { ... }) + it('caches result on repeated calls', async () => { ... }) + }) +}) +``` + +### Dependency Injection over Mocking + +Prefer passing dependencies rather than mocking: + +```typescript +// Good: DI makes testing natural +class OrderService { + constructor( + private db: Database, + private email: EmailService, + ) {} +} + +// Test +const service = new OrderService(mockDb, mockEmail) +``` + +### Test the Interface, Not Implementation + +- Test public API behavior, not internal details +- Avoid testing private methods directly +- Refactoring internals shouldn't break tests + +## What to Test + +### Always Test + +- Core business logic and calculations +- Edge cases: empty states, null values, error conditions +- Authentication and authorization +- Data validation and sanitization +- API error handling and status codes + +### Sometimes Test + +- UI component rendering (use snapshot tests sparingly) +- Integration with third-party services (use contract tests) +- Performance-critical paths + +### Don't Test + +- Generated code (scaffolds, ORM models) +- Simple getters/setters +- Language/stdlib features you didn't write +- Configuration constants (test the code that uses them instead) + +## Quick Reference + +> **Note:** The examples below use `describe`/`test`/`expect` which work with Vitest, Jest, and Bun's built-in test runner (`bun:test`). + +```typescript +// Unit test example (Bun/Vitest compatible) +test('validateEmail rejects invalid emails', () => { + expect(validateEmail('not-an-email')).toBe(false) + expect(validateEmail('user@example.com')).toBe(true) + expect(validateEmail('')).toBe(false) + expect(validateEmail(null)).toBe(false) +}) + +// Async test with error +test('getUser throws on not found', async () => { + await expect( + userService.getUser('nonexistent-id'), + ).rejects.toThrow('User not found') +}) +``` + +## Quick Reference Commands + +- `run_terminal_command` — Run tests with `bun test`, `npm test`, or `npx vitest run` +- `read_files` — Read test files and source files +- `code_search` — Find related test patterns or coverage gaps + +## Notes + +- Write tests in the same language as your production code +- Keep tests simple — no conditional logic, loops, or complex abstractions +- A failing test should tell you what's wrong from the error message alone +- Run the specific test file, not the whole suite, during development