gpsaggese/helpers / .claude/skills/markdown.summarize
markdown.summarize
VerifiedSummarize markdown content into bullet points while preserving header structure
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.3 KB |
| example.md | markdown | 3.0 KB |
SKILL.md
View on GitHub---
description: Summarize markdown content into bullet points while preserving header structure
model: sonnet
---
# 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:
```markdown
<!-- 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
```markdown
# <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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |