---
title: How your knowledge grows
nav: How knowledge grows
group: Reference
order: 1.9
---
# How your knowledge grows

Your space is a folder of plain text pages, and five rules make it more useful
every time you work. Any AI app can follow them, with Mainmind or without it.

## One page looks like this

```markdown
---
id: check-bank-details-first
type: lesson
date: 2026-09-25
source: work/2026-09-24-march-invoices.md
applies-to: skills/pay-a-supplier/SKILL.md
state: pending
---

# Check the supplier's bank details before the first payment

Alder & Ash paid a new supplier's old account in March. The supplier had
changed banks; the invoice showed the new details.
```

The lines at the top say what the page is, when it was written, where it came
from and whether it is still current. A lesson stays `pending` until the owner
says yes and it is folded into the page it names. The rest is ordinary writing.

## A skill looks like this

A skill is how one kind of work gets done: paying a supplier, applying to a
job, running a weekly review. Each skill is a folder with one `SKILL.md` in
it, written in the [Agent Skills](https://agentskills.io) format. Claude,
Codex, Cursor and other AI apps already read that format, so the skill works
in whichever app you open.

```markdown
---
name: pay-a-supplier
description: Pay a supplier's invoice after checking it. Use when an invoice is due.
metadata:
  date: "2026-09-25"
  source: work/2026-09-24-march-invoices.md
  state: current
  tags: money, suppliers
---

# Pay a supplier

1. Match the invoice to the order and what arrived.
2. Check the bank details against the supplier's page.
3. Ask the owner before any money leaves.
```

`name` is the folder's name. `description` says what the skill does and when
to use it, which is how an AI app knows to pick it. Page details go under
`metadata`; a skill is in use once its `state` there is `current`, and a new
one starts as `draft`. `tags` are a few plain words for what the skill is
about, like `support`, `sales` or `interviews`, separated by commas; the app
lets you tap a tag to see only those skills, and an agent that writes or
updates a skill sets them. Who may see a skill and how it changes go there too,
as `access-scope` and `write-class`; a skill that leaves them out takes the
ones the space sets for all skills. Other pages in the folder say them at the
top of the file. A skill can keep scripts, templates or
longer notes in the same folder. Spaces made before skills keep the same thing as pages in a
`processes` folder, and Mainmind reads both as skills.

## Write it plainly

The same page is read by a person and by their AI, so write it once, for a
newcomer. What a person can follow, an agent can follow too.

- **Say what it is for and when to use it, in one line.** For a skill, that
  line is the `description`: "Pay a supplier's invoice after checking it. Use
  when an invoice is due."
- **Lead with what you get.** Then when to use it, the steps, when it is
  done, and what to do if something goes wrong.
- **One action per step.** Number the steps and start each with a verb.
- **Keep sentences short.** Most under 25 words, none over 40.
- **Use everyday words.** Say "where it came from", not "provenance", and
  "permission", not "Authority". Mainmind names any system word it finds and
  a plainer one to use.
- **Keep every fact exact.** Plain words never drop an amount, a date, a
  limit or an approval.

- **Draw it when words aren't enough.** A skill with branches or handoffs can
  add a diagram as a `mermaid` block. The skill's page draws it as a
  picture, and an AI reads the same text. Flowcharts, sequence and state
  diagrams work best. Labels are drawn as plain words, and flowchart layout
  settings written inside a diagram are ignored.

```mermaid
flowchart LR
  A[Invoice arrives] --> B{Matches the order?}
  B -- Yes --> C[Ask the owner to pay]
  B -- No --> D[Ask the supplier]
```

Mainmind checks this when a skill is proposed or first saved. A skill that
needs work comes back to the agent with the lines to fix, so the owner only
sees pages that read well. Only new or changed sentences are checked, so older
pages are never blocked and get plainer each time someone touches them.

## The five rules

| Rule | What it means |
|---|---|
| **One thing per page** | Each page holds one fact, lesson or skill. Link to a page instead of copying it. |
| **Say where it came from** | A fact names its source and date. A fact with no source counts as unchecked. |
| **Add, don't erase** | To correct something, add a newer page that replaces the old one. The history stays, so you can see why it changed. |
| **Turn work into lessons** | When work teaches something, write it down as a lesson and name the skill or page it should improve. When it comes up again, fold it into that skill. |
| **Ask only for what steers** | Notes, lessons and records are added freely. Changes to a skill, what an agent is told to do, or who may do what ask the owner first. |

## Why this is enough

Knowledge compounds because each piece of work leaves a small, dated,
sourced page behind, and lessons flow back into the skill the next piece of
work uses. This works the same in a business, a job hunt or a project. There is no database to learn and no special app to read it: the
pages are Markdown, so you can open them anywhere, and
[Download everything](/docs/getting-started#take-everything-with-you) gives
you the whole folder.

Mainmind adds what a folder cannot do alone: every AI app you connect reads the
same pages, your agents save what they learn as they work, and the owner is
asked before anything that steers future work changes.