Skip to content
Skills Library
Programming · Writing

docs-init

/docs-init

Bootstraps a documentation structure (architecture, onboarding, data-model, deployment, security, contributing, and a first ADR) for a project that has little or no docs/ directory, exploring the codebase and populating templates only with content evidenced in the code. Use when the user wants to set up docs, bootstrap documentation, initialize project docs, scaffold a docs/ folder, or create docs from scratch for a new or undocumented project. Not for refreshing or syncing docs that already exist (use docs-update). Not for generating a standalone architecture or ER diagram without the surroun

Repository
cc-arsenal ↗
Licence
MIT
Last repository change
25.10.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
9
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.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

Bootstraps a documentation structure (architecture, onboarding, data-model, deployment, security, contributing, and a first ADR) for a project that has little or no docs/ directory, exploring the codebase and populating templates only with content evidenced in the code. Use when the user wants to set up docs, bootstrap documentation, initialize project docs, scaffold a docs/ folder, or create docs from scratch for a new or undocumented project. Not for refreshing or syncing docs that already exist (use docs-update). Not for generating a standalone architecture or ER diagram without the surroun

Arguments

/docs-init [context]
Original author description

Bootstraps a documentation structure (architecture, onboarding, data-model, deployment, security, contributing, and a first ADR) for a project that has little or no docs/ directory, exploring the codebase and populating templates only with content evidenced in the code. Use when the user wants to set up docs, bootstrap documentation, initialize project docs, scaffold a docs/ folder, or create docs from scratch for a new or undocumented project. Not for refreshing or syncing docs that already exist (use docs-update). Not for generating a standalone architecture or ER diagram without the surroun

How it works

  1. Anti-hallucination guidelines
  2. Workflow
  3. Template Reference
  4. Detection Commands
  5. Usage Examples
  6. Example Output
  7. Notes
Original SKILL.md headings · 155 lines, 1,029 words
SKILL.md preview
---
name: docs-init
description: Bootstraps a documentation structure (architecture, onboarding, data-model,
  deployment, security, contributing, and a first ADR) for a project that has little
  or no docs/ directory, exploring the codebase and populating templates only with
  content evidenced in the code. Use when the user wants to set up docs, bootstrap
  documentation, initialize project docs, scaffold a docs/ folder, or create docs from
  scratch for a new or undocumented project. Not for refreshing or syncing docs that
  already exist (use docs-update). Not for generating a standalone architecture or
  ER diagram without the surrounding document (use docs-diagram).
metadata:
  summary: "Documentation structure initialization"
  author: mgiovani
  version: 2.0.0
disable-model-invocation: true
argument-hint: '[context]'
context: fork
agent: general-purpose
---

# Initialize Project Documentation

Bootstrap a `docs/` structure for a project with little or no existing documentation. Only generate what the codebase actually evidences.

## Anti-hallucination guidelines

Every claim in generated docs must trace to something read or grepped in this run:

1. Verify a file/directory exists before referencing it.
2. Get counts from `ls`/`find`/`grep`, never estimate.
3. Quote real function/class/table names, not assumed ones.
4. An empty directory is not a feature, don't document it.
5. If a claim can't be verified, drop it rather than guess.

## Workflow

### 1. Explore the codebase

Find: source directories with actual code, package manager files (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, ...), database/ORM files, infrastructure configs (Docker, k8s, Terraform), and any existing `docs/`. See Detection Commands below for the exact patterns.

If a Task/subagent tool is available, delegate this to an Explore agent with that scope. Otherwise run the same `grep`/`find` commands inline and `Read` each hit: the result must be the same either way.

Verify every finding before using it: read the package manifest, read the model file, confirm a directory has real files inside it, not just an empty folder.

### 2. Detect project characteristics

From the exploration, determine: language/framework stack, project type (web app, CLI, library, service), whether a database/ORM is present, and whether infrastructure/deployment configs exist. These characteristics drive which doc types Phase 3 decides to generate.

### 3. Decide which docs to generate

- **Always**: `docs/architecture.md`, `docs/onboarding.md`, `docs/adr/0001-record-architecture-decisions.md` (Nygard-format meta-ADR, generate inline, no template file)
- **If a database/ORM was found**: `docs/data-model.md`
- **If deployment configs were found** (Dockerfile, k8s manifest, CI workflow, IaC): `docs/deployment.md`, `docs/security.md`
- **If the project looks collaborative** (multiple contributors in `git log`, an open-source license, no existing CONTRIBUTING): `docs/contributing.md`, `docs/rfc/` directory

Don't generate a doc type with no supporting evidence: an empty data-model.md for a stateless CLI is worse than no file at all.

### 4. Check for existing docs

Scan `docs/`. For any target file that already exists, do not overwrite it: list it under "skipped" and ask the user before touching it. This skill is safe to rerun: by default it only fills gaps.

### 5. Populate templates

Templates live in `assets/templates/` (see reference table below). For each one you're using:

1. Grep it for its actual placeholder set: `grep -oE '\{\{[A-Z_0-9]+\}\}' assets/templates/<name>.md | sort -u`
2. Map every placeholder to a value from step 1/2's verified findings. Never leave a placeholder as a literal `{{TOKEN}}` in the output.
3. Templates mark some sections as conditional with an HTML comment ("delete if...", "only if evidenced"). Where the codebase gives no evidence for that section, delete the whole section (heading included, not just the placeholder text).
4. After writing the file, grep it for `\{\{[A-Z_0-9]+\}\}` again. Zero matches. If any remain, resolve or delete them before moving on.

**Worked example** (a FastAPI + PostgreSQL service):

```
$ grep -oE '\{\{[A-Z_0-9]+\}\}' assets/templates/architecture.md | sort -u
{{COMPONENT_DEPENDENCIES}}
{{COMPONENT_DESCRIPTION}}
{{COMPONENT_NAME}}
{{DATA_FLOW}}
{{DATE}}
{{DEPLOYMENT_SUMMARY}}
...
```

Map each to a verified finding: `{{TECHNOLOGY_STACK}}` becomes "Python 3.12, FastAPI 0.115, PostgreSQL 16 via SQLAlchemy", read from `pyproject.toml` and the model files, not assumed. If `security.md`'s Compliance section has no GDPR/HIPAA evidence in the codebase (no consent flow, no PHI handling), delete that whole section rather than fill it with a guess.

### 6. Write the files

Create `docs/` (and `docs/adr/`, `docs/rfc/` if needed). Write each file that isn't being skipped.

### 7. Validate the diagrams render

Skip if none of the files you wrote has a ```` ```mermaid ```` block. Otherwise you need `mmdc`: install with `npm i -g @mermaid-js/mermaid-cli`, or run it ad hoc by defining `mmdc() { npx -y -p @mermaid-js/mermaid-cli mmdc "$@"; }` first. If Chromium refuses to launch in a sandbox, add `-p` with a puppeteer config of `{"args":["--no-sandbox"]}`.

Run this on the files you wrote; each `FAIL <name>-N.mmd` names the doc and the Nth mermaid block in it:

```bash
d=$(mktemp -d)
for md in <the docs/ files you wrote>; do
  awk -v out="$d/${md//\//__}" '/^```mermaid/{f=out "-" ++n ".mmd"; next} /^```/{f=""} f{print > f}' "$md"
