Skip to content
Skills Library
Programming · Writing

document-project

/document-project

Create or improve project documentation. Use when the user asks to "document the project", "create docs", "improve documentation", "write a README", "add a getting started guide", or mentions that documentation is missing or outdated. Produces a minimal root README.md and a /docs directory with linked pages. All diagrams use ASCII or Mermaid.

Licence
MIT
Last repository change
24.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 24.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Create or improve project documentation. Use when the user asks to "document the project", "create docs", "improve documentation", "write a README", "add a getting started guide", or mentions that documentation is missing or outdated. Produces a minimal root README.md and a /docs directory with linked pages. All diagrams use ASCII or Mermaid.

Triggers from the description

document the projectcreate docsimprove documentationwrite a READMEadd a getting started guide
Original author description

Create or improve project documentation. Use when the user asks to "document the project", "create docs", "improve documentation", "write a README", "add a getting started guide", or mentions that documentation is missing or outdated. Produces a minimal root README.md and a /docs directory with linked pages. All diagrams use ASCII or Mermaid.

How it works

  1. Task Tracking
  2. Phase 1: Understand the Project
  3. Phase 2: Audit Existing Documentation
  4. Phase 3: Plan the Documentation Structure
  5. Phase 4: Write the Root README.md
  6. Phase 5: Write the /docs Pages
  7. Phase 6: Cross-Linking Rules
  8. Phase 7: Output Summary
Original SKILL.md headings · 302 lines, 1,463 words
SKILL.md preview
---
name: document-project
description: Create or improve project documentation. Use when the user asks to "document the project", "create docs", "improve documentation", "write a README", "add a getting started guide", or mentions that documentation is missing or outdated. Produces a minimal root README.md and a /docs directory with linked pages. All diagrams use ASCII or Mermaid.
tools: Bash, PowerShell, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate
model: sonnet
metadata:
  version: 1.0
---

# Document Project

Create or improve project documentation: a minimal root `README.md` that describes the project and links to a `/docs` directory containing all detailed pages. Every file and section is cross-linked so readers can navigate naturally. All diagrams are ASCII or Mermaid — no external image dependencies.

## Task Tracking

Before doing any work, call `TaskCreate` for each phase below. Call `TaskUpdate` (status `in_progress`) when you begin a phase and `TaskUpdate` (status `completed`) when you finish it.

- Understand the project
- Audit existing documentation
- Plan documentation structure
- Write root README.md
- Write /docs pages
- Cross-link pages
- Print summary

## Phase 1: Understand the Project

### Gather project signals

```bash
# Language / runtime / build tool
ls package.json pyproject.toml Cargo.toml go.mod pom.xml build.gradle \
   Makefile CMakeLists.txt *.sln 2>/dev/null

# Entry points and structure
ls src/ app/ lib/ cmd/ internal/ main.* index.* 2>/dev/null

# Existing documentation (audit before creating anything)
find . -maxdepth 3 -name "*.md" -o -name "*.rst" -o -name "*.adoc" \
   ! -path "*/.git/*" ! -path "*/node_modules/*" 2>/dev/null

# Existing /docs directory
ls docs/ 2>/dev/null

# Test directories
ls test/ tests/ spec/ __tests__/ 2>/dev/null

# CI/CD
ls .github/ .gitlab-ci.yml .circleci/ 2>/dev/null
```

Read `package.json`, `pyproject.toml`, `Cargo.toml`, or equivalent to extract:
- Project name and description
- Version
- License
- Dependencies (to understand scope)

Read existing `README.md` fully if it exists — capture its tone, any content worth keeping, and note what is missing.

### Key questions to answer before writing

| Question                                             | Where to look                                         |
|------------------------------------------------------|-------------------------------------------------------|
| What does this project do?                           | README, package manifest description, main entry file |
| Who is the audience? (end users / developers / both) | README tone, API surface, CLI vs library              |
| How do you install it?                               | package manifest, Makefile, CI scripts                |
| How do you run / use it?                             | scripts section, main file, existing docs             |
| How do you run tests?                                | test config, CI workflow, Makefile                    |
| What are the main components?                        | directory structure, imports, module names            |
| Are there configuration options?                     | env files, config schemas, CLI flags                  |
| Is there a deployment / release process?             | CI/CD, Dockerfile, release scripts                    |

## Phase 2: Audit Existing Documentation

Before creating or editing any file, inventory what already exists:

