feat: improved the Claude Kit as a plugin

skills/documentation/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: documentation
+argument-hint: "[file or api/readme]"
+description: >
+  Use when generating or updating documentation — including code comments, docstrings, JSDoc, API docs, README files, or technical specifications. Trigger for keywords like "document", "docstring", "JSDoc", "README", "API docs", "explain this code", "add comments", or any request to improve code documentation. Also activate when generating project documentation or updating existing docs after code changes.
+---
+
+# Documentation
+
+## When to Use
+
+- Adding docstrings or JSDoc to functions/classes
+- Generating or updating README files
+- Documenting API endpoints
+- Writing technical specifications
+- Adding inline comments to complex logic
+
+## When NOT to Use
+
+- Generating changelogs from commits — use `git-workflows`
+- Writing OpenAPI specs — use `openapi`
+- Architecture design documentation — use `brainstorming` + `writing-plans`
+
+---
+
+## Quick Reference
+
+| Topic | Reference | Key content |
+|-------|-----------|-------------|
+| Code documentation | `references/code-docs.md` | Python docstrings, TypeScript JSDoc, inline comments |
+| API documentation | `references/api-docs.md` | Endpoint docs, request/response examples |
+| Project documentation | `references/project-docs.md` | README, CONTRIBUTING, architecture docs |
+
+---
+
+## Documentation Workflow
+
+### For Code
+
+1. Read the code thoroughly — understand purpose and behavior
+2. Identify inputs, outputs, side effects, and edge cases
+3. Add docstrings/JSDoc with examples
+4. Add type annotations if missing
+
+### For APIs
+
+1. Scan route definitions and identify endpoints
+2. Document request format, response format, error responses
+3. Add authentication requirements
+4. Include working examples
+
+### For Projects
+
+1. Analyze project purpose, features, and setup
+2. Write clear installation and usage instructions
+3. Include working code examples
+4. Keep configuration tables up to date
+
+---
+
+## Best Practices
+
+1. **Document the why, not the what** — code shows what; comments explain why.
+2. **Include examples** — one working example beats three paragraphs of description.
+3. **Document edge cases** — what happens with null, empty, or invalid input?
+4. **Keep docs adjacent to code** — docstrings over separate doc files.
+5. **Update docs with code** — stale docs are worse than no docs.
+
+## Common Pitfalls
+
+1. **Restating the code** — `# increment i by 1` adds no value.
+2. **Missing error documentation** — not documenting what exceptions a function raises.
+3. **Outdated examples** — code examples that no longer compile.
+4. **Over-documenting internal code** — public APIs need docs; private helpers often don't.
+
+---
+
+## Related Skills
+
+- `openapi` — OpenAPI spec generation for REST APIs
+- `git-workflows` — Changelog generation from commits
+- `backend-frameworks` — Framework-specific documentation patterns

skills/documentation/references/api-docs.md

@@ -0,0 +1,44 @@
+# API Documentation Patterns
+
+## Endpoint Documentation Template
+
+```markdown
+## POST /api/orders
+
+Create a new order.
+
+### Authentication
+Requires Bearer token.
+
+### Request Body
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| items | array | yes | Order items |
+| shippingAddress | object | yes | Delivery address |
+
+### Response (201 Created)
+```json
+{
+  "id": "order_456",
+  "status": "pending",
+  "total": 99.99,
+  "createdAt": "2024-01-15T10:00:00Z"
+}
+```
+
+### Errors
+| Status | Code | Description |
+|--------|------|-------------|
+| 400 | INVALID_ITEMS | Items array is empty |
+| 401 | UNAUTHORIZED | Invalid or missing token |
+| 422 | OUT_OF_STOCK | Item not available |
+```
+
+## Discovery Process
+
+1. Scan route definitions (`@app.get`, `router.post`, `@Controller`)
+2. Identify HTTP methods and paths
+3. Note authentication requirements
+4. Document request/response schemas
+5. List all error responses with codes
+6. Add working curl/httpx examples

skills/documentation/references/code-docs.md

@@ -0,0 +1,52 @@
+# Code Documentation Patterns
+
+## Python Docstrings (Google Style)
+
+```python
+def calculate_discount(price: float, percentage: float) -> float:
+    """Calculate discounted price.
+
+    Args:
+        price: Original price in dollars.
+        percentage: Discount percentage (0-100).
+
+    Returns:
+        The discounted price.
+
+    Raises:
+        ValueError: If percentage is not between 0 and 100.
+
+    Example:
+        >>> calculate_discount(100.0, 20)
+        80.0
+    """
+```
+
+## TypeScript JSDoc
+
+```typescript
+/**
+ * Calculate discounted price.
+ *
+ * @param price - Original price in dollars
+ * @param percentage - Discount percentage (0-100)
+ * @returns The discounted price
+ * @throws {RangeError} If percentage is not between 0 and 100
+ *
+ * @example
+ * calculateDiscount(100, 20); // returns 80
+ */
+```
+
+## When to Add Inline Comments
+
+- Explain **why**, not what — `# Retry 3x because upstream API is flaky`
+- Document workarounds — `// Safari doesn't support this API, fallback to...`
+- Clarify non-obvious logic — `# O(1) amortized via lazy deletion`
+- Mark TODOs with context — `# TODO(#123): remove after migration complete`
+
+## When NOT to Comment
+
+- Restating the code: `i += 1  # increment i by 1`
+- Obvious function names: `def get_user_by_id` needs no docstring explaining it gets a user by ID
+- Commented-out code — delete it, git has history

skills/documentation/references/project-docs.md

@@ -0,0 +1,43 @@
+# Project Documentation Patterns
+
+## README Structure
+
+```markdown
+## Installation
+
+```bash
+npm install my-package
+```
+
+## Quick Start
+
+```typescript
+import { Client } from 'my-package';
+const client = new Client({ apiKey: 'your-key' });
+const result = await client.fetch();
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | string | required | Your API key |
+| `timeout` | number | 5000 | Request timeout in ms |
+```
+
+## Key Sections
+
+1. **Title + one-liner** — what this project does
+2. **Installation** — copy-pasteable setup commands
+3. **Quick Start** — working example in < 10 lines
+4. **Configuration** — table of options with types and defaults
+5. **API Reference** — link to detailed docs
+6. **Contributing** — how to contribute
+7. **License** — MIT, Apache, etc.
+
+## Documentation Coverage Report
+
+After documenting, summarize:
+- Functions documented: X/Y (Z%)
+- Endpoints documented: X/Y (Z%)
+- Missing: [list of undocumented items]