Unify OpenCode and Codex starter kits
- Add .shared/prompts/ with tool-neutral prompts - Add .opencode/config/project.md, rules/, skills/ from opencode-kit - Add .codex/config/project.md from codex-kit - Copy .shared/prompts/ to both .opencode/prompts/ and .codex/prompts/ - Add features/INDEX.md and features/README.md - Update README with unified structure The two original starter kits are now redundant.
This commit is contained in:
109
.opencode/skills/docs/SKILL.md
Normal file
109
.opencode/skills/docs/SKILL.md
Normal file
@@ -0,0 +1,109 @@
|
||||
---
|
||||
name: docs
|
||||
description: Documents API endpoints, generates wiki structure, and tracks documentation coverage
|
||||
category: development
|
||||
---
|
||||
|
||||
# Documentation Engineer
|
||||
|
||||
Documents API endpoints, maintains wiki structure, and reports documentation gaps.
|
||||
|
||||
## When to Use
|
||||
|
||||
```
|
||||
/docs
|
||||
/docs api
|
||||
/docs wiki
|
||||
/docs check
|
||||
```
|
||||
|
||||
## Sub-Commands
|
||||
|
||||
### `/docs api`
|
||||
Scans `src/` for API endpoints and updates `docs/api/`.
|
||||
|
||||
### `/docs wiki`
|
||||
Suggests or updates wiki structure in `docs/wiki/`.
|
||||
|
||||
### `/docs check`
|
||||
Reports which endpoints/classes lack documentation.
|
||||
|
||||
## Skill Steps
|
||||
|
||||
### 1. Scan for API Endpoints
|
||||
- Search `src/` for route files (REST patterns: `*Route.php`, `*Controller.php`)
|
||||
- Search for HTTP method annotations: `@Route`, `@Get`, `@Post`, `@Put`, `@Delete`
|
||||
- Detect endpoint patterns in plain PHP files
|
||||
|
||||
### 2. Update API Documentation
|
||||
- Create/update `docs/api/ENDPOINTS.md` with endpoint inventory
|
||||
- Create individual files per resource: `docs/api/users.md`, `docs/api/tasks.md`
|
||||
- Format:
|
||||
|
||||
```markdown
|
||||
# Users API
|
||||
|
||||
## Endpoints
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | /api/users | List all users |
|
||||
| GET | /api/users/{id} | Get single user |
|
||||
| POST | /api/users | Create user |
|
||||
| PUT | /api/users/{id} | Update user |
|
||||
| DELETE | /api/users/{id} | Delete user |
|
||||
|
||||
## Request/Response Examples
|
||||
|
||||
### GET /api/users
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"data": [...],
|
||||
"total": 42,
|
||||
"page": 1,
|
||||
"per_page": 20
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
### 3. Wiki Structure
|
||||
If `docs/wiki/` doesn't exist, suggest structure:
|
||||
|
||||
```
|
||||
docs/wiki/
|
||||
├── README.md <- Wiki home
|
||||
├── getting-started.md <- Setup guide
|
||||
├── api-reference.md <- API overview
|
||||
├── database.md <- DB schema
|
||||
└── deployment.md <- Hosting guide
|
||||
```
|
||||
|
||||
### 4. Documentation Coverage Report
|
||||
Track which classes/features have docs:
|
||||
|
||||
| Class/File | Has Docs | Last Updated |
|
||||
|------------|----------|--------------|
|
||||
| UserController | ✅ docs/api/users.md | 2026-01-15 |
|
||||
| TaskController | ❌ missing | - |
|
||||
|
||||
## Output
|
||||
|
||||
- `docs/api/*.md` - API endpoint documentation
|
||||
- `docs/wiki/README.md` - Wiki home (if created)
|
||||
- Coverage report printed to user
|
||||
|
||||
## Rules
|
||||
|
||||
- Use English for all documentation content
|
||||
- One endpoint file per resource
|
||||
- Include request/response examples
|
||||
- Document error responses (400, 401, 403, 404, 500)
|
||||
- Keep docs in sync with code (check on every run)
|
||||
|
||||
## Context Recovery
|
||||
|
||||
If context is compacted:
|
||||
1. Re-scan `src/` for endpoint files
|
||||
2. Check which docs already exist
|
||||
3. Continue from missing documentation
|
||||
Reference in New Issue
Block a user