菜单
Provides deterministic primitives for restructuring markdown documents with 100% reliability and coverage verification.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | doc-restructure |
| description | Provides deterministic primitives for restructuring markdown documents with 100% reliability and coverage verification. |
This skill provides deterministic, LLM-free primitives for extracting and restructuring markdown documents with guaranteed coverage. Unlike LLM-based approaches, these functions provide bit-exact extraction and verification capabilities.
For complex transformations, don't do interactive work—build a harness.
An agent harness is a small, purpose-built system that wraps your work with:
Instead of doing 50 interactive edits, build a harness that:
Example pattern:
# harness.py - one-off script for this job
from pathlib import Path
from doc_restructure import iter_headings, coverage_check
CONFIG = [
{"file": "doc1.md", "expected_sections": ["Intro", "Method", "Results"]},
{"file": "doc2.md", "expected_sections": ["Overview", "Details"]},
]
def transform_one(path, expected):
content = path.read_text()
# Use skill primitives here
headings = {h.title for h in iter_headings(content, levels=(2,))}
# Verify
missing = coverage_check(content, set(expected))["missing"]
if missing:
raise ValueError(f"Missing sections: {missing}")
# Transform...
for cfg in CONFIG:
transform_one(Path(cfg["file"]), cfg["expected_sections"])
Why this beats pure interactive work:
Don't overengineer, but don't shy away from code either.
For complex bulk operations, use the right tool:
Example - bulk fix broken links:
grep -r "old-section-name" --include="*.md" -l
Example - extract all URLs from multiple files:
from pathlib import Path
from doc_restructure import body_urls
for md in Path("docs").glob("**/*.md"):
urls = body_urls(md.read_text())
print(f"{md}: {len(urls)} URLs")
When localizing Russian docs, transform US number formats:
1,415.2 → 1 415,2 (thousands: comma→space, decimal: dot→comma)300,000,000 → 300 000 0003.97-10.68 → 3,97–10,68 (ranges with en dash)Key challenge: Distinguish "real numbers" from "version strings":
GLM-4.6, GPT-5.4, HuggingFace path, 0.6B (model names)Harness approach:
# 1) Define safe patterns to EXCLUDE (versions, paths, dates)
VERSION_LIKE = re.compile(r'(?:GLM|GPT|YandexGPT|Claude)[-.\s]\d|^\d+[A-Z]|huggingface\.co|\d{2}\.\d{2}\.\d{4}')
# 2) Transform only safe contexts (table cells, currency, measurements)
# 3) Run and verify no regressions (check model names still work)
# 4) Manual review pass for edge cases
Yield heading occurrences outside fenced code blocks.
Returns: Iterable of HeadingOccurrence objects with:
level: inttitle: str (normalized)start_line: int (0-based inclusive)end_line: int (0-based exclusive)Extract a verbatim section starting at the first matching heading.
Returns: Tuple of (section_text, start_line, end_line_exclusive)
Verify that all headings in the document are accounted for.
Returns: Dict with "covered", "missing", "extra" lists
Create a safe filename slug from a heading title.
Extract all H2 section ranges.
Returns: List of (title, start_line, end_line) tuples
Strip trailing punctuation from URLs.
Extract all URLs from markdown (markdown links + bare URLs).
Returns: Dict mapping URL -> preferred label
Extract URLs from Sources section (- [label](url) format).
Returns: Set of URLs
Suggest category heading based on URL domain.
Audit links between body and sources.
Returns: Dict with "covered", "missing", "extra" URL lists
Add markdown anchor links to all headings.
Example: ## My Section → ## My Section {: #my-section }
Strip YAML front matter from markdown.
Returns: Tuple of (front_matter, body)
Add YAML front matter to markdown body.
Extract headings with IAL (Kramdown) syntax: ## Title {: #anchor-id }
Returns: List of dicts with level, title, anchor_id, line_number
Apply anchor ID remapping to markdown.
Example: {: #old_id } → {: #new_id }
Find broken cross-references (links to non-existent anchors).
Returns: List of dicts with fragment, line_number, context
Create URL-safe slug from heading title (ASCII-only).
Demote headings by one level outside fenced code blocks.
Example: ## H2 → ### H3
Promote headings by one level outside fenced code blocks.
Example: ### H3 → ## H2
Extract the first H1 heading from markdown.
Returns: H1 title without # prefix, or None
Create anchor-friendly slug (keeps Cyrillic).
Combine multiple markdown files into one document.
Each file becomes an H2 section, headings inside are demoted by one level.
Extract all HTTP/HTTPS URLs from text.
Returns: Set of normalized URLs
Parse sections at given level into ordered buckets with URLs.
Returns: Dict: section_title -> {anchor, urls: {url: info}}
Deduplicate URLs - each URL appears in exactly one section.
Useful for merging source lists.
Find URLs appearing more than once in a section.
Returns: List of duplicate URLs
import sys
sys.path.insert(0, 'skills/doc-restructure')
from doc_restructure.scripts import (
iter_headings,
extract_section_by_heading,
coverage_check,
make_safe_slug,
extract_all_h2_section_ranges,
body_urls,
sources_urls,
audit_links,
)
# Extract all H2 headings from a document
headings = list(iter_headings(document_md, levels=(2,)))
# Extract a specific section
section_content, start, end = extract_section_by_heading(
document_md,
heading_title="Methodology Overview",
heading_level=2
)
# Verify coverage
mapped_titles = {"Methodology Overview", "Implementation Details", "Results"}
coverage = coverage_check(document_md, mapped_titles)
if coverage["missing"]:
print(f"Unmapped headings: {coverage['missing']}")
# Audit links in document with Sources section
if "## Sources" in document_md:
body, sources = document_md.split("## Sources", 1)
link_audit = audit_links(body, sources)
print(f"Missing from sources: {link_audit['missing']}")
This skill intentionally avoids:
Agents orchestrate the workflow using these primitives + ad-hoc harnesses, maintaining full control over: