Doc Skill
Creates or updates docs/<artifactId>.md based on the existing project
and a structured interview.
Philosophy: Documentation is not an appendix – it is part of the product.
Good docs emerge from the source code, not alongside it.
What This Skill Does
- Analyzes the project – automatically evaluates pom.xml, properties, docker-compose, source code
- Fills gaps via interview – only asks what cannot be derived from the code
- Creates or updates –
docs/<artifactId>.md from template or targeted additions
How to Use
Document the project
Create docs for my Spring Boot project
Update the docs with the new messaging feature
Instructions
Step 1 – Analyze Project (automatic)
Before the interview, read and evaluate existing project artifacts:
| File |
Extracted Information |
pom.xml |
groupId, artifactId, framework, active dependencies (DB, messaging, Keycloak) |
src/main/resources/application.properties |
Configured ports, database name, realm |
docker-compose.yml |
Services, ports, credentials |
specs/*.md |
Existing feature specs as basis for API documentation |
src/main/java/**/boundary/rest/ |
REST endpoints (paths, methods) |
src/main/java/**/boundary/messaging/ |
Messaging consumers (channels) |
src/main/java/**/entity/ |
Entities / data model |
src/main/resources/db/migration/ |
Flyway migrations → database schema |
Already determined information must not be asked again.
Step 2 – Interview (only fill gaps)
Only ask what cannot be clearly derived from the source code:
| # |
Question |
Only ask when |
| 1 |
Brief project description (1–2 sentences: what does it do?) |
No README.md present |
| 2 |
Target audience / users (internal API, public, other team?) |
Unclear from code |
| 3 |
Special configuration notes (secrets, external systems) |
Not in application.properties |
| 4 |
Known limitations / open TODOs |
Always ask |
| 5 |
Should all template sections be filled? |
Always ask – some sections may be omitted |
Step 3 – Create or Update
Create: docs/<artifactId>.md does not exist
→ Generate file from template templates/project-doc.md.template, fill all placeholders.
Update: docs/<artifactId>.md already exists
→ Read file, replace or add changed/new content in a targeted way.
→ Do not overwrite existing manual additions by the user – only update empty or
outdated sections.
→ Add an update note at the end of the file:
_Last updated: {{DATE}} (doc)_
Template Sections
| Section |
Required |
Source |
| Project Overview |
Yes |
Interview + pom.xml |
| Stack & Versions |
Yes |
pom.xml |
| Local Development |
Yes |
docker-compose.yml, application.properties |
| Architecture (BCE) |
Yes |
Package structure |
| API Reference |
If REST present |
boundary/rest/** |
| Messaging |
If RabbitMQ active |
boundary/messaging/**, application.properties |
| Auth / Keycloak |
If quarkus-oidc / oauth2-resource-server active |
application.properties |
| Configuration Reference |
Yes |
application.properties |
| Deployment |
Yes |
Dockerfile, docker-compose.yml |
| Known Limitations |
Yes |
Interview |
References
| File |
Description |
| templates/project-doc.md.template |
Template for project documentation |
Output Path
docs/<artifactId>.md
The docs/ directory is created if it does not exist.
Conventions
- Language: English in prose, headings, and code blocks
- Filename:
<artifactId>.md in kebab-case
- Version numbers taken from
pom.xml – no guessing
- Passwords / secrets only as placeholders (
<your-secret>) – never real values
- Co-Author:
<!-- Generated via doc · Co-Author: Claude (claude-sonnet-4-6, Anthropic) -->
Position in Workflow
[spec-feature] optional – business requirements
|
[openapi] if OpenAPI spec needed
|
[java-scaffold] framework: DB, messaging, infra
|
[review] code review
|
[doc] <-- project documentation
1---2name: doc-23description: Creates or updates project documentation as a Markdown page in docs/. Automatically analyzes pom.xml, properties, docker-compose, and source code – only asks what cannot be derived from the code. Use this skill for "document the project", "write docs", "update the docs", "create a README" or when a new project needs technical documentation.4---56# Doc Skill78Creates or updates `docs/<artifactId>.md` based on the existing project9and a structured interview.1011> **Philosophy:** Documentation is not an appendix – it is part of the product.12> Good docs emerge from the source code, not alongside it.1314---1516## What This Skill Does17181. **Analyzes the project** – automatically evaluates pom.xml, properties, docker-compose, source code192. **Fills gaps via interview** – only asks what cannot be derived from the code203. **Creates or updates** – `docs/<artifactId>.md` from template or targeted additions2122## How to Use2324```25Document the project26```2728```29Create docs for my Spring Boot project30```3132```33Update the docs with the new messaging feature34```3536---3738## Instructions3940### Step 1 – Analyze Project (automatic)4142Before the interview, read and evaluate existing project artifacts:4344| File | Extracted Information |45|------|---------------------|46| `pom.xml` | groupId, artifactId, framework, active dependencies (DB, messaging, Keycloak) |47| `src/main/resources/application.properties` | Configured ports, database name, realm |48| `docker-compose.yml` | Services, ports, credentials |49| `specs/*.md` | Existing feature specs as basis for API documentation |50| `src/main/java/**/boundary/rest/` | REST endpoints (paths, methods) |51| `src/main/java/**/boundary/messaging/` | Messaging consumers (channels) |52| `src/main/java/**/entity/` | Entities / data model |53| `src/main/resources/db/migration/` | Flyway migrations → database schema |5455Already determined information **must not be asked again**.5657### Step 2 – Interview (only fill gaps)5859Only ask what cannot be clearly derived from the source code:6061| # | Question | Only ask when |62|---|----------|--------------|63| 1 | **Brief project description** (1–2 sentences: what does it do?) | No `README.md` present |64| 2 | **Target audience / users** (internal API, public, other team?) | Unclear from code |65| 3 | **Special configuration notes** (secrets, external systems) | Not in `application.properties` |66| 4 | **Known limitations / open TODOs** | Always ask |67| 5 | **Should all template sections be filled?** | Always ask – some sections may be omitted |6869### Step 3 – Create or Update7071**Create:** `docs/<artifactId>.md` does not exist72→ Generate file from template `templates/project-doc.md.template`, fill all placeholders.7374**Update:** `docs/<artifactId>.md` already exists75→ Read file, replace or add changed/new content in a targeted way.76→ **Do not overwrite** existing manual additions by the user – only update empty or77 outdated sections.78→ Add an update note at the end of the file:79 `_Last updated: {{DATE}} (doc)_`8081### Template Sections8283| Section | Required | Source |84|---------|----------|--------|85| Project Overview | Yes | Interview + pom.xml |86| Stack & Versions | Yes | pom.xml |87| Local Development | Yes | docker-compose.yml, application.properties |88| Architecture (BCE) | Yes | Package structure |89| API Reference | If REST present | boundary/rest/** |90| Messaging | If RabbitMQ active | boundary/messaging/**, application.properties |91| Auth / Keycloak | If quarkus-oidc / oauth2-resource-server active | application.properties |92| Configuration Reference | Yes | application.properties |93| Deployment | Yes | Dockerfile, docker-compose.yml |94| Known Limitations | Yes | Interview |9596---9798## References99100| File | Description |101|------|-------------|102| [templates/project-doc.md.template](templates/project-doc.md.template) | Template for project documentation |103104### Output Path105106```107docs/<artifactId>.md108```109110The `docs/` directory is created if it does not exist.111112---113114## Conventions115116- **Language:** English in prose, headings, and code blocks117- **Filename:** `<artifactId>.md` in kebab-case118- Version numbers taken from `pom.xml` – no guessing119- Passwords / secrets only as placeholders (`<your-secret>`) – never real values120- **Co-Author:** `<!-- Generated via doc · Co-Author: Claude (claude-sonnet-4-6, Anthropic) -->`121122### Position in Workflow123124```125[spec-feature] optional – business requirements126 |127[openapi] if OpenAPI spec needed128 |129[java-scaffold] framework: DB, messaging, infra130 |131[review] code review132 |133[doc] <-- project documentation134```
mgoericke