skeleton/.opencode/skills/docs/SKILL.md

name, description, category

name	description	category
docs	Documents API endpoints, generates wiki structure, and tracks documentation coverage	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:

# 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