# Docs

> Generate or update project documentation from code -- API docs, service docs, architecture docs, or runbooks. Use after adding endpoints, entities, events, or infrastructure changes, or when documentation may be stale.

- **Type:** Skill
- **Install:** `agentstack add skill-makigjuro-cloudstack-ai-plugins-docs`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [makigjuro](https://agentstack.voostack.com/s/makigjuro)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [makigjuro](https://github.com/makigjuro)
- **Source:** https://github.com/makigjuro/cloudstack-ai-plugins/tree/main/plugins/dev-workflow/skills/docs
- **Website:** https://github.com/makigjuro/cloudstack-ai-plugins#quick-start

## Install

```sh
agentstack add skill-makigjuro-cloudstack-ai-plugins-docs
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Generate / Update Documentation

Generate or update markdown documentation by analyzing the actual codebase. Never fabricate -- every statement must be backed by code you've read.

## Arguments

- `{target}` -- What to document. One of:
  - `service {name}` -- Full service documentation (endpoints, events, config)
  - `api {service}` -- API endpoint reference for a service
  - `architecture` -- Update the technical architecture doc
  - `domain` -- Update the domain model doc
  - `runbook {service}` -- Operational runbook (health checks, alerts, troubleshooting)
  - `quickstart` -- Update the quickstart / getting started guide
  - `all` -- Regenerate all outdated docs

If no argument given, detect what's changed since last docs update and suggest what needs refreshing.

## Configuration

Read `cloudstack.json` from the project root at the start of execution. Extract:
- `NAMESPACE` = `project.namespace`
- `SOLUTION` = `backend.solutionPath`
- `SERVICES` = `backend.services[]`
- `FRONTEND_PATH` = `frontend.path` (default: `web`)
- `CHARTS_PATH` = `infrastructure.chartsPath` (default: `deploy/charts`)
- `TERRAFORM_PATH` = `infrastructure.terraformPath`

If `cloudstack.json` does not exist, auto-detect by scanning the project structure.

## Process

### Step 1: Detect Scope

If no target specified:
```bash
# Find docs that may be stale -- compare last doc commit vs last code commit
git log -1 --format=%H -- docs/
git log -1 --format=%H -- src/ ${FRONTEND_PATH} ${CHARTS_PATH} ${TERRAFORM_PATH}

# Show what code changed since docs were last updated
git diff {last-docs-commit}..HEAD --stat -- src/ ${FRONTEND_PATH} ${CHARTS_PATH} ${TERRAFORM_PATH}
```

Present the user with a summary of what's changed and recommend which docs to update.

### Step 2: Gather Evidence

Read the actual code -- do NOT guess or use stale memory. For each doc type:

**Service doc (`docs/services/{service-name}/README.md`):**
1. Read `src/{Service}/{Service}.Host/Program.cs` -- DI, middleware, config sections
2. Read `src/{Service}/{Service}.Host/Endpoints/` -- all endpoint files
3. Read `src/{Service}/{Service}.Application/Commands/` -- all command records
4. Read `src/{Service}/{Service}.Application/Queries/` -- all query records
5. Read `src/{Service}/{Service}.Infrastructure/DependencyInjection.cs` -- external dependencies
6. Read `src/{Service}/{Service}.Infrastructure/Persistence/Configurations/` -- DB schema
7. Grep for messaging subjects/topics in the service
8. Read Helm chart values if present: `${CHARTS_PATH}/{service-name}/values.yaml`
9. Read `appsettings.json` in the Host project -- configuration keys

**API doc (`docs/services/{service-name}/api.md`):**
1. Read all endpoint files in `src/{Service}/{Service}.Host/Endpoints/`
2. Read corresponding command/query records for request/response shapes
3. Read validators for constraints
4. Extract: method, route, request body, response body, status codes, auth requirements

**Architecture doc (`docs/architecture/technical-architecture.md`):**
1. Read all `Program.cs` files for service topology
2. Read app host / orchestrator config for service discovery and dependencies
3. Read `${TERRAFORM_PATH}/` for infrastructure components
4. Read `${CHARTS_PATH}/` for deployment topology
5. Grep for inter-service communication patterns (HTTP clients, messaging subjects)

**Domain model doc (`docs/architecture/domain-model.md`):**
1. Read all entities in the shared domain layer
2. Read all value objects in the shared domain layer
3. Read all domain events in the shared domain layer
4. Read EF Core configurations for relationships and constraints

**Runbook (`docs/services/{service-name}/runbook.md`):**
1. Read `Program.cs` for health check endpoints
2. Read `${CHARTS_PATH}/{service-name}/values.yaml` for resource limits, probes, env vars
3. Read `${CHARTS_PATH}/{service-name}/templates/` for alerts, HPA config
4. Grep for error codes and error handling patterns
5. Read integration test factory for dependencies (DB, messaging, cache, storage)

**Quickstart (`docs/quickstart.md`):**
1. Read app host / orchestrator config for local dev setup
2. Read `docker-compose*.yml` if present
3. Read `${FRONTEND_PATH}/package.json` for frontend setup
4. Read `Directory.Build.props` for SDK requirements
5. Verify all commands by checking they reference real files/scripts

### Step 3: Generate Documentation

Write the documentation to the appropriate path. Follow these rules:

**Structure:**
- Use the existing file if updating -- preserve sections the user may have manually edited
- Add a metadata comment at the top: ``
- Mark auto-generated sections with `` / `` markers
- Leave non-generated sections untouched when updating

**Content rules:**
- Every endpoint, entity, event, and config key must come from actual code you read
- Include code references: `See: src/{Service}/.../FileName.cs`
- Use tables for structured data (endpoints, config keys, events)
- Include Mermaid diagrams for architecture and entity relationships where helpful
- Keep descriptions concise -- one sentence per item unless complexity warrants more

### Step 4: Verify

After generating:
1. Check all file paths referenced in the doc actually exist
2. Check all endpoint routes match what's in the code
3. Check all config keys match what's in appsettings / values.yaml
4. Validate any Mermaid diagrams using `mcp__claude_ai_Mermaid_Chart__validate_and_render_mermaid_diagram` -- fix syntax errors before writing
5. Report what was generated/updated and word count

## Output Formats

### Service Doc Template

```markdown

# {Service Name}

{One-paragraph description of what this service does.}

## API Endpoints

| Method | Route | Description | Auth |
|--------|-------|-------------|------|
| POST | `/api/{resource}` | Create a new resource | API Key |
| GET | `/api/{resource}/{id}` | Get resource by ID | API Key |

## Commands & Queries

### Commands
| Command | Description | Handler |
|---------|-------------|---------|
| `CreateResourceCommand` | Creates a new resource | `CreateResourceHandler` |

### Queries
| Query | Description | Handler |
|-------|-------------|---------|
| `GetResourceByIdQuery` | Retrieves resource by ID | `GetResourceByIdHandler` |

## Domain Events Published

| Event | Trigger | Key Data |
|-------|---------|----------|
| `ResourceCreatedEvent` | Resource.Create() | ResourceId, TenantId |

## Messaging Subjects

| Subject | Type | Direction | Description |
|---------|------|-----------|-------------|
| `{project}.{resource}.events.` | Persistent | Outbound | Resource events |

## Configuration

| Key | Description | Default | Required |
|-----|-------------|---------|----------|
| `ConnectionStrings:{name}` | Database connection | -- | Yes |

## Dependencies

- **PostgreSQL** -- State persistence
- **Messaging** -- Event publishing

```

### API Doc Template

```markdown

# {Service Name} API Reference

Base URL: `/api/{resource}`

## POST /api/{resource}

Create a new resource.

**Request Body:**
\`\`\`json
{
  "name": "string",
  "metadata": "string | null"
}
\`\`\`

**Response (201):**
\`\`\`json
{
  "id": "guid",
  "name": "string",
  "createdAt": "datetime"
}
\`\`\`

**Error Codes:**
| Code | Status | Description |
|------|--------|-------------|
| `RESOURCE_ALREADY_EXISTS` | 409 | Resource with this ID already exists |
| `NAME_REQUIRED` | 400 | Name is missing or empty |

**Validation Rules:**
- `name` -- Required, max 200 characters

```

### Runbook Template

```markdown

# {Service Name} Runbook

## Health Checks

| Endpoint | Type | Description |
|----------|------|-------------|
| `/health/live` | Liveness | Process is running |
| `/health/ready` | Readiness | Dependencies accessible |

## Dependencies

| Dependency | Failure Impact | Recovery |
|------------|---------------|----------|
| PostgreSQL | Full outage | Readiness probe fails, pod restarts |
| Messaging | Event publishing stops | Circuit breaker, retries |

## Resource Limits

| Resource | Request | Limit |
|----------|---------|-------|
| CPU | 100m | 500m |
| Memory | 256Mi | 512Mi |

## Common Issues

### {Error Code}
- **Symptom:** {what the user sees}
- **Cause:** {root cause}
- **Resolution:** {steps to fix}

## Alerts

| Alert | Severity | Condition | Runbook Action |
|-------|----------|-----------|----------------|
```

## Guidelines

- Accuracy over completeness -- skip a section rather than guess
- Update, don't replace -- preserve manually-written content outside generated markers
- Reference code -- every fact should be traceable to a source file
- Keep it scannable -- tables, headers, and short paragraphs over walls of text
- Date everything -- the metadata comment helps track staleness

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [makigjuro](https://github.com/makigjuro)
- **Source:** [makigjuro/cloudstack-ai-plugins](https://github.com/makigjuro/cloudstack-ai-plugins)
- **License:** MIT
- **Homepage:** https://github.com/makigjuro/cloudstack-ai-plugins#quick-start

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-makigjuro-cloudstack-ai-plugins-docs
- Seller: https://agentstack.voostack.com/s/makigjuro
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.