michat-friendly-documents

Use this skill when you’re creating or revising a document that you expect to consult repeatedly in MiChat (guides, rules, runbooks, profile notes, living docs). The goal is to make the document easy to search, easy to read in sections, and safe to update over time.

Core principle

Write documents so MiChat can retrieve and update them in small, precise chunks:

• Prefer clear headings that carry the document’s taxonomy.
• Prefer small, stable sections over long unbroken prose.
• Make it obvious what each section is for.

Recommended shape

A good default structure (Markdown):

• Optional YAML frontmatter: title, optional type, optional tags, optional updated.
• A short “How to use this document” paragraph (1–3 sentences).
• Headings (H1/H2/H3) that carry the taxonomy.

Example skeleton

---
title: Example guide
type: guide
updated: 2026-01-13
---

How to use: Consult this when making decisions about X. Prefer section reads; update only the relevant section when something changes.

# Overview

## Key constraints

## Common edge cases

# Details

## …

Heading discipline

• Use meaningful, specific headings (“Authorisation flow”, “Failure modes”, “FAQ”) rather than generic ones (“Notes”, “Stuff”).
• Avoid very large sections. If a section is getting long, split it.
• Keep heading titles stable once the doc is established; stability makes section updates safer.
• Avoid having multiple sections with the exact same heading at the same level; unique, stable headings make targeted section updates safer.

Writing for retrieval

• Put key terms in headings and first sentences (what someone would search).
• Prefer concrete wording over clever wording.
• If the document contains lists of rules, keep them as bullets or numbered items for clarity.

Updating without rewriting everything

MiChat works best when changes can be made to one section at a time.

Good patterns

• Add new material as a new headed section.
• Change one headed section when something changes.
• Keep “quick reference” material near the top, and deeper detail below.

Patterns to avoid

• A single long wall of text with few headings.
• Frequent renaming of headings (breaks targeted updates).

Choosing what kind of document this is

Not every document needs to be “curated.” Two useful types:

• Curated guides (stable): written to be consulted repeatedly; update deliberately, section by section.
• Working notes (evolving): logs, scratch notes, ongoing lists. These can be rougher, but still benefit from headings if they grow.

When to switch skills

If you need a draft/archive/trash workflow (safe iteration, promotion, soft delete, reorganising), use the filesystem-enabled documents workflow skill (e.g. documents-workspace).