1. List every `.md` / `.rst` / `.adoc` file and its first heading.
2. Check for content worth preserving (installation steps, API references, diagrams).
3. Identify gaps: what is described in code comments or CI scripts but not documented?
4. Note any outdated content (stale commands, removed flags, old file paths).

**Do not delete existing documentation files.** If content should move from one file to another, copy the useful parts and mark the old file as superseded with a link to the new location.

### Badge audit

If the existing `README.md` contains badges (e.g. `[![...](https://img.shields.io/...)](...)` or similar), evaluate each one:

**Keep as-is if the badge:**
- Points to a CI workflow that still exists (check `.github/workflows/` or equivalent).
- Reflects the actual license in the repo (`LICENSE` file or manifest).
- Links to a real published package (npm, PyPI, crates.io, etc.) that matches the project name.
- Shows a coverage report that is actually being generated.

**Recommend a change if the badge:**
- References a CI workflow file or job name that no longer exists.
- Shows a version that mismatches the current manifest version.
- Links to a service (e.g. Travis CI, AppVeyor) that the project has migrated away from.
- Is broken (the image URL returns a 404 or "unknown" state).
- Duplicates information already stated in plain text nearby.

For each problematic badge, output a specific suggestion rather than silently removing it:

> ⚠️ Badge `build` links to `.github/workflows/ci.yml` but that file does not exist (found `build.yml` instead). Suggested fix: update the badge URL to reference `build.yml`.

Do **not** remove any badge without explicit user approval. Only flag and explain.

## Phase 3: Plan the Documentation Structure

Choose the page set based on project complexity:

### Minimal (scripts, small libraries, CLIs)

```
README.md
docs/
  getting-started.md
  configuration.md        (if there are config options)
```

### Standard (libraries, services, larger CLIs)

```
README.md
docs/
  getting-started.md
  architecture.md
  configuration.md
  api.md / usage.md
  contributing.md
```

### Full (platforms, frameworks, multi-service projects)

```
README.md
docs/
  getting-started.md
  architecture.md
  configuration.md
  api.md
  deployment.md
  contributing.md
  adr/                    (architecture decision records, if applicable)
    001-*.md
```

Only create pages that have real content to put in them. A placeholder page with "TBD" is worse than no page.

Present the planned structure to the user and wait for approval before writing any files if significant work already exists. For a project with no docs at all, proceed directly.

## Phase 4: Write the Root README.md

The root `README.md` must be **minimal**. Its only jobs are:

1. Say what the project is (1–3 sentences).
2. Show the quickest possible way to install and run it (copy-paste commands).
3. Link to the `/docs` pages for everything else.

### Template

```markdown
# <Project Name>

<One to three sentences: what it does, who it is for, what problem it solves.>

## Quick Start

\`\`\`<lang>
<install command>
<run command>
\`\`\`

## Documentation

- [Getting Started](docs/getting-started.md)
- [Architecture](docs/architecture.md)
- [Configuration](docs/configuration.md)
- [API Reference](docs/api.md)
- [Contributing](docs/contributing.md)

## License

<License name> — see [LICENSE](LICENSE).
```

**Rules:**
- No feature lists, no lengthy explanations, no screenshots.
- Badges are allowed if they pass the audit in Phase 2. Place them on a single line immediately after the title, before the description. Do not add new badges unless the user asks.
- Every section beyond "Quick Start" that needs more than 3–4 lines belongs in `/docs`.
- If a `README.md` already exists, use Edit to add or update only what is missing; preserve content that is still accurate.

## Phase 5: Write the /docs Pages

### docs/getting-started.md

Cover: prerequisites → install → first run → verify it works. Use numbered steps. Include copy-paste commands. Link back to `README.md` and forward to `configuration.md` if relevant.

### docs/architecture.md

Explain the main components, how they relate, and the data/control flow. **Always include at least one diagram.**

**Mermaid component diagram example:**

````markdown
```mermaid
graph TD
    CLI[CLI / Entry Point] --> Core[Core Library]
    Core --> DB[(Database)]
    Core --> Cache[(Cache)]
    CLI --> Config[Config Loader]
```
````

**ASCII fallback (if Mermaid is not appropriate):**

```
┌─────────┐     ┌──────────┐     ┌──────────┐
│   CLI   │────▶│   Core   │────▶│    DB    │
└─────────┘     └──────────┘     └──────────┘
                      │
                      ▼
                ┌──────────┐
                │  Cache   │
                └──────────┘
```

