AI docs kit
Get your AI to write Markdown docs in the structure GitDoco publishes best. GitDoco doesn't run the AI: you use your own.
How to use it
Prompt
Use it to write or overhaul your docs now. Works with any AI.
- Copy the prompt.
- Paste it into your AI. An agent that can see your repository (such as Devin) writes the files itself. A chat without access to your repository also needs your code and any existing docs attached.
- Review what it writes.
Agent skill
Use it to keep your docs right from now on, without pasting anything each time.
- Copy the skill.
- Save it as
gitdoco-docs/SKILL.mdwherever your agent loads skills. - Ask your agent to write or update the docs. It follows the rules whenever it works on them.
Then: commit the files to README.md and docs/ and push. GitDoco rebuilds your site, and the build page shows anything to fix.
The prompt and skill are in English. AI tools follow them whatever language your docs are in.
The kit
Prompt
You are writing documentation for a GitHub repository that GitDoco publishes as a website. GitDoco needs no configuration: it builds the site from the repository's Markdown files on every push. Follow these rules.
Structure
- README.md at the repository root is the site's home page. Start it with one "# " heading (the site's title) followed by a one-paragraph summary of the project.
- Put the rest of the documentation in a top-level docs/ folder (or the folders selected in GitDoco). Each Markdown file (.md or .markdown) becomes one page.
- Don't put an index.md or README.md directly in the docs folder: it would replace README.md as the home page, and README.md would not be published.
- Other Markdown files at the repository root, such as CONTRIBUTING.md, are published as pages too if they are selected in GitDoco.
- Sub-folders become sections in the sidebar. Give each sub-folder an index.md as its landing page (a README.md also works); without one, GitDoco generates an "All pages in {folder}" page.
- Order pages and folders with a number prefix such as 01-install.md, 02-configure.md. The prefix sets the order and is hidden from titles. Unprefixed items follow, in alphabetical order.
- Never create two files that would share an address, such as docs/guide.md beside a docs/guide/ folder. Use docs/guide/index.md instead.
Pages
- Start every page with exactly one "# " heading; it becomes the page title in the sidebar and in search.
- Use "## " for sections and "### " for sub-sections. These appear under the page in the sidebar, so keep them short and descriptive. Don't skip levels.
- Link to other pages with relative links to their .md files, e.g. [Configure](02-configure.md) or [Install](../01-install.md#requirements). GitDoco turns these into site links. Heading anchors follow GitHub's rules. Don't write links between pages as full github.com URLs. Links to other repository files open on GitHub.
- Put images in the repository and link them relatively, e.g. . PNG, JPEG, GIF, SVG, WebP and AVIF are supported.
- Draw diagrams as Mermaid code blocks (```mermaid). They are rendered as images when the site is built.
- Label every code block with its language (```bash, ```php, ```yaml) so it is highlighted.
- Use GitHub-flavoured Markdown: tables, task lists and strikethrough work. Front matter is ignored.
- Don't rely on HTML scripts, styles, iframes, forms or embeds: GitDoco removes them.
Content
- Write for a reader who has just found the project: what it is, how to install it, how to use it, then reference detail.
- Keep each page to one topic. Prefer several short pages over one long one.
- Use British or American English consistently, matching the existing docs.
Agent skill gitdoco-docs/SKILL.md
---
name: gitdoco-docs
description: Write or restructure a repository's Markdown documentation so GitDoco publishes it as a well-organised site. Use when asked to write, reorganise or review the docs in README.md or docs/.
---
# Writing docs for GitDoco
GitDoco builds a documentation site from a repository's README.md and docs folder on every push, with no configuration file. Follow these rules whenever you create or edit documentation in this repository.
## Layout
- README.md at the repository root is the home page: one `#` heading, then a one-paragraph summary.
- All other pages live in `docs/` (or the folders selected in GitDoco). One `.md` or `.markdown` file is one page; each sub-folder is a sidebar section.
- Never put an `index.md` or `README.md` directly in `docs/`: it replaces README.md as the home page, and README.md is then not published.
- Other root Markdown files, such as `CONTRIBUTING.md`, are published as pages if they are selected in GitDoco.
- Give each sub-folder an `index.md` (a `README.md` also works). Without one, GitDoco generates an "All pages in {folder}" page.
- Order with number prefixes (`01-install.md`, `02-configure.md`, `01-basics/`). Prefixes are hidden from titles.
- Never let two paths share an address: `docs/guide.md` and `docs/guide/` clash, and the build fails. Use `docs/guide/index.md`.
## Pages
- Exactly one `#` heading per page: it is the page title.
- `##` and `###` headings are listed under the page in the sidebar; keep them short, and don't skip levels.
- Link between pages with relative links to `.md` files (`[Configure](02-configure.md#options)`); anchors follow GitHub's rules. Never link between pages with full github.com URLs. Links to other repository files open on GitHub.
- Store images in the repository and reference them relatively. Supported: PNG, JPEG, GIF, SVG, WebP, AVIF.
- Use fenced Mermaid blocks for diagrams, and a language on every code block.
- GitHub-flavoured Markdown is supported. Front matter is ignored. Scripts, styles, iframes, forms and embeds are removed.
## Limits
- Each file at most 5 MB; the README, docs and their images at most 40 MB and 5,000 files in total; the built site at most 200 MB.
## Before finishing
- Check every relative link points at a file that exists.
- Check no file and folder share a name in the same directory.
- Check each sub-folder of `docs/` has an `index.md`, `docs/` itself has none, and each page starts with one `#` heading.