done
for f in "$d"/*.mmd; do mmdc -q -i "$f" -o "${f%.mmd}.svg" || echo "FAIL $f"; done
```

Fix each failing block using its parser error, then re-run until nothing prints `FAIL`. Cap at 3 rounds, then report the blocks that still fail. If `mmdc` can't be installed (no Node, offline), say so in the report and fall back to a careful syntax review of each diagram.

### 8. Report

List what was created, what was skipped (already existed), diagram validation result (rendered, or still failing, or unvalidated), and next steps.

## Template Reference

| Document | Template | Generated when |
|----------|----------|-----------------|
| Architecture | `architecture.md` | always |
| Onboarding | `onboarding.md` | always |
| First ADR | inline (Nygard format) | always |
| Data Model | `data-model.md` | database/ORM detected |
| Deployment | `deployment.md` | deployment config detected |
| Security | `security.md` | deployment config detected |
| Contributing | `contributing.md` | collaborative project |

## Detection Commands

Run these directly (or hand them to the Explore agent from step 1):

```bash
# Language/framework
find . -name "package.json" -o -name "pyproject.toml" -o -name "go.mod" -o -name "Cargo.toml" | head -5

# Database/ORM
find . -name "*models.py" -o -name "*schema.prisma" -o -name "*entity.ts" | head -5

# Infrastructure
find . -name "Dockerfile" -o -name "docker-compose.yml" -o -name "*.k8s.yaml" | head -5

# Project name and description
basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
head -20 README.md 2>/dev/null
```

## Usage Examples

```
docs-init
docs-init for Python FastAPI microservice
docs-init for Next.js SaaS application
```

## Example Output

```
Documentation Initialization Complete

Created:
 docs/architecture.md - System architecture overview
 docs/onboarding.md - Developer onboarding guide
 docs/adr/0001-record-architecture-decisions.md - Meta-ADR
 docs/data-model.md - Database schema (SQLAlchemy detected)
 docs/deployment.md - Deployment guide (Docker detected)

Skipped (already exists):
 docs/contributing.md

Next steps:
 1. Review and customize the generated docs
 2. docs-diagram er / docs-diagram arch for standalone diagrams
 3. docs-adr "Decision Title" for future ADRs
```

## Notes

- Safe to rerun: only fills gaps, asks before overwriting existing files.
- User-supplied context (e.g. "for a FastAPI microservice") steers detection but doesn't replace verification: still confirm the stack from the actual files.
Files in this package (9)
  • SKILL.md 8 KB
  • assets/templates/architecture.md 1 KB
  • assets/templates/contributing.md 6 KB
  • assets/templates/data-model.md 1 KB
  • assets/templates/deployment.md 1 KB
  • assets/templates/onboarding.md 2 KB
  • assets/templates/security.md 2 KB
  • evals/evals.json 3 KB
  • evals/trigger-eval.json 2 KB

Versions

RepositoryScoreLicence
This page · mgiovani/cc-arsenal100MIT
tamaplus/josjis-code100MIT

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

Downloads in the last 30 days: 0 · ranking

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

Similar skills

  • 100init-project
    Use this skill for \"initialize project\", \"set up project\", \"scaffold project\", \"create AGENTS.md\", \"create CLAUDE.md\", \"set up rules\", \"create context directory\", \"vibe rules\", \"project templates\", \"init new project\", \"set up development structure\",…
  • 100docs-diagram
    Generate a Mermaid diagram (ER, architecture, deployment, or security) by reading the actual codebase and writing it to docs/. Use for requests like "draw an ER diagram of these tables", "show me the architecture", "diagram the deployment setup", "visualize the security data…
  • 100documentation-guide
    Guide documentation structure, content requirements, and project documentation best practices. Use when: creating README, documentation, docs folder, project setup, technical docs. Not for: generating docs mechanically from source — use /docgen; changelog entries — use…
  • 100docs-update
    Refresh existing docs (architecture, onboarding, data-model, deployment, security, contributing) so they match the current codebase, verifying every claim against real code instead of guessing. Use when the user says docs are stale, asks to sync docs with recent code changes,…
  • 100generating-project-docs
    Use when creating, refreshing, or updating project-level documentation — README.md, ARCHITECTURE.md, STRUCTURE.md, or scoped section updates
  • 100spec-init
    Initialize a specification system for a project from scratch. Analyzes the codebase to identify architectural layers, domains, boundaries, and key decisions, then generates the initial set of specs (META.md, INDEX.md, domain specs, contracts, architecture docs, ADR template; a…

Feedback and reports

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