Skill Changelog

Skill Changelog

Maintain a CHANGELOG.md inside the directory of any skill being worked on. Every meaningful edit to a skill warrants a dated, versioned entry.

Skill Locations

Skills live in one of two places — both are valid targets:

1. Standalone skills: ~/.claude/skills/<skill-name>/ or .claude/skills/<skill-name>/
2. Plugin skills: ~/.claude/plugins/marketplaces/<marketplace>/plugins/<plugin>/skills/<skill-name>/ — or in marketplace repos: plugins/<plugin>/skills/<skill-name>/

CHANGELOG.md location depends on context — see Location Detection below.

Location Detection

Before writing CHANGELOG.md, determine where it belongs:

1. Resolve the real path of the SKILL.md being edited — the path may be a symlink (e.g. ~/.claude/skills/<name>/SKILL.md symlinked to a repo location):

   readlink -f <path-to-SKILL.md>
   

   Use the resolved canonical path for all directory traversal below.
2. Start from the skill's root directory (the folder containing the resolved SKILL.md).
3. Walk up the directory tree (up to 4 levels) looking for .claude-plugin/plugin.json.
4. Plugin found: the directory containing .claude-plugin/ is the plugin root — place CHANGELOG.md there.
5. Plugin not found: the skill is standalone — place CHANGELOG.md next to SKILL.md.

Example — plugin skill (symlinked):

• Loaded via: ~/.claude/skills/create-release/SKILL.md (symlink)
• Resolved to: [repo]/plugins/release-workflow/skills/create-release/SKILL.md
• Found: [repo]/plugins/release-workflow/.claude-plugin/plugin.json
• CHANGELOG: [repo]/plugins/release-workflow/CHANGELOG.md

Example — standalone skill:

• Skill dir: ~/.claude/skills/conventional-commits/
• readlink -f returns same path (not a symlink)
• No .claude-plugin/plugin.json found walking up
• CHANGELOG: ~/.claude/skills/conventional-commits/CHANGELOG.md

Plugin-level entry format

When CHANGELOG.md is shared across multiple skills in a plugin, prefix each bullet with the skill name so it's clear what changed:

### Added
- `create-release`: initial skill — orchestrates version detection, release branch, CI monitoring, PR creation
- `monitor-pipeline`: initial skill — watches GitHub Actions run, reports pass/fail

Operating Modes

The active mode is stored as plain text (opt-in or auto) in:

~/.claude/skills/.skill-changelog/mode

If the file does not exist, default to opt-in.

Switching modes

When the user says anything like "switch to auto", "track all skills automatically", "go back to opt-in", or "manual only":

1. Write the new mode value to ~/.claude/skills/.skill-changelog/mode
2. Confirm the change to the user

Standing Rule

Before finishing any skill editing task, silently apply this rule:

1. Identify the skill's root directory (the folder containing the SKILL.md being edited) and run Location Detection to determine the resolved CHANGELOG location.
2. Read ~/.claude/skills/.skill-changelog/mode (default: opt-in)
3. opt-in mode: proceed only if CHANGELOG.md already exists at the resolved location
4. auto mode: always proceed — create CHANGELOG.md at the resolved location if absent, then append an entry

Do this without prompting the user.

CHANGELOG.md Initialization

When creating a new CHANGELOG.md, write this header first:

# Changelog

All notable changes to this skill will be documented in this file.

The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [Unreleased]

<!-- Next release entries go here -->

Entry Format

Append entries in reverse-chronological order (newest at the top, below the header):

## [<version>] - <YYYY-MM-DD>T<HH:MM:SS>Z

### <Change Type>
- <concise description of what changed and why>

Change types

Use one or more per entry:

• Added — new features, sections, references, or scripts
• Changed — modifications to existing content or behavior
• Fixed — corrections to errors or wrong behavior
• Removed — deleted content or files
• Deprecated — features marked for future removal
• Security — security-related updates

Versioning

Auto-infer the version bump — do not ask the user:

Start at 1.0.0 for the initial entry of a newly initialized changelog.

Timestamp

Use the current UTC time in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

Example Entry

## [1.1.0] - 2026-04-25T14:32:00Z

### Changed
- Expanded description to include additional trigger phrases to prevent undertriggering

### Added
- `references/schemas.md` with JSON schema for structured output validation

Behavior Reference