KB Writing Instructions for AI Assistants

Updated Jun 17, 2026 ·

Overview

The goal is to make any AI tool to create KB pages in the same format.

This includes:

• Claude Code
• GitHub Copilot
• Codex-style agents
• Other AI assistants that can create Markdown files
• Future AI tools that can create documentation pages

The reusable guide that the agent will follow is located at joeden/docs/KB-Writing-Guide.md.

EDIT: That location is not ideal because this is a Docusaurus project and files inside docs/ can be rendered as public pages.

The better setup is to keep the reusable AI writing guide outside docs/, and then keep a public KB page that explains the setup.

info

This page is an actual rendered page in the Docusaurus docs tree.

This is not the reusable guide that AI assistants should follow.

There is a separate copy of the guide that AI assistants will follow, located outside the rendered docs tree.

Why Not Put the Guide in docs/

The Docusaurus sidebar uses autogenerated docs from the docs/ folder.

Below is a snippet from sidebars.js that shows how the sidebar is generated.

tutorialSidebar: [{ type: "autogenerated", dirName: "." }]

This means a file like this can become a rendered page.

joeden/docs/KB-Writing-Guide.md

Use docs/ for pages that should be published.

Use a non-rendered folder for internal AI instructions.

Instruction Files

The repository uses separate instruction files for different AI tools.

File	Purpose
AGENTS.md	Instructions for Codex-style agents.
CLAUDE.md	Instructions for Claude Code.
.github/copilot-instructions.md	Instructions for GitHub Copilot.
.agents/KB-Writing-Guide.md	Reusable docs style guide for AI assistants.

These instruction files points to the reusable guide instead of repeating every rule in detail.

EDIT: The old guide path is not used as the source of truth.

joeden/docs/KB-Writing-Guide.md

The active guide is stored outside the rendered docs tree.

joeden/.agents/KB-Writing-Guide.md

KB Page Rules

All AI assistants follows the same KB page rules.

• Add frontmatter to every page.
• Match the frontmatter style used by nearby pages.
• Use the correct folder for the topic.
• Start with a short and simple overview.
• Use clear section headings.
• Use short paragraphs.
• Use short bullet items when they improve scanning.
• Capitalize the first word of every bullet item.
• Use tables when the content is easier to compare in rows.
• Format Markdown tables with padded columns so the pipes align in the raw source file.
• Use inline **Note**: paragraphs for short reminders, small caveats, and minor context.
• Use Docusaurus admonitions when a note, tip, warning, or risk is clearer as a callout.
• Avoid sub-bullets unless they are needed.
• Avoid em dashes.
• Avoid asyndetons, and use conjunctions when listing related ideas in prose.
• Keep the tone practical, calm, and direct.

Table Formatting

Tables are structured in valid Markdown and easy to read in the raw source file.

Align the pipes by padding the columns with spaces.

Good:

| File                              | Purpose                                      |
| --------------------------------- | -------------------------------------------- |
| `AGENTS.md`                       | Instructions for Codex-style agents.         |
| `CLAUDE.md`                       | Instructions for Claude Code.                |
| `.github/copilot-instructions.md` | Instructions for GitHub Copilot.             |
| `.agents/KB-Writing-Guide.md`     | Reusable docs style guide for AI assistants. |

Avoid compact tables when the source is harder to scan.

| File | Purpose |
| --- | --- |
| `AGENTS.md` | Instructions for Codex-style agents. |

Bullet Formatting

Bullet lists should be easy to scan and consistent in the raw Markdown source.

Capitalize the first word of every bullet item.

Good:

- Inspect nearby pages
- Use matching frontmatter
- Choose the right folder
- Use the KB writing style

Avoid bullet items that start with a lowercase word.

- inspect nearby pages
- use matching frontmatter
- choose the right folder
- use the KB writing style

Notes vs Admonitions

Inline **Note**: sections are useful for small reminders.

Docusaurus admonitions are better for callouts that need visual weight.

Use inline notes and admonitions for different situations.

Format	Use for
**Note**:	Short reminders, small caveats, and minor context.
Admonitions	Longer, more important, or visually emphasized callouts.

Recommendations:

• Use inline **Note**: for short reminders, small caveats, and minor context.
• Keep inline notes to one short paragraph.
• Use Docusaurus admonitions when the content is longer, more important, or needs visual emphasis.
• Do not use inline notes for multi-step instructions, long warnings, or high-risk information.

Example:

**Note**: Different AI tools do not all read instruction files equally.

Admonitions

Docusaurus admonitions are used when a paragraph or phrase is better shown as a callout.

Choose the admonition type based on the purpose of the information.

Type	Use for
note	Extra context, reminders, and small clarifications.
tip	Helpful suggestions, shortcuts, and recommended paths.
info	Neutral background information and useful details.
warning	Important cautions, limitations, and possible issues.
danger	High-risk actions, destructive steps, and severe risks.

Use the standard Docusaurus syntax.

:::note

This is extra context that helps explain the topic.

:::

Use a custom title only when it makes the callout clearer.

:::warning[Check the workspace path]

Make sure `launch.json` is created inside the active VS Code workspace.

:::

How AI Tools Should Use This

Before creating a KB page, the AI assistant actually inspects nearby pages in the target folder.

It copies the frontmatter style from nearby pages.

It reads the shared guide.

joeden/.agents/KB-Writing-Guide.md

It then creates the KB page under the correct rendered docs folder.

Example Prompt

Use this style of request when asking an AI assistant to create a KB page.

If the AI assistant is working inside the joeden repo and it reads the repo instruction files, then the rules doesn't need to be included in the prompt every time.

So a short prompt like this should be enough:

Create a KB page about debugging Python in VS Code.

Put it in the correct folder under joeden/docs.

Use these notes:
...

Follow the repo KB writing instructions.

The assistant should then:

• Inspect nearby pages
• Use matching frontmatter
• Choose the right folder
• Use the KB writing style
• Align Markdown tables
• Use Docusaurus admonitions when useful
• Avoid em dashes and asyndetons

Note: Different AI tools do not all read instruction files equally. Codex, Claude Code, and Copilot usually support repo instructions, but behavior can vary depending on the tool, session, workspace root, and settings.

For best results, your prompt can include one short reminder:

Follow the repo KB writing instructions.

Validation

After adding or changing the instruction files, check the file locations.

• The reusable guide should be outside docs/.
• The public explanation page should be inside docs/.
• The AI-specific files should point to .agents/KB-Writing-Guide.md.
• Bullet items should start with capitalized first words.
• Markdown tables should have aligned pipes in the raw source file.
• Inline notes should use **Note**: and stay to one short paragraph.
• Admonitions should use the correct Docusaurus type and syntax.
• Docusaurus should only render the public explanation page.