dotmd-parser 0.2.0

Dependency graph parser for .md skill files — parse @include/@delegate/@ref directives, build graphs, and resolve templates for AI agent prompt engineering

dotmd-parser

日本語版 README はこちら

Dependency graph parser for .md skill files — built for AI agent prompt engineering with Claude Code and similar tools.

Why dotmd-parser?

As AI agent projects grow, SKILL.md files start referencing each other via @include and @delegate directives. Without tooling, you're left manually tracing dependencies to answer basic questions:

• "Which files break if I edit shared/role.md?"
• "Is there a circular reference hiding in my skill tree?"
• "What {{variables}} are still unresolved after expansion?"

dotmd-parser solves this by parsing your .md files into a dependency graph — automatically detecting directives, runtime references, and template placeholders. One function call gives you the full picture.

Comparison

Capability	Manual / grep	dotmd-parser
Find @include / @delegate references	grep -r "@include" — flat list, no context	Structured graph with node types and edge metadata
Detect circular references	Hope you notice before the agent loops	Automatic detection with full cycle path in warnings
Reverse dependency ("what breaks?")	Manually trace every file	dependents_of(graph, "shared/role.md") — one call
Expand @include to final text	Copy-paste by hand	resolve("SKILL.md", variables={...}) — recursive expansion
Find unresolved {{variables}}	grep "{{" *.md — noisy, no dedup	Deduplicated list per node and after expansion
Missing file detection	Runtime failure	Warnings at parse time with exact paths

Installation

pip install dotmd-parser

Quick Start

from dotmd_parser import build_graph, resolve, dependents_of, summary

build_graph — Build a dependency graph

graph = build_graph("./my-skill/")
# or from a specific file
graph = build_graph("./my-skill/SKILL.md")

Returns:

{
  "nodes": [
    {"id": "/abs/path/to/SKILL.md", "type": "skill", "missing": false, "placeholders": []}
  ],
  "edges": [
    {"from": "...", "to": "...", "type": "include", "parallel": false}
  ],
  "warnings": []
}

resolve — Expand @include directives

result = resolve("./prompts/main.md", variables={"name": "Alice"})

print(result["content"])       # Fully expanded text
print(result["placeholders"])  # Unresolved {{variable}} names
print(result["warnings"])      # Circular refs, missing files, etc.

dependents_of — Reverse dependency query

# "If I change shared/role.md, what else breaks?"
affected = dependents_of(graph, "/abs/path/to/shared/role.md")

summary — Human-readable overview

print(summary(graph))
# Nodes: 5  (agent:1, shared:2, skill:1, reference:1)
# Edges: 4  (include:3, read-ref:1)
# Warnings: 0

Supported Directives

Directive	Description
@include path/to/file.md	Inline expansion — file content is inserted at this position
@delegate path/to/agent.md	Agent delegation — recorded in graph but not expanded
@delegate path/to/agent.md --parallel	Parallel delegation with --parallel flag
@ref path/to/file.md	Runtime reference — recorded in graph but not expanded
Read `path/to/file.md`	Legacy runtime reference — same behavior as @ref (kept for backward compatibility)

CLI

# Installed as a command
dotmd-parser ./my-skill/

# Or via Python module
python -m dotmd_parser.parser ./my-skill/

Development

git clone https://github.com/dotmd-projects/dotmd-parser.git
cd dotmd-parser
pip install -e .
pip install pytest
pytest tests/ -v

License

MIT