# Docfront

> Conventions for writing, organizing, and browsing documentation in a docs/ directory using docfront. Use when creating documents, restructuring documentation, or unsure about frontmatter format and file naming conventions.

- Skill: `paleo/docfront` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add paleo/docfront`
- Raw SKILL.md: https://api.skillmd.com/api/skills/paleo/docfront/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: CC0 1.0
- Author: paleo (https://skillmd.com/u/paleo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/paleo/docfront

---


# Authoring Documentation

All project documentation lives in the `docs/` directory. The `docfront` CLI lets both humans and AI agents discover and read documents without leaving the terminal.

## Browsing with CLI

> Run commands via the project's package manager (e.g. `npm run docfront --`, `pnpm docfront`).

```bash
docfront                                          # list root docs
docfront --dir topic-a --dir topic-b/sub-topic-c  # list subdirectories
docfront --recursive                              # list everything
docfront --read doc-1.md topic-a/doc-2.md         # read documents (frontmatter stripped)
docfront --check                                  # validate all files
```

## Workflow

1. **Understand the Subject** — clarify what needs to be documented. Ask the user if unclear.
2. **Determine Placement** — scan existing docs (`docfront --recursive`). Decide: new file, existing file, which subdirectory. Discuss with the user if unclear.
3. **Write** — follow the conventions below.

## Writing Guidelines

- **Target audience:** an experienced newcomer — someone technically capable but unfamiliar with this specific project.
- Be brief and specific — no obvious information, no generic best practices.
- Typical document: 40–80 lines.
- Prefer referencing source files over large code blocks.
- If the title makes the purpose obvious, omit the `summary`.

## File and Directory Naming

- Use **lowercase-with-dashes** (kebab-case) for new files and directories.
- Uppercase is allowed by the CLI (e.g. `RELEASING.md`).
- Names must be **shell-safe**: no spaces, no quotes, no special characters. The CLI validates this for both files and directories. Use `docfront --check` to verify.
- Use `.md` (Markdown) for all documents.
- Use short, descriptive names.
- Group related documents into subdirectories. Subdirectories can be nested.

## YAML Frontmatter

`.md` files can start with a YAML frontmatter block. Add it when it adds value — especially when the filename or heading alone is not explicit enough. It is not required; when frontmatter is absent, the CLI falls back to the first `# heading` in the document body for the title. Fields:

| Field | Required | Description |
| --- | --- | --- |
| `title` | No | A human-readable display name shown in listings. Falls back to the first `# heading` when absent. |
| `summary` | No | One concise sentence. If the title already makes the purpose obvious, omit the summary to avoid redundancy. |
| `read_when` | No | A YAML list of short, action-oriented hints. Each hint completes: *"Read this document when you are…"* |

## Document Body

After the closing `---` of the frontmatter, write standard Markdown. There are no constraints on the body format — use headings, code blocks, tables, and lists as needed.

```markdown
---
title: Your Title Here
summary: A one-sentence description of what this document covers.
read_when:
  - first situation when this document is useful
  - second situation
---

# Your Title Here

Start your content here…
```

## References

- [Installing Docfront CLI](references/installation.md) — how to add docfront CLI to a project.
- [Bootstrapping Documentation](references/bootstrapping-documentation.md) — instructions for creating or extending project documentation by exploring the codebase.
- [Migrate Existing Documents](references/migrate-existing-docs.md) — guide for bringing an existing folder of Markdown documents into docfront conventions (naming, frontmatter).
- [Migrate Skills to Docfront Documentation](references/migrate-skills-to-docfront.md) — guide for moving internal project documentation from agent skills into `docs/`.