跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
其他技能

scannable-docs

Format technical and reference writing so it scans fast and stays dense — tables for data, bullets for discrete items, short paragraphs for context, top-down diagrams for flow. Use when writing or restyling a spec, schema, README, project note, reference note, or comparison, or when asked for something "scannable", "dense", or "tables and lists".

pborenstein · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add pborenstein/handoff --skill scannable-docs

技能说明


name: scannable-docs description: Format technical and reference writing so it scans fast and stays dense — tables for data, bullets for discrete items, short paragraphs for context, top-down diagrams for flow. Use when writing or restyling a spec, schema, README, project note, reference note, or comparison, or when asked for something "scannable", "dense", or "tables and lists". compatibility: Designed for Claude Code with filesystem access allowed-tools: Bash, Read, Edit, Write, Glob, Grep

Scannable Docs

A reader should find any fact in a few seconds, and nothing on the page should be filler. Form follows the shape of the content: data goes in tables, discrete items in lists, reasoning in short paragraphs.

Adapted from Technical Documentation Principles, written before current models. The principles hold; this version adds the formatting habits models now overproduce.

Scope

Use it for specs, schemas, READMEs, project notes, reference notes, comparisons, and how-tos.

Do not use it for writing that has its own voice: essays, personal notes, narrative memos, or conversational replies. Another skill or the author's own prose sets their form.

Choose the form

ContentFormTest
Items that share attributes: fields, options, commands, comparisonsTableCan you name the columns?
Discrete items with nothing in common to tabulate: caveats, open itemsBulleted listWould they read naturally as a list aloud?
Steps where order mattersNumbered listDoes step 3 fail if done before step 2?
Context, reasoning, transitionsParagraph of 1–3 short sentencesDoes each sentence depend on the one before?
Flow, dependency, hierarchyDiagram, top-downAre there arrows in your head?
Exact syntax someone will copyCode blockWould anyone paste it?

When content fits two forms, prefer the denser one that still reads without effort. Three trivial label-value bullets are a sentence, not a table.

Tables

  • Left-align every column: |:-----|:-----|.
  • The first column is the key (name, term, field), and rows are in a meaningful order: by sequence, by importance, or alphabetical.
  • Column headers are descriptive nouns: "Command", not "Syntax"; "Meaning", not "Info".
  • Every cell carries information. Drop a column that is mostly blank, —, or a restatement of the first column.
  • Cells hold phrases, not paragraphs. A cell that needs two sentences means the content wants prose or its own section.
  • Split a table past about 12 rows, or one mixing kinds of rows, into several tables under ### subheadings. Parallel tables use identical headers.
  • Identifiers, paths, and values in backticks. No bold inside cells.

Lists

  • A blank line before every list (CommonMark and Obsidian both need it).
  • Parallel grammar: every item starts the same way (all verbs, or all nouns).
  • One level of nesting at most. Deeper nesting is a table or a new section.
  • No bold label at the start of an item (- **Speed:** fast). If items have labels, they have attributes: make a table. Otherwise write the item as a plain sentence.

Headings

  • No skipped levels: ## then ###, never ## then ####.
  • No wrapper heading with one child. Remove the intermediate level.
  • Parallel sections use the same heading level and the same internal structure.
  • A heading names its content as a noun phrase. "Dates", "Layer types", "Open decisions" — not "Overview", "Details", or "Key takeaways".
  • No bold line standing in for a heading (**Usage:** alone on a line). Use a real heading, or fold it into the sentence that follows.

Prose

  • Short sentences, one idea each.
  • Describe mechanisms and measurable facts, not quality: what it does, not how impressive it is.
  • Use the same term for the same thing everywhere. Define a term once, at first use.
  • No opening paragraph that restates the title, and no closing summary. The document is the summary.
  • No signposting ("It's worth noting", "Let's look at"), no stacked hedges ("may potentially"), no rhythm triplets ("fast, simple, and reliable") unless each item is measured.
  • No jargon: leverage, utilize, robust, seamless, powerful, elegant, sophisticated, innovative, comprehensive.
  • No emoji. No em-dash chains that string three clauses together; split them into sentences.

Diagrams

  • ASCII boxes and arrows, drawn top-down, for pipelines, data flow, and relationships between records.
  • Label arrows with the relation name when it is not obvious.
  • Keep a diagram under about 20 lines. A larger one is two diagrams.
  • Mermaid flowchart TD is acceptable when the target renders it (Obsidian does); ASCII renders everywhere.

Code and examples

  • Several commands become a table: Task | Command | Result.
  • A full example stays whole when it is the substance, such as a complete schema record. Do not trim it to fit a table.
  • One code block per language per example; label the language on the fence.

Docs about a codebase

  • Open with one paragraph on what it does and for whom.
  • Mention supporting files (sample data, fixtures) in context, not as top-level sections.
  • Do not treat agent configuration files as content sources: CLAUDE.md, AGENTS.md, GEMINI.md, SKILL.md, .claude/, .cursor/. They are written for models, not readers.

Workflow

  1. Read the source material, or the existing document if restyling.

  2. Sort the content by shape using the form table above, before writing anything.

  3. Write the document.

  4. Run the checker and fix what it reports:

    python3 <this skill's directory>/scripts/scannable_check.py "path/to/doc.md"
    

    It flags bold-label bullets, pseudo-headings, non-left-aligned tables, skipped heading levels, lists without a blank line before them, emoji, and banned jargon. It skips YAML frontmatter and code fences. It is a report; it never edits the file.

  5. Read it once

阅读完整来源 ↗