Agentic Markdown

A simple way to organize and navigate Markdown so humans and agents can quickly find what matters without guesswork. It reveals details step by step, keeps structure clear and connections explicit, and helps you focus only on what’s relevant instead of reading everything.

Model

unit: one logical context block with exactly one entrypoint
entrypoint: exactly one of
```
name.md
```
or
```
name/index.md
```
, never both
child unit: a unit reached by one structural
```
Source:
```
link from its parent
external context: non-tree units listed under
```
Dependencies
```
or
```
Related
```
inline section: short content that remains in the current entrypoint
extracted section: content moved to a child unit, leaving heading, description, and
```
Source:
```

No implicit discovery. File proximity, sibling files, directory contents, and backlinks do not define structure.

Entrypoints

Every unit entrypoint must use this format:

---
title: Human Title
tags: [tag-a, tag-b]
---

# Human Title

Short overview of this unit.

## Section Name
One or two lines describing the child content.
Source: [Readable Title](./child.md)

Frontmatter rules:

```
title
```
is required, string, human-readable
```
tags
```
is required, flat list; it may be empty
frontmatter title and top
```
#
```
heading should match unless preserving an existing public title is more important

Child targets are also entrypoints and must follow the same format.

Source Links

Source:

is the only structural child directive.

Required form:

## Section Name
One or two lines explaining why this child exists.
Source: [Readable Title](./relative-entrypoint.md)

Rules:

must be under a section header
must have a useful one- or two-line description before it
must use a Markdown link with readable label text
must use a relative path
must point to a valid unit entrypoint
must not point to external units, independent sibling units, URLs, anchors, or unlinked nearby files
raw paths such as
```
Source: ./workflow.md
```
are invalid in v2

Semantics:

defines the tree hierarchy
participates in primary traversal
is eligible for recursive descent when relevant
order follows the
```
Source:
```
line order in the file

External Context

External context is explicit and not part of the tree.

Use

Dependencies

for external units required for correct interpretation:

## Dependencies

| Document | Purpose |
|---|---|
| [Glossary](../glossary.md) | Defines required terms |

Use

Related

for optional expansion:

## Related

| Document | Purpose |
|---|---|
| [Patterns](../patterns.md) | Alternative approaches |

Rules for both tables:

must be Markdown tables with exactly
```
Document
```
and
```
Purpose
```
columns
each row must include one relative Markdown link and a short purpose
links must not be children of the current unit
links are external context, not structural hierarchy

Read

Dependencies

only when ambiguity, undefined terms, or correctness needs require them. Read

Related

only when more context, comparison, or exploration is useful.

Traversal

Follow this algorithm:

Open the entrypoint.
Read frontmatter, overview, section headers, descriptions, and link labels.
If sufficient, stop.
For each relevant
```
Source:
```
, open the child entrypoint.
If ambiguity or missing prerequisite remains, open relevant
```
Dependencies
```
.
If still incomplete or expansion is useful, open relevant
```
Related
```
.
Never scan sibling files, directories, or unlinked files.

Choose relevance from section headers, descriptions, link text, target tags, and the current task. Do not auto-expand every child, dependency, or related document.

Transform Procedure

Check the user request, explicit local constraints, and current linked graph for contradictions. If a real conflict remains, stop and ask for resolution.
Identify the unit boundary from the requested entrypoint and explicit links only.
Choose the canonical entrypoint; if both
```
name.md
```
and
```
name/index.md
```
exist for one unit, keep one and remove or convert the duplicate.
Add or repair required frontmatter on every unit entrypoint.
Inventory sections in order. Keep short sections inline; extract only coherent topics that improve scanability.
For extracted topics, preserve heading identity, choose descriptive relative paths, move content into child entrypoints, and leave description plus
```
Source:
```
.
Convert external non-child references to
```
Dependencies
```
or
```
Related
```
tables when they are needed.
Validate in the order below and fix failures before finishing.

Do not split for symmetry. Do not invent missing children only to satisfy a broken link; either create the child from real inline content or remove/inline the stub.

Contradiction Stops

When step 1 finds mutually exclusive requirements:

make no structural edits
name the conflicting requirements concretely
ask the user which requirement wins
report validation as skipped because the transform intentionally stopped
do not treat later transform steps as ambiguous; they are not applicable until the conflict is resolved

Read an unlinked local constraint file only when the user request, brief, or entrypoint explicitly identifies it. Otherwise, unlinked nearby files remain outside the unit.

Legacy Markdown

When converting legacy Markdown that uses multiple top-level

headings:

keep or create one document-level
```
#
```
heading from the canonical entrypoint title
convert remaining top-level topic headings to
```
##
```
sections unless they become child entrypoints
preserve the visible heading text when extracting; only sanitize filenames
keep heading order stable unless validation requires moving a child link

Splitting

keep one file by default
split when the entrypoint becomes hard to scan or a section is a coherent reusable topic
keep short residual sections inline when they are easy to scan and not reusable
prefer
```
./topic.md
```
for one coherent topic
use
```
./topic/index.md
```
only when that topic has multiple substantial subtopics that should be explicit children
never create vague files like
```
part-1.md
```
sanitize filenames, not headings;
```
FAQ / Edge Cases
```
may become
```
faq-edge-cases.md
```
preserve source order and meaning
never keep substantial duplicate truth inline and in a child

Folder-backed topics are just units whose entrypoint is

index.md

; directories are never traversed implicitly.

Shared reference files that are needed for interpretation but are not owned by the current tree should stay outside the tree and be listed in

Dependencies

. Do not absorb or duplicate them only to avoid an external context table.

Validation

Before finishing, check:

exactly one entrypoint per unit:
```
name.md
```
or
```
name/index.md
```
every entrypoint has valid frontmatter with
```
title
```
and
```
tags
```
each entrypoint has one top
```
#
```
heading and a short overview
every
```
Source:
```
sits under a section header, has a description, and uses readable Markdown-link syntax
every
```
Source:
```
target is relative, exists, and points to a valid entrypoint
resolve every relative link from the file that contains the link, not from the root entrypoint
no
```
Source:
```
target points to
```
Dependencies
```
,
```
Related
```
, URLs, anchors, independent sibling units, or unrelated nearby docs
the
```
Source:
```
graph is acyclic
all
```
Dependencies
```
and
```
Related
```
sections are valid two-column tables with
```
Document
```
and
```
Purpose
```
every dependency/related row has a relative Markdown link and purpose text
no broken links in structural or external-context sections
no implicit filesystem discovery is required to understand the unit

Fix in this order:

duplicate entrypoints
missing or invalid frontmatter
malformed
```
Source:
```
broken links
graph cycles or wrong hierarchy
malformed external-context tables
duplicate inline/extracted truth
vague names or needless depth

Backlinks

Backlinks are optional and non-canonical. If needed, generate them outside source files. They must never affect traversal or validation.

Output

Report:

final tree
external context sections touched
validation result
files changed
any intentionally inline large section and why it stayed inline

agentic-markdown

NPX Install

Tags

SKILL.md Content