makeDoc

Detect the received flags:

• No flags → creation mode
• --update → update mode
• --agent → delegate to the makeDoc-agent agent
• --agent --update → delegate to the agent with the --update flag

If the command includes --agent:

Delegate the entire task to the makeDoc-agent agent using the subagent tool.

Pass as prompt:

• The current working directory (absolute path)
• The received flags without --agent

Example prompt to the agent:

Run the makeDoc skill in the directory: /path/to/project
Flags: --update

Do not perform any exploration or generation yourself. Everything is handled by the agent.

If the command does NOT include --agent:

Explore the current project before writing any file. Do not generate generic content: everything must be specific to the code you are reading.

Follow this process:

---

0. Detect operation mode

Creation mode (no flag):

• Assume no prior documentation exists
• Generate all files from scratch
• If /docs or README.md already exist, warn the user they will be replaced and continue

Update mode (--update):

• Read all existing documentation files before touching the code:
  • README.md
  • docs/*.md
• Identify which sections may be outdated compared to the code
• When writing, preserve content that is still valid and update only what changed
• If a section has information you cannot verify in the current code, preserve it without marking it
• Do not delete existing files; if a file no longer applies, warn the user but do not delete it automatically

---

1. Project exploration

Before writing anything, survey the project:

• Recursively list the directory structure (ignore node_modules, .git, pycache, dist, build)
• Read the project entry points: main, index, app, server, etc.
• Read configuration files: package.json, pyproject.toml, Makefile, docker-compose.yml, .env.example, etc.
• Identify the tech stack, architectural patterns and system layers
• Look for test files if they exist
• Read at least 3-5 business logic files or main modules

If the project is large, prioritize:

1. Main entry point
2. Modules/folders with the most files
3. Configuration and infrastructure files
4. Test folder

---

2. Analysis before writing

Before generating any file, answer these internally:

• What does this project do? What problem does it solve?
• What is the architecture? MVC, layers, microservices, scripts?
• What technologies does it use and why (if inferable)?
• Is there an API? Tests? A database?
• What is ambiguous or incomplete in the code?

In --update mode, also:

• What changed compared to the existing documentation?
• Are there new modules, endpoints, or dependencies not yet documented?
• Are there documented sections that no longer correspond to the current code?
• Did the directory structure change?

---

3. File generation

Write the following files in the project root directory:

Always generate:

• README.md
• docs/architecture.md
• docs/structure.md
• docs/installation.md
• docs/decisions.md

Generate only if applicable:

• docs/api.md → if there are HTTP endpoints, CLI, or a public interface
• docs/testing.md → if there are tests or a testing framework configured
• docs/usage.md → if the project has a user interface, non-trivial usage flows, or CLI commands

---

Content of each file

README.md

# Project Name

## 📚 Documentation
| | |
|---|---|
| [⚙️ Architecture](docs/architecture.md) | System design, components and flow |
| [📁 Structure](docs/structure.md) | Project organization and responsibilities |
| [🚀 Installation](docs/installation.md) | Requirements and steps to run the project |
| [🧠 Technical decisions](docs/decisions.md) | Trade-offs and design justifications |
| [📖 Usage guide](docs/usage.md) | How to use the project, flows and examples *(if applicable)* |
| [🔌 API](docs/api.md) | Endpoints, request/response and examples *(if applicable)* |
| [🧪 Testing](docs/testing.md) | How to run tests and coverage strategy *(if applicable)* |

---

## Description
- What it does
- What problem it solves
- Real use case

## Quick start
Concrete, executable example

## Technologies used
Split into categories as applicable

## Quick installation
Summary in 2-3 steps. Link to docs/installation.md

## Architecture (summary)
Short paragraph. Link to docs/architecture.md

## Project structure
Summarized tree. Link to docs/structure.md

---

docs/architecture.md

• General system design
• Main components and their responsibilities
• System flow (how data travels)
• Patterns used (MVC, repository, services, etc.)
• Database interaction (if applicable)
• Technical justification for design decisions

---

docs/structure.md

• Full directory tree (without node_modules, .git, etc.)
• Explanation of each folder and its responsibility
• Layer separation
• What should NOT go in each folder (if relevant)

---

docs/installation.md

• Prerequisites (runtime, versions, external services)
• Complete step-by-step:
  1. Clone the repo
  2. Install dependencies
  3. Configure environment variables
  4. Configure database (if applicable)
  5. Run the project
• Real, copy-paste-ready commands
• How to verify it works

---

docs/api.md (if applicable)

• List of endpoints or public commands
• For each: method, path, description, request, response, example
• Error handling
• Authentication (if applicable)

---

docs/decisions.md

• Important technical decisions
• Trade-offs considered
• Discarded alternatives (if inferable from the code)
• Justification for "why this way and not another"

---

docs/usage.md (if applicable)

Aimed at the end user or developer who will use the project, not the one who will modify it.

• How the project is used in practice
• Main flows step by step
• Concrete, executable examples of the most common use cases
• Parameters, options, or configurations relevant to the user
• Expected behavior and important edge cases
• Common errors and how to resolve them

Do not repeat information from installation.md. Assume the project is already running.

---

docs/testing.md (if applicable)

• How to run the tests
• What they cover (unit, integration, e2e)
• General testing strategy
• Coverage (if there is a coverage configuration)

---

Writing rules

• If something is not in the code, omit it: do not leave banners like ⚠️ Not verified in generated files. Report omissions only in the final summary to the user, not inside the files.
• No generic text: every section must be specific to the analyzed project
• Show technical judgment: explain the "why", not just the "what"
• Use lists and code blocks when they add clarity
• Avoid obvious explanations
• Be direct: no long introduction, no closing with "hope this helps"
• Language: English, except technical names, paths, commands and code

---

When finished

Report to the user:

• What files were generated or updated
• What sections were preserved unchanged (in --update mode)
• What sections were omitted due to lack of evidence in the code, and why
• If there are files that could be deleted because they no longer apply (in --update mode)
• If anything needs to be completed manually