Menu
Writes human-friendly changelog entries and release notes. Use when populating changelog, preparing releases, or reviewing release notes quality.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Keeps skill definitions aligned between Claude Code and Codex. Use when creating, migrating, renaming, or updating skills that must work across `.claude/skills` and `.agents/skills`, or when auditing drift between the two systems.
When to open a pull request in the DorkOS repo (review the pushed branch first, open the PR after it converges) and how the automated review behaves, including its controls (skip-review, review:light/deep, re-review). Use when finishing a branch, opening a PR, deciding how much review a PR should get, or requesting a re-review after addressing feedback.
Decides when agent work needs an isolated git worktree and how to create, enter, and clean one up safely. Use when starting code changes in a checkout that may be shared with another agent, dispatching a Linear task, executing a spec, or running any parallel work that mutates tracked files.
Writes non-release DorkOS blog posts - feature posts, decision essays, ecosystem posts, and release recaps - from the repo's own ADRs, specs, research reports, and changelog fragments. Use when drafting, researching, or reviewing anything in blog/ that is not a version release note.
Guides writing concise, effective Architecture Decision Records. Use when creating ADRs, extracting decisions from specs, or reviewing ADR quality.
Patterns for adding, renaming, removing, or retyping fields in DorkOS user config. Use when editing UserConfigSchema, MarketplacesFileSchema, or any conf-backed store — walks the Zod field → defaults → conf migration → docs → test lifecycle end-to-end.
| 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.covers: frontmatter (which commits this fragment covers; the
post-commit hook fills it in, and the PR check reads it so your prose stays free to be
rewritten for a human), then one or more ### 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.