# Changelog Narrator

> Compare two document versions and produce a structured changelog — no git needed. Use for PRDs, SOPs, contracts, strategy docs. Triggers: 'compare these two documents', 'what changed between versions', 'generate a changelog', 'сравни две версии документа', 'что изменилось', 'сделай changelog'.

- **Type:** Skill
- **Install:** `agentstack add skill-kirkruglov-claude-skills-kit-changelog-narrator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [KirKruglov](https://agentstack.voostack.com/s/kirkruglov)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [KirKruglov](https://github.com/KirKruglov)
- **Source:** https://github.com/KirKruglov/claude-skills-kit/tree/main/skills/changelog-narrator

## Install

```sh
agentstack add skill-kirkruglov-claude-skills-kit-changelog-narrator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Changelog Narrator

This skill compares two versions of a business document and produces a structured, human-readable changelog — without git, CLI, or "Track Changes". Designed for non-technical users who receive updated drafts and need to understand what changed at a glance.

**Input:**
- Two local files (`.md` or `.txt`) in the Cowork workspace — old version (v1) and new version (v2)
- Optional: version labels if filenames are ambiguous; optional focus area (e.g., "only compare Section 3")

**Output:**
- Markdown changelog: Summary → Added → Removed → Modified → Notes

---

## Language Detection

Detect the user's language from their message:
- If Russian (or contains Cyrillic): respond in Russian
- If English (or other Latin-script language): respond in English
- If ambiguous: respond in the language of the trigger phrase used

---

## Instructions

### Step 1: Identify and Validate Files

1. Check that exactly two files are provided
   - If only one file is given: stop — "Two documents are required. Please provide both the old version (v1) and the new version (v2)."
   - If no files are given: scan the Cowork workspace for `.md` and `.txt` files; list them and ask the user to specify which two to compare

2. Read both files
   - If a file is unreadable (binary, corrupted, unsupported format): stop — "Could not read [filename]. changelog-narrator works with .md and .txt files only."

3. Determine version order (which is v1, which is v2)
   - Infer from filename markers: `v1`/`v2`, `old`/`new`, `draft`/`final`, date suffixes (earlier date = v1)
   - If version order is ambiguous (e.g., `strategy-a.md` vs `strategy-b.md`): ask — "Which file is the older version?" — do not guess

### Step 2: Split Documents into Comparable Units

1. Segment each document into logical units:
   - H1/H2/H3 headings → use as section labels
   - Paragraphs under each heading → compare as blocks
   - Numbered or bulleted list items → compare as individual items
   - Table rows → compare row by row

2. Build a section map for each document:
   - Key: section heading (or "Intro" for content before the first heading)
   - Value: list of content units under that heading

3. If user specified a focus area (e.g., "only Section 3" or "only the Risks section"):
   - Filter both maps to matching section only
   - Note in output: "Comparison limited to: [Section Name]"

### Step 3: Compare and Classify Changes

1. Align sections by heading label across v1 and v2
2. For each content unit, classify:
   - **Added**: present in v2 but absent in v1
   - **Removed**: present in v1 but absent in v2
   - **Modified**: present in both, but content differs
   - **Unchanged**: identical in both → do NOT include in output

3. For **Modified** items:
   - Describe the change briefly: what was the key shift? (e.g., "Timeline changed from Q2 to Q3", "Metric updated from 10% to 15%", "Scope narrowed from 5 to 3 segments")
   - Do NOT reprint full paragraphs from both versions
   - If the change is structural (section renamed, split, merged): flag as Modified with note "Section restructured"

4. For tables:
   - Compare rows as discrete units — flag each added/removed/modified row individually
   - Do not collapse entire table into a single "Modified" entry

**Edge Cases:**
- Files are identical: output "No changes detected between [v1] and [v2]." Do not produce an empty changelog.
- Section exists in v2 but not in v1 → entire section is Added
- Section exists in v1 but not in v2 → entire section is Removed

### Step 4: Write Summary

Write 2–3 sentences capturing:
- Overall scope of changes (how many sections affected, what type of changes dominate)
- The apparent intent behind the changes (e.g., "Scope was narrowed", "Risks section significantly expanded", "Timelines shifted across the board")
- Avoid generic statements — reference specific sections or patterns

### Step 5: Format and Output Changelog

1. Assemble the changelog using the Output Format structure below
2. Populate each section: Added, Removed, Modified — each with N (count)
3. Skip any section with 0 entries (e.g., if nothing was removed, omit "Removed")
4. Add Notes section for all assumptions about version order, skipped content, focus-area limitations, table handling

---

## Negative Cases

- **Only one file provided:** Stop — "Two documents are required. Please provide both the old version (v1) and the new version (v2)."
- **No files found in workspace:** Stop — "No files found. Please upload your document versions or confirm they're in the selected Cowork folder, then try again."
- **File is binary/unreadable:** Stop — "Could not read [filename]. changelog-narrator works with .md and .txt files only."
- **More than two files provided:** Clarify — "I can compare two versions at a time. Please specify which two to compare first. You can run the skill again for additional pairs."
- **User asks for visual/side-by-side diff:** Explain — "I produce a structured text changelog. For a visual side-by-side diff, paste both files into a tool like Diffchecker.com."

---

## Output Format

```markdown
## Changelog: [Document Title] — [v1 filename] → [v2 filename]

**Compared:** `[filename-v1]` vs `[filename-v2]`
**Date:** [YYYY-MM-DD]

### Summary
[2–3 sentences: overall scope and intent of changes — specific sections and patterns, not generic phrasing]

---

### Added (N)

- **[Section / Heading]:** [Brief description of what was added]
- **[Section / Heading]:** [Brief description of what was added]

### Removed (N)

- **[Section / Heading]:** [Brief description of what was removed]

### Modified (N)

- **[Section / Heading]:** [Key change — e.g., "Timeline extended from Q2 to Q3"; "Success metric changed from 10% to 15% retention"]
- **[Section / Heading → Sub-item]:** [Brief description]

---

### Notes
- [Assumption: e.g., "Treated `strategy-a.md` as v1 based on earlier file modification date"]
- [Flag: e.g., "Table in Section 4 had 3 rows added — listed under Added separately"]
- [Scope note: e.g., "Comparison limited to Section 3 as requested"]
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [KirKruglov](https://github.com/KirKruglov)
- **Source:** [KirKruglov/claude-skills-kit](https://github.com/KirKruglov/claude-skills-kit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kirkruglov-claude-skills-kit-changelog-narrator
- Seller: https://agentstack.voostack.com/s/kirkruglov
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.