terrylica/cc-skills

markdown-table-validator

Detect and fix Markdown (GFM) tables that won't render on GitHub or the VS Code preview — unescaped pipes inside cells, header/separator column-count mismatch, indented (code-block) tables, and misplaced alignment colons.

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/terrylica/cc-skills --skill markdown-table-validator

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

Markdown Table Validator

Scan Markdown files for the structural problems that silently demote a GFM table to a plain paragraph on GitHub / VS Code preview, and optionally auto-escape the single most common cause (an unescaped | inside a cell).

Self-Evolving Skill: This skill improves through use. If the detector misses a real broken-table case, the --fix heuristic guesses wrong, or a path/flag has drifted — fix this file (and the detector SSoT) immediately, don't defer. Only update for real, reproducible issues.

Why tables break (the one rule that matters)

GFM ignores whitespace between pipes, so alignment is never the cause. What breaks rendering is structure — overwhelmingly an unescaped `|` inside a cell. GFM's table tokenizer treats a | as a column delimiter even inside a `` `code span` ``, so a regex/code cell like ` a | b | c inflates that row's cell count and the whole table collapses. The fix — escaping it as \|` — changes meaning, so no formatter does it for you (Prettier actively corrupts such tables: prettier#10164 / #11410). This skill detects it and can apply the escape under review.

Quick start

bash
SCAN="$(cc-plugin-root doc-tools)/skills/markdown-table-validator/scripts/scan_markdown_tables.ts"

# Report problems in one file (exit 1 if any render-breaking error)
bun "$SCAN" path/to/FILE.md

# Audit a whole tree
bun "$SCAN" "docs/**/*.md" "plugins/**/*.md"

# Opt-in auto-fix: escape over-count pipes, then re-align with prettier
bun "$SCAN" --fix path/to/FILE.md
prettier --write path/to/FILE.md

What it detects

CodeSeverityMeaning
column-overflowerrorA row has more cells than the header → unescaped `\` in a cell.
header-mismatcherrorHeader and separator row have different column counts → won't render.
indented-tableerrorTable indented ≥4 spaces → parsed as a code block.
alignment-colon-in-rowerrorAn alignment token like :--: sits in a data row (misplaced separator).
short-rowinfoRow has too few cells; GFM pads and markdownlint --fix repairs.
missing-blank-lineinfoNo blank line before/after the table; the formatter auto-fixes.

Fenced code blocks ( ```) are skipped, so example broken tables shown inside docs don't trip the scan.

Output

Compiler-style path:line: severity: message [code]. Exit 0 when no error remains (info nits never fail the run), 1 otherwise — usable as a gate.

--fix heuristic (always review the diff)

For a row with more cells than the header, the genuine columns are assumed to be the first N; every pipe beyond column N is treated as literal content and escaped as \|. This exactly fixes the common case (regex/code in the last cell) but can guess wrong when a pipe was a genuinely missing delimiter — so review the diff, then run prettier --write to re-align.

Relationship to the automatic guard

This skill is the manual, repo-wide counterpart to the per-edit itp-hooks PostToolUse guard (posttooluse-markdown-table-guard.ts), which reminds Claude to fix the same errors the moment a .md file is written. Use the skill to clean existing docs in bulk; the hook prevents new breakage. Both share the same detection algorithm (SSoT: plugins/itp-hooks/hooks/lib/markdown-table-detector.ts).

Suppress the per-edit hook on a file by adding a comment containing MD-TABLE-OK.

References

  • algorithm.md — the detection algorithm + the pipe-escaping rationale.

Post-Execution Reflection

After this skill completes, reflect before closing the task:

  1. Locate yourself. — Find this SKILL.md's canonical path before editing.
  2. What failed? — A missed broken table or a false positive → fix the detector (markdown-table-detector.ts) and its mirror here.
  3. What worked better than expected? — Promote to recommended practice.
  4. What drifted? — Keep the self-contained scanner copy in parity with the itp-hooks detector SSoT.
  5. Log it. — Note the trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.

来自同一仓库

更多 Skills

全部 Skills
terrylica
社区

academic-pdf-to-gfm

Convert academic PDF papers to GitHub-renderable GFM markdown with math equations. TRIGGERS - PDF, GitHub markdown, math

1小时安装量
1
GitHub Stars
2
最近更新
11月5日
terrylica
社区

adr-code-traceability

Add ADR references to code for traceability. TRIGGERS - ADR traceability, code reference, document decision in code.

1小时安装量
1
GitHub Stars
2
最近更新
11月5日
terrylica
社区

arxiv-source-first-paper-ingest

Read an arXiv paper faithfully by fetching the authors' own LaTeX source instead of OCR-ing the PDF. Extracts every display equation with its label, environment and enclosing proposition, renders each to MathML, and proves usability by compiling each formula with a real TeX engine. Use when you need a paper's formulas exactly — to replicate a method, implement a loss function or custom objective, verify a quoted number, or check a claim against what the authors actually wrote. TRIGGERS - read th

1小时安装量
1
GitHub Stars
2
最近更新
11月5日
terrylica
社区

azure-provision

Bootstrap Azure automation when interactive az login is blocked by a Conditional Access policy (error 530035, "Device state: Unregistered"). Mints a service principal through the Azure Portal session ONCE — using Microsoft Graph over a captured token, not DOM clicking — then provisions resource groups, Cognitive Services / AI Language / Speech resources and their keys entirely via az/REST, writing key AND endpoint together into the SCS vault. Use when az login fails but the portal works, when mo

1小时安装量
1
GitHub Stars
2
最近更新
11月5日