Agent Skills › nubjs/nub › md-toc

md-toc

GitHub

用于高效导航大型Markdown文件。通过生成包含精确行范围的目录(TOC)，避免加载全文，利用Read工具的offset和limit参数精准读取指定章节，适用于长文档、状态追踪等场景。

.claude/skills/md-toc/SKILL.md nubjs/nub

触发场景

需要阅读大型Markdown文件的特定章节处理超过200行的Markdown文档

安装

npx skills add nubjs/nub --skill md-toc -g -y

更多选项

非标准路径

npx skills add https://github.com/nubjs/nub/tree/main/.claude/skills/md-toc -g -y

不安装直接使用

npx skills use nubjs/nub@md-toc

指定 Agent (Claude Code)

npx skills add nubjs/nub --skill md-toc -a claude-code -g -y

安装 repo 全部 skill

npx skills add nubjs/nub --all -g -y

预览 repo 内 skill

npx skills add nubjs/nub --list

SKILL.md

Frontmatter

{
    "name": "md-toc",
    "version": "1.0.0",
    "metadata": {
        "internal": true
    },
    "description": "Navigate large markdown files efficiently — get a complete heading TOC with exact line ranges, then Read only the section you need instead of loading the whole file."
}

md-toc — markdown navigation via line ranges

When a markdown file is large (>200 lines), don't Read the whole thing. Run the TOC script first to see every heading and its section's line range, then use Read with offset + limit to jump straight to the section you need.

Invocation

node scripts/md-toc/index.mjs <file.md>
# or equivalently:
nub scripts/md-toc/index.mjs <file.md>

Output format

One line per heading, indented by depth, with the section's line range:

L1-402    # Nub — Final-Polish Orchestration Tracker
L152-192    ## Status board
L282-367    ## Item cards
L284-292      ### A — Settle/verify env-plumbing  ·  todo

The range L152-192 means the "Status board" section occupies lines 152–192. To read it:

Read(file, offset=152, limit=41)   # limit = end - start + 1

A heading's section spans from its own line to just before the next heading of equal or higher level (or EOF). # lines inside fenced code blocks are correctly ignored (uses a real markdown AST parser, not regex).

When to use

Any file >200 lines where you need one section, not the whole file.
HANDOFF/STATUS trackers, AGENTS.md, architecture docs, long epics.
Before dispatching a sub-agent that needs a slice of a large doc — run the TOC yourself, embed the relevant offset/limit in the prompt so the agent Reads precisely.