Use Mermaid for: flowcharts, sequence diagrams, entity-relationship diagrams, state machines.
Use ASCII for: simple box-and-arrow topology diagrams, directory trees, table-like layouts.

### docs/configuration.md

List every configuration option in a table:

| Option | Type | Default | Description |
|---|---|---|---|
| `PORT` | `int` | `8080` | HTTP server port |

Group by source (env vars, config file, CLI flags) if there are multiple.

### docs/api.md or docs/usage.md

- For libraries: public API surface with signatures and examples.
- For CLIs: every command and flag with examples.
- For HTTP APIs: endpoints, request/response shapes, authentication.

### docs/contributing.md

Cover: how to set up the dev environment, run tests, submit a pull request, and the code style expectations. Link to any existing `.github/CONTRIBUTING.md` if it exists rather than duplicating it.

### docs/deployment.md (if applicable)

Cover: environment requirements, build steps, how to deploy, environment variables required in production, rollback procedure.

## Phase 6: Cross-Linking Rules

Every page must be navigable without using the browser back button.

**Required links in every `/docs` page:**
- Top of file: breadcrumb back to root — `[← Back to README](../README.md)`
- Bottom of file: "See also" section with links to related pages.

**In-page section links:**
- When one section references a concept explained in another file, link the first mention: e.g. `See [Configuration](configuration.md#database)`.
- Use anchor links (`#section-name`) for deep links within the same file.

**README Documentation table:**
- Every file in `/docs` must appear in the README's Documentation section. If a new page is added, the README must be updated.

**Cross-link map to maintain:**

```
README.md
  └── links to every docs/*.md

docs/getting-started.md
  └── links to: configuration.md, architecture.md (if helpful)

docs/architecture.md
  └── links to: getting-started.md, api.md / usage.md

docs/configuration.md
  └── links to: getting-started.md, deployment.md (if applicable)

docs/api.md / usage.md
  └── links to: getting-started.md, configuration.md

docs/contributing.md
  └── links to: getting-started.md, architecture.md
```

## Phase 7: Output Summary

After all writes and edits, print:

```
Documentation written:
  ✓ README.md                  (updated — Quick Start section added)
  ✓ docs/getting-started.md    (created)
  ✓ docs/architecture.md       (created — includes Mermaid component diagram)
  ✓ docs/configuration.md      (created — 12 options documented)

Skipped (no content available):
  — docs/deployment.md         (no deployment config found)

Action needed:
  ! docs/api.md                (stub created — public API surface needs manual review)
```

Flag any sections that were left as stubs because the required information could not be inferred from the codebase alone.
Files in this package (2)
  • SKILL.md 11 KB
  • evals/evals.json 8 KB

Versions

RepositoryScoreLicence
This page · dan323/easier-life-skills100MIT
jjmartres/ai-coding-agents100MIT

Database snapshot: 13.11.2026 · package version 71b89593c73a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 2 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95readme
    When the user wants to create or update a README.md file for a project. Also use when the user says 'write readme,' 'create readme,' 'document this project,' 'project documentation,' or asks for he...
  • 90generate-readme
    Generate or refresh a comprehensive, professional README.md for a repository, with architecture overview, mermaid and optional C4 diagrams, repository structure, dependencies, and API documentation. Use whenever the user asks to create, write, update, improve, or regenerate a…
  • 100readme-generator
    Generate, audit, or improve a project README following a 15-section structure (Title, Table of Contents, About, Features, Tech Stack, Architecture, Project Structure, Getting Started, Configuration, Security, How to Contribute, What's Next, License, Acknowledgements, Author)…
  • 90update-docs
    Check and update repository documentation before creating PRs/MRs. Scans for outdated docs, mermaid diagrams, README, API docs. Only runs for repos with docs.enabled=true in config.json. Use when user says "update docs", "check documentation".
  • 100write-project-docs
    Generate the core documentation triad for a project — CLAUDE.md (agent working context), a README, and a CONTRIBUTING guide. Use when the user says "write the README", "create a CLAUDE.md", "add a contributing guide", "document this project", or "set up the docs" for a repo.…
  • 100documenting-projects
    Use when generating, improving, or auditing project documentation. Triggers: 'document this project', 'write docs', 'generate documentation', 'docs are outdated', 'need a README', 'create tutorials', 'API reference docs', 'doc audit', 'documentation review'. Standalone README:…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.