Menu
Writes human-friendly changelog entries and release notes. Use when populating changelog, preparing releases, or reviewing release notes quality.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Develop, validate, and publish DorkOS marketplace packages โ agents, plugins, skill-packs, and adapters. Use when creating marketplace items, working in the dork-labs/marketplace repo, or helping users build packages for the personal marketplace.
First-touch triage for incoming GitHub issues on dork-labs/dorkos. Use when DorkBot is asked to triage the issue queue: label each new issue by type and runtime, find likely duplicates, and ask the reporter for missing reproduction steps. Read-and-suggest by default; only comments or edits labels when explicitly allowed to act.
Regenerate DorkOS product screenshots and video loops from the real UI, and manage the shot registry, human overrides, and version archives that feed the marketing site, docs, and changelogs. Use when marketing/docs media is stale after UI changes, a new feature or docs page needs a money shot, a person wants to override an automated capture, or a release calls for a fresh capture or archive โ anything under apps/site/public/product/ or the apps/e2e/capture pipeline.
Skill whose frontmatter name does not match its directory name.
Implements the Calm Tech design system using Tailwind CSS v4 and Shadcn UI. Use when writing styles, building components, or theming. For design decisions, see designing-frontend.
Writes user-facing DorkOS prose a non-developer can read: changelog fragments, release notes, READMEs, npm copy, docs guides and concept pages, blog posts, UI microcopy, and error messages. Use when writing or reviewing any copy a person (not a coding agent) will read.
| name | writing-changelogs |
| description | Writes human-friendly changelog entries and release notes. Use when populating changelog, preparing releases, or reviewing release notes quality. |
Write changelog entries and release notes that humans actually want to read. This skill activates when writing changelog entries, preparing GitHub releases, or reviewing release notes quality.
Sources: Keep a Changelog, Common Changelog
/system:releaseUnreleased entries do not go in CHANGELOG.md. Each change adds one fragment file
under changelog/unreleased/ โ a coordination-free scheme that keeps parallel worktrees from
colliding on a shared [Unreleased] block (ADR 260707-231641; full guide in
changelog/README.md). The workflow:
<YYMMDD-HHMMSS>-<kebab-slug>.md: a timestamp id from .claude/scripts/id.ts
followed by a short slug. The post-commit hook names it from your commit subject.### Category headings (Added, Changed, Deprecated,
Removed, Fixed, Security) with bullets written per the principles below. One fragment may
carry multiple categories.post-commit hook writes a fragment from each conventional commit; curate
it (or hand-author one) before opening a PR. Never edit CHANGELOG.md's [Unreleased]
section โ it no longer holds entries./system:release compiles all fragments into the new ## [X.Y.Z] section and
deletes them. Only the release process writes CHANGELOG.md.The entry-quality guidance below applies identically to fragment bullets.
Changelog entries are user-facing prose, so the writing-for-humans skill sets the readability bar: 9th-grade level, one idea per sentence, benefit before mechanism, every acronym glossed. Read it first. The rules specific to changelogs:
(DOR-123) or (#42)- [Imperative verb] [user benefit/what changed] ([reference])
- **[Feature Name]** - [User benefit explanation]
- [Technical detail 1]
- [Technical detail 2]
| Bad (Developer-focused) | Good (User-focused) |
|---|---|
| Add obsidian_manager.py for auto vault registration | Open files in Obsidian without manual vault setup |
| fix: Use relative paths in theme commands | Fix theme commands failing when run from different directories |
| Accept 'default' as theme alias | Use 'default' to quickly apply the standard theme |
| Add changelog-populator.py hook | Changelog entries are now auto-generated from commits |
| Update AGENTS.md with new patterns | (Skip - internal documentation, not user-facing) |
| refactor: Extract helper function | (Skip - internal refactoring, no user impact) |
| Verb | Use For | Example |
|---|---|---|
| Add | New features, capabilities | Add dark mode support |
| Fix | Bug corrections | Fix login failing on Safari |
| Change | Modifications to existing behavior | Change default timeout to 30 seconds |
| Remove | Deleted features | Remove deprecated v1 API |
| Improve | Performance, UX enhancements | Improve search speed by 50% |
| Update | Dependencies, configurations | Update to React 18 |
| Deprecate | Scheduled for removal | Deprecate XML export (use JSON instead) |
Not everything belongs in the changelog. Skip:
Exception: Include if it affects how users interact with the system.
Add a single-line blockquote below version headings to provide a theme/summary for the release:
## [0.3.0] - 2026-02-20
> DorkOS 0.3.0 adds a scheduler and dynamic MCP tools.
### Added
- ...
This theme line feeds:
The blockquote is optional and backward-compatible. Older versions without it work fine.
Use these standard categories in order:
When creating GitHub releases, use this narrative format (different from the changelog):
## What's New in vX.Y.Z
[1-2 sentence theme describing the focus of this release]
_[One line caption. See it move โ [docs page or /features section]]_
### Highlights
๐จ **[Feature Name]** - [One sentence explaining the benefit and how to use it]
๐ **[Feature Name]** - [One sentence explaining the benefit and how to use it]
๐ง **[Fix/Improvement]** - [One sentence explaining what's better now]
### All Changes
- [Bullet list of all changes - can be slightly more technical]
- [Include references: (#123) or (abc1234)]
**Full Changelog**: https://github.com/[owner]/[repo]/compare/v[prev]...v[new]
Rule: every release with user-visible UI changes includes at least one visual. Embed the shot's poster PNG from the version's frozen archive (archive/vX.Y.Z/<shot-id>-<theme>.png โ never the live /product/<file> path, which repoints on the next capture and would change what an old release shows). GitHub renders PNG/GIF inline but does not play .webm, so link the caption to a docs page or /features section for the motion version instead of linking the webm directly. The /system:release media phase (Phase 6.6) selects and archives these shots before this step runs.
| Emoji | Use For |
|---|---|
| โจ | Major new feature |
| ๐จ | UI/UX improvements, themes |
| ๐ | File handling, organization |
| ๐ง | Fixes, improvements |
| โก | Performance |
| ๐ | Security |
| ๐ | Documentation |
| ๐๏ธ | Removals, deprecations |
Before publishing release notes, verify each entry:
(DOR-123) or (#42)For the overall release:
When converting conventional commits to changelog entries:
| Commit Message | Changelog Entry |
|---|---|
feat: Add obsidian_manager.py | Add automatic Obsidian vault registration |
fix(theme): Use relative paths | Fix theme commands failing outside project root |
feat!: Change config format | BREAKING: Change configuration format (see migration guide) |
chore: Update deps | (skip) |
docs: Fix typo | (skip) |
Always make breaking changes prominent:
### Changed
- **BREAKING**: [Description of breaking change]
- Migration: [How to update]
During release preparation:
For each entry, mentally prepend "You can now..." - if it doesn't make sense, rewrite it.
If someone asks "so what?" after reading your entry, you need more context.