Change Walkthrough

Name: Change Walkthrough
Author: sawyerhood

sawyerhood/sawyer-mart

5 installs
70 repo stars
Updated January 12, 2026
sawyerhood/sawyer-mart

Helps with ai & agent building tasks.

About

change-walkthrough is a Claude Code skill for ai & agent building. It helps solo builders move faster with AI-assisted development.

change-walkthrough
AI & Agent Building
AI-coding skill

Change Walkthrough by the numbers

5 all-time installs (skills.sh)
Ranked #13,065 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
Data as of Aug 5, 2026 (Skillselion catalog sync)

npx skills add https://github.com/sawyerhood/sawyer-mart --skill change-walkthrough

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/sawyerhood/sawyer-mart/change-walkthrough.svg)](https://skillselion.com/skills/sawyerhood/sawyer-mart/change-walkthrough)

Installs	5
repo stars	★ 70
Last updated	January 12, 2026
Repository	sawyerhood/sawyer-mart ↗

What it does

Helps with ai & agent building tasks.

Files

SKILL.mdMarkdownGitHub ↗

Change Walkthrough

Generate a detailed, well-formatted markdown walkthrough of code changes with automatic HTML conversion and browser preview.

Workflow

1. Understand What Changes to Review

Ask or determine what changes the user wants documented:

Uncommitted changes (default): All changes in working directory
Staged changes: Only changes added to staging area
Recent commits: Last N commits
Commit range: Specific range (e.g., "abc123..def456")
Branch comparison: Diff between branches
Specific files: Only certain files or directories

If not specified, default to uncommitted changes.

2. Gather Change Information

Based on the scope, run appropriate git commands:

# Uncommitted changes
git diff --stat && git diff

# Staged changes
git diff --staged --stat && git diff --staged

# Last N commits
git log --oneline -n N && git diff HEAD~N..HEAD

# Branch comparison
git diff main..HEAD --stat && git diff main..HEAD

Also gather context by reading changed files to understand the full picture.

3. Generate the Walkthrough Document

Create a comprehensive markdown document:

# Change Walkthrough: {Descriptive Title}

**Date:** YYYY-MM-DD
**Scope:** {uncommitted/staged/commits/etc}
**Total Files:** N files changed (+additions/-deletions)

## Summary

{2-3 sentence overview explaining what changed and why}

## Files Changed

| File | Changes | Description |
|------|---------|-------------|
| `path/to/file.ts` | +15/-3 | Brief description |

## Detailed Walkthrough

### {Feature or Component Name}

#### `path/to/file.ts:10-25`

**What changed:** {Explanation}

\`\`\`typescript
// Code snippet with syntax highlighting
\`\`\`

**Why:** {Reasoning behind this change}

## Testing Notes

- {What should be tested}
- {Potential edge cases}

---
*Generated by change-walkthrough skill*

4. Generate Filename

Create a descriptive filename based on the changes:

1. Extract key terms from files changed or commit messages 2. Format as kebab-case: {action}-{subject}-{YYYY-MM-DD}.md

Examples:

add-user-authentication-2025-12-22.md
fix-login-validation-2025-12-22.md
refactor-database-queries-2025-12-22.md

5. Write the Markdown File

Write the walkthrough to the skill's tmp directory. All generated files should be stored within the skill folder, not in the user's project directory.

The skill's base directory is shown at the top when the skill loads as "Base directory for this skill: ...". Use this path to construct the output location:

{SKILL_BASE_DIR}/tmp/{filename}.md

Write the generated markdown using the absolute path to the skill's tmp directory.

6. Install Dependencies and Convert to HTML

The conversion script requires npm dependencies. Run all commands from the skill's base directory (shown at the top when the skill loads as "Base directory for this skill: ...").

# Change to skill directory and install dependencies (only needed once per cache)
cd {SKILL_BASE_DIR} && npm install

# Convert markdown to HTML (use ABSOLUTE paths for input/output)
node scripts/md-to-html.js {SKILL_BASE_DIR}/tmp/{filename}.md

# Open in default browser
open {SKILL_BASE_DIR}/tmp/{filename}.html

Replace {SKILL_BASE_DIR} with the skill's base directory path. The script accepts absolute paths for the input file and automatically creates the .html file alongside it in the skill's tmp directory.

Report to the user the paths to both files and confirm the browser opened.

Notes

Use syntax highlighting with language specification in code blocks
Include file:line references for specific code locations
Group related changes together in the walkthrough
For extensive changes, organize by feature rather than by file

{
  "name": "change-walkthrough",
  "version": "1.0.0",
  "description": "Markdown to HTML converter for change walkthroughs",
  "type": "module",
  "scripts": {
    "convert": "node scripts/md-to-html.js"
  },
  "dependencies": {
    "marked": "^15.0.0",
    "marked-highlight": "^2.2.0",
    "highlight.js": "^11.10.0"
  }
}

#!/usr/bin/env node
/**
 * Markdown to HTML converter with syntax highlighting.
 *
 * Usage: node md-to-html.js <input.md> [output.html]
 * If output is not specified, creates <input>.html alongside the input file.
 */

import { readFileSync, writeFileSync } from 'fs';
import { basename, dirname, join } from 'path';
import { Marked } from 'marked';
import { markedHighlight } from 'marked-highlight';
import hljs from 'highlight.js';

const HTML_TEMPLATE = `<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Change Walkthrough</title>
    <style>
        :root {
            --bg: #fafafa;
            --text: #333;
            --heading: #2c3e50;
            --heading-border: #3498db;
            --code-bg: #2d3748;
            --code-text: #e2e8f0;
            --inline-code-bg: #edf2f7;
            --inline-code-text: #e53e3e;
            --table-border: #ddd;
            --table-alt: #f9f9f9;
            --blockquote-border: #3498db;
            --blockquote-bg: #f0f7ff;
        }

        @media (prefers-color-scheme: dark) {
            :root {
                --bg: #1a202c;
                --text: #e2e8f0;
                --heading: #90cdf4;
                --heading-border: #4299e1;
                --code-bg: #2d3748;
                --code-text: #e2e8f0;
                --inline-code-bg: #4a5568;
                --inline-code-text: #fc8181;
                --table-border: #4a5568;
                --table-alt: #2d3748;
                --blockquote-border: #4299e1;
                --blockquote-bg: #2a4365;
            }
        }

        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
            line-height: 1.6;
            max-width: 900px;
            margin: 0 auto;
            padding: 2rem;
            color: var(--text);
            background: var(--bg);
        }

        h1 {
            color: var(--heading);
            border-bottom: 2px solid var(--heading-border);
            padding-bottom: 0.5rem;
        }
        h2 { color: var(--heading); margin-top: 2rem; }
        h3 { color: var(--heading); opacity: 0.9; }
        h4 { color: var(--heading); opacity: 0.8; font-family: monospace; }

        pre {
            background: var(--code-bg);
            color: var(--code-text);
            padding: 1rem;
            border-radius: 8px;
            overflow-x: auto;
        }
        code {
            font-family: 'SF Mono', Monaco, 'Courier New', monospace;
            font-size: 0.9em;
        }
        p code, li code, td code {
            background: var(--inline-code-bg);
            padding: 0.2em 0.4em;
            border-radius: 4px;
            color: var(--inline-code-text);
        }
        pre code {
            background: none;
            padding: 0;
            color: inherit;
        }

        table {
            border-collapse: collapse;
            width: 100%;
            margin: 1rem 0;
        }
        th, td {
            border: 1px solid var(--table-border);
            padding: 0.75rem;
            text-align: left;
        }
        th { background: var(--table-alt); }
        tr:nth-child(even) { background: var(--table-alt); }

        ul, ol { padding-left: 1.5rem; }
        li { margin: 0.5rem 0; }

        blockquote {
            border-left: 4px solid var(--blockquote-border);
            margin: 1rem 0;
            padding: 0.5rem 1rem;
            background: var(--blockquote-bg);
        }

        hr {
            border: none;
            border-top: 1px solid var(--table-border);
            margin: 2rem 0;
        }

        /* highlight.js theme overrides for dark code blocks */
        .hljs { background: var(--code-bg); color: var(--code-text); }
        .hljs-keyword, .hljs-selector-tag, .hljs-built_in { color: #ff79c6; }
        .hljs-string, .hljs-attr { color: #f1fa8c; }
        .hljs-comment, .hljs-quote { color: #6272a4; font-style: italic; }
        .hljs-variable, .hljs-template-variable { color: #f8f8f2; }
        .hljs-number, .hljs-literal { color: #bd93f9; }
        .hljs-function, .hljs-title { color: #50fa7b; }
        .hljs-type, .hljs-class { color: #8be9fd; }
        .hljs-symbol, .hljs-bullet { color: #ffb86c; }
        .hljs-name, .hljs-tag { color: #ff79c6; }
    </style>
</head>
<body>
{{BODY}}
</body>
</html>`;

function main() {
    const args = process.argv.slice(2);

    if (args.length < 1) {
        console.error('Usage: node md-to-html.js <input.md> [output.html]');
        process.exit(1);
    }

    const inputPath = args[0];
    const outputPath = args[1] || inputPath.replace(/\.md$/, '.html');

    let mdContent;
    try {
        mdContent = readFileSync(inputPath, 'utf-8');
    } catch (err) {
        console.error(`Error: Cannot read file: ${inputPath}`);
        process.exit(1);
    }

    // Configure marked with syntax highlighting
    const marked = new Marked(
        markedHighlight({
            langPrefix: 'hljs language-',
            highlight(code, lang) {
                if (lang && hljs.getLanguage(lang)) {
                    return hljs.highlight(code, { language: lang }).value;
                }
                return hljs.highlightAuto(code).value;
            }
        })
    );

    // Enable GitHub Flavored Markdown features
    marked.use({
        gfm: true,
        breaks: false
    });

    const htmlBody = marked.parse(mdContent);
    const htmlDoc = HTML_TEMPLATE.replace('{{BODY}}', htmlBody);

    try {
        writeFileSync(outputPath, htmlDoc, 'utf-8');
        console.log(`Created: ${outputPath}`);
    } catch (err) {
        console.error(`Error: Cannot write file: ${outputPath}`);
        process.exit(1);
    }
}

main();