markdown-summarize

Summarize markdown content into bullet points while preserving header structure

SKILL.md

GitHub

Interface Specification

Inputs

Parameter Type Required Description
<INPUT> file path or text Yes Markdown file or text chunk to summarize
<NUM_WORDS> integer No* Target output word count
<FRACTION> float (0-1) No* Alternative to <NUM_WORDS>: fraction of original size
<MAX_HEADER_LEV> integer No Max header level to preserve (default: preserve all levels)
<TAG> string No Tag for output filename (default: derived from input)
  • Exactly one of <NUM_WORDS> or <FRACTION> must be specified.

Outputs

Item Format Description
Console output Text Header structure preview + summary + statistics
Output file Markdown explanation.<tag>.md (overwrites if exists)
Word count Integer Original and target word counts printed to console
  • Say in the output file how it was generated, with this comment at the top:
    <!-- Generated by `.claude/skills/markdown.summarize/SKILL.md` -->
    

Workflow

Parse Input

  • Read the file at <INPUT>
  • Extract headers using markdown syntax (#, ##, ###, etc.)

Determine Header Strategy

Case A: Input has header structure

  • Extract all headers and print the structure to console

Case B: Input is plain text (no headers)

  • Skip header extraction. Summarize directly

Apply Header Level Filter

If <MAX_HEADER_LEV> not specified:

  • Preserve all header levels from the original

If <MAX_HEADER_LEV> specified:

  • Keep only headers with level <= <MAX_HEADER_LEV>
  • Summarize each deeper section into chunks (see "Group Into Chunks")
    • Each collapsed section becomes a chunk titled after its header text (shortened if needed)
    • Headers nested inside a collapsed section become sub-bullets

For every header kept (header fidelity):

  • Copy the header line verbatim: same # level, text, numbering, and order
    • Do not rename, reword, re-case, renumber, or add numbers to it
    • Keep gaps and duplicates in the source numbering
  • Do not add, merge, split, or reorder headers. Only headers deeper than <MAX_HEADER_LEV> are removed
  • Header fidelity wins over the header rules of markdown.rules.md and text.rules.md (e.g., starting at level 1, capitalizing major words, numbering in order)

Calculate Target Length

  • Count the original word count as <ORIG_NUM_WORDS>
  • If <FRACTION> is given: <TARGET_WORDS> = <ORIG_NUM_WORDS> x <FRACTION>
  • If <NUM_WORDS> is given: <TARGET_WORDS> = <NUM_WORDS>

Summarize Content

  • Convert to chunks of nested bullets. See "Group Into Chunks" and "Compress Content" below
  • Follow .claude/skills/markdown.rules.md and .claude/skills/text.rules.md
    • If they conflict with the chunk format, the chunk format wins (e.g., the ## chunk titles in "Example 2" of text.rules.md)
  • Constraints:
    • Convert all mathematical formulas to LaTeX
    • Wrap text at 85 columns
    • Hit <TARGET_WORDS> within 10% tolerance
    • Preserve key concepts and important details

Group Into Chunks

  • Split the content under each preserved header into chunks of related content
    • If the input has no headers, split the whole text into chunks
  • Start each chunk with a title line * <TITLE>, with no leading spaces
    • Put the bullets directly under the title, with no blank line in between
    • Separate chunks with one blank line
    • Do not write bullets outside a chunk
  • A chunk:
    • Covers one topic or idea
    • Has typically 2-5 first-level bullets
    • Follows the order of the source
  • Start a new chunk when the topic changes
    • E.g., from a definition, to why it matters, to its uses, to an example
  • Rules for <TITLE> (same as slide titles in slides.rules.md):
    • Short noun phrase, 2-6 words, in sentence case
    • Names the topic or the claim, not its role
      • Bad: * Overview, * Details, * Point 2
      • Good: * Culture > strategy
    • Use > to express priority or comparison
    • Use : <qualifier> for a variant of an earlier chunk's topic
      • E.g., * Core values: EOS Worldwide example
    • No numbering, no trailing punctuation, ASCII only
    • Unique within its section
  • Use # only for headers in the source, with their source numbers
    • * chunk titles are never numbered

Compress Content

  • Keep:
    • Definitions and claims
    • Enumerations (e.g., the list of values)
    • Cause-effect relations (e.g., culture wins in the long term)
    • The few concrete examples that clarify a claim
  • Drop:
    • Quotes and attributions
    • Cross-references and links (e.g., "see Chapter 8")
    • Rhetorical asides and hedges
    • Exhortations and motivational closing paragraphs
    • Restatements of a claim that a bullet already captures
  • Write bullets as fragments, not full sentences:
    • Omit the subject when the chunk title already names it
      • E.g., under * Core values, write Define the culture, not Core Values define the culture
    • Do not end a bullet with a period
    • If one sentence makes several claims about one subject, use the subject as a parent bullet and one sub-bullet per claim
      • E.g., A Company with sub-bullets Needs to know who it is and Is defined by the Core Values
  • Turn an enumeration into one flat bullet list, in source order
    • Applies to numbered, bold-numbered, and inline lists
    • Drop the numbers and the bold
  • If the source explains one list item at length, put 2-3 sub-bullets under it
    • Use E.g., to introduce a concrete example
    • Use : to join a statement and its explanation
  • Use .claude/skills/markdown.summarize/example.md as the reference
    • It compresses 351 words into 108 (about 31%), not counting the header
    • The 2 closing paragraphs of the input are dropped completely
    • The exact target length comes from <TARGET_WORDS>, not from the example

Output Results

  • Print statistics: <ORIG_NUM_WORDS> compared to the actual output word count
  • Write explanation.<tag>.md (overwrite if it exists)

Interactive Follow-up

  • Wait for user questions
  • Answer questions that reference specific sections of the summary

Behavior Specifications

Header Fidelity

  • Output headers are identical to the source headers
    • Source numbered, output numbered the same way
      • Bad: source # 2. Methods, output # 1. Methods
      • Good: source # 2. Methods, output # 2. Methods
    • Source not numbered, output not numbered
      • Bad: source ## Data, output ## 1.1. Data
      • Good: source ## Data, output ## Data
    • Source # 2. Methods, ## 2.1. Data, # 4. Results
      • Output keeps 2., 2.1., and 4. (it does not renumber 4. to 3.)

Chunk Format

# <Header copied from source>

* First chunk title
- Main point
  - Supporting detail
  - Supporting detail
- Main point

* Second chunk title
- Main point

Edge Cases

Condition Behavior
No headers in input Summarize into * <TITLE> chunks, no H1/H2 in output
<MAX_HEADER_LEV> = 1 Collapse all H2+ into * <TITLE> chunks under H1
<MAX_HEADER_LEV> > deepest level Preserve all headers as-is
Source headers are not numbered Output headers are not numbered
Source numbering has gaps or duplicates Copy the numbers as they are
Section with a single topic Emit a single chunk
Empty input Return error message
Very short input Return minimal summary maintaining structure

Verification

  • Output word count is close to <TARGET_WORDS> (within 10%)
  • Every kept header matches the source: same level, text, number, and order
    • E.g., compare the lines starting with # in the input and output, ignoring fenced code blocks
  • Headers removed only if deeper than <MAX_HEADER_LEV>
  • All key information extracted into bullet points
  • Every bullet sits under a * <TITLE> chunk title
  • The output file says that it was generated by .claude/skills/markdown.summarize/SKILL.md
  • Chunk titles are 2-6 word noun phrases, in sentence case, unnumbered
  • Quotes, cross-references, and rhetorical filler are dropped
  • Text wrapped at 85 columns
  • File written successfully
  • User can ask follow-up questions