doc

name	doc
description	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.
argument-hint	[artifactId]

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

1. Analyzes the project – automatically evaluates pom.xml, properties, docker-compose, source code
2. Fills gaps via interview – only asks what cannot be derived from the code
3. 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