Malou Dongelmans

Episode 03

Markdown pyramid, a Claude Code skill

Third post in “Tools I build with.” Full write-up of a skill that solves two problems that compound on any serious project.

The problem

When you build a project with Claude Code, note files pile up fast: plans, decisions, design notes, journal entries. Without a clear structure, two things happen every session.

  1. Claude searches across all your notes to find what’s relevant, or ends up loading too much context at once. Either way, it’s costing more per question than it needs to.
  2. More of your project is exposed to accidental edits. The wider Claude’s attention spreads, the easier it is for a change to land in a file you weren’t working on.

Both showed up often enough on projects here. A small add-on for Claude Code now handles them together.

What the skill is

Two parts, working independently but pulling the same direction.

  • A Claude Code skill. A folder of markdown files at ~/.claude/skills/markdown-pyramid/. Claude auto-discovers it. When you ask something that matches “organise my project notes” or “stop Claude reading every file”, the skill’s instructions kick in.
  • A CLAUDE.md rule you paste into your project. This tells Claude how to read your notes: start at the top of the pyramid, go deeper only on demand.

The skill teaches Claude how to write notes in a three-layer pyramid. The CLAUDE.md rule teaches Claude how to read them efficiently. Together, Claude only opens the file it actually needs.

The pyramid

notes/
├── INDEX.md                     ← what your project is + current focus
├── design/
│   ├── README.md                ← design system summary
│   ├── colours.md
│   └── typography.md
├── features/
│   ├── README.md                ← what the site does
│   ├── contact-form.md
│   └── chat-widget.md
└── stack/
    ├── README.md                ← how it's built
    └── hosting.md

INDEX.md summarises the areas. Each area’s README.md summarises its topic pages. Claude usually answers from the top, because the summary is enough, and only descends when the question requires it.

Optional variant: a backlog area. If you want to track todos inside the pyramid rather than in a separate tool (Linear, GitHub Issues, a sticky note on your monitor), add a dedicated backlog/ folder at the root of your notes. Same three-layer idea: a master list in backlog/README.md with P1/P2/P3 priority sections, individual pages for items that need more context, an archive/ sibling for done items. The skill’s structure.md has the full pattern.

Install

The skill is open source, at github.com/yves-lou/markdown-pyramid. Installation is four short steps.

1. Check git is installed

Open a terminal and type:

git --version

If a version number appears, git is installed. If the terminal says command not found, install git first from git-scm.com. Git is a free program most developers already have.

2. Clone the skill into Claude Code’s skills folder

Claude Code looks for installed skills in a specific folder on your laptop:

  • macOS and Linux: ~/.claude/skills/
  • Windows: %USERPROFILE%\.claude\skills\ (the same folder, named differently)

Run this single command. It creates the folder if it doesn’t exist, then downloads the skill into it:

git clone https://github.com/yves-lou/markdown-pyramid ~/.claude/skills/markdown-pyramid

The ~ means “your user folder”, which works on macOS, Linux and Windows PowerShell.

3. Verify the install

List what landed in the folder:

ls ~/.claude/skills/markdown-pyramid

You should see SKILL.md, structure.md, workflow.md, integration.md, example.md and a templates/ folder. If the list is empty, the clone didn’t finish and you need to re-run it.

4. Call the skill from Claude Code

Close any running Claude Code session, start a fresh one. The skill is now available in two ways.

As a slash command, inside a Claude Code session, type:

/markdown-pyramid

Claude Code routes your next request through the skill’s instructions.

Automatically, from plain-English prompts. Claude Code reads the skill’s description and decides for itself when to use it. These kinds of questions will trigger the skill without a slash command:

  • “Organise the notes for this project.”
  • “Stop Claude from reading every note file on every session.”
  • “Help me structure the design folder.”

Wire it into a project

Installing the skill teaches Claude how to organise notes. The final step tells Claude when to apply the pyramid reading rule inside a specific project. Add this block to that project’s CLAUDE.md file at the project root (create the file if it doesn’t exist yet):

## Project notes: markdown-pyramid

This project organises its markdown notes in a three-layer pyramid under `notes/`. Read only what you need:

1. Start by reading `notes/INDEX.md`.
2. Only open an area's `README.md` when the user's request concerns that area.
3. Only open individual topic pages when the user asks about one specifically.
4. Don't search across the whole `notes/` tree.

The full snippet, plus optional additions (like the backlog variant), is in the repo’s integration.md.

From here on, every Claude Code session that starts in that project’s folder respects the pyramid automatically.

Why this matters

The pyramid is less about saving money and more about thinking through the shape of a project before anything is written.

Most projects start by making things and write notes about them later. Design decisions end up in one place, deployment in another, ideas for later in a third. Claude Code then has to hunt across everything each time a question comes up.

Taking ten minutes to plan the shape of your notes before anything lands in them is a small upfront investment. It pays off every session after: you know where to put new notes, and Claude knows where to look.

That’s why this pattern has been packaged as an add-on anyone can install, rather than staying a personal habit.

The second benefit: edits stay where they belong

This one’s easier to feel than explain. When Claude has 50 files in its attention, its suggestions sometimes touch files you didn’t ask it to touch. Sometimes helpfully (“I updated the README to match”), sometimes not.

The pyramid narrows Claude’s attention to the exact layer it’s working on. Files above and below stay closed. Changes land where you meant them to land.

What’s inside

  • SKILL.md: what Claude reads first. Routes to everything else.
  • structure.md: the file layout, area naming, topic naming.
  • workflow.md: adding, updating, archiving without drifting.
  • integration.md: the full CLAUDE.md rule plus install details.
  • example.md: a real project structured this way.
  • templates/: copy-paste starters for each layer. index.md, area-readme.md, topic.md, plus backlog-readme.md and backlog-item.md if you also want to track todos inside the pyramid.

What’s next in the series

  • Service account + campaign planning. How to let a small Python script write to a Google Sheet, used in this series to plan the episodes.
  • …and more tools ahead, each tied to a real project.

Subscribe below to get each one when it’s published.