semantic-version
Skill0 starsChanged 2 months agoMITView on GitHub
Maintains a project release history JSON file with semantic versions (MAJOR.MINOR.PATCH), dates, and change summaries. Use when shipping user-visible changes, bumping version, updating release history, preparing commits that need a version entry, or when the user mentions about page data, release log, version history, or semantic versioning on disk.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- Jinbae10/skillstheir own version, first seen Jul 7, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- Jinbae10/skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository26 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .cursor/rules/automate-before-manual.mdcCursor rule
- .cursor/rules/finish-task-dev-server.mdcCursor rule
- brainstormingSkill
- caveman-commitSkill
- find-skillsSkill
- systematic-debuggingSkill
- verification-before-completionSkill
- writing-plansSkill
- ask-before-architectureSkill
- automate-before-manualSkill
- caveman-commitSkill
- diagrams-mermaidSkill
- dont-be-lazySkill
- dont-forgetSkill
- find-jobSkill
- finish-with-dev-serverSkill
- google-calendar-mcpSkill
- init-fmzSkill
- instagram-chrome-postSkill
- project-initSkill
- recapSkill
- semantic-versionSkill
- skills-sh-maintainerSkill
- ui-change-e2eSkill
- validate-before-shareSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 5 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 14
Do not: update docs/release-history.json while editing docs, specs, plans, or code.
- Very specific: line 22
Create docs/ if missing. Never split history across multiple files.
- Very specific: line 24
If the project already has docs/release-history.json, use it.
- Very specific: line 61
Start at 0.1.0 for new projects unless the repo already defines a version.
- Distinctive: line 70
When in doubt whether the change is user-visible, ask once.
- Very specific: line 74
Update docs/release-history.json in the same /commit-push run when:
- Very specific: line 80
Do not update during normal editing, planning, or commits outside /commit-push.
- Distinctive: line 82
Do not update for: formatting, comments, dev-only config, test-only changes, or dependency bumps with no behavioral change.
- Very specific: line 86
Read docs/release-history.json (create from template if absent).
- Distinctive: line 88
If skipping, stop; do not touch the file.
- Very specific: line 93
After commit, add commit (short SHA) to the new entry if it was omitted.
- Distinctive: line 117
When the file does not exist:
- Distinctive: line 127
Add the first entry only when the first user-visible delivery ships.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Semantic Version
Maintain a single JSON file on disk that records product version and release entries. No database, no UI — the file is the source of truth for About screens, changelogs, or tooling to consume later.
Faruk Base — when to bump
In Faruk Base (this template repo):
- Do not update
docs/release-history.jsonwhile editing docs, specs, plans, or code. - Only bump version when the user invokes
/commit-push(or explicitly asks to record a release without that command). - Pair with
caveman-commitin the same/commit-pushrun.
Canonical file
Path: docs/release-history.json
Create docs/ if missing. Never split history across multiple files.
If the project already has docs/release-history.json, use it. Do not rename or relocate without explicit user request.
JSON schema
{
"currentVersion": "0.1.0",
"updatedAt": "2026-07-07T22:15:00.000Z",
"entries": [
{
"version": "0.1.0",
"date": "2026-07-07",
"title": "Short headline for the release",
"summary": "One or two sentences on what changed for the user.",
"type": "feat",
"commit": "a1b2c3d"
}
]
}Field rules
| Field | Rules |
currentVersion | Latest version MAJOR.MINOR.PATCH. Must match newest entry version. |
updatedAt | ISO 8601 UTC timestamp of last file write. |
entries | Newest first. Never delete past entries unless user explicitly asks. |
version | Strict MAJOR.MINOR.PATCH — always three numeric parts. |
date | YYYY-MM-DD in local project timezone or UTC; be consistent within a project. |
title | Imperative or past-tense headline, ≤80 chars, user-facing language. |
summary | Plain explanation of user-visible impact; no commit-message boilerplate. |
type | One of: feat, fix, refactor, perf, docs, chore, breaking. |
commit | Short git SHA (7 chars) after commit exists; omit while drafting pre-commit. |
Version bump rules
Start at 0.1.0 for new projects unless the repo already defines a version.
| Change | Bump | Example |
| New user-visible feature | MINOR | 0.12.0 → 0.13.0 |
| Bugfix or small adjustment, no new feature | PATCH | 0.13.0 → 0.13.1 |
| Breaking change (API, migration, removed behavior) | MAJOR | 0.13.1 → 1.0.0 |
| Docs, tests, CI, refactors with zero user-visible effect | No bump | Do not add an entry |
When in doubt whether the change is user-visible, ask once. Default to no entry for internal-only work.
When to update
Update docs/release-history.json in the same /commit-push run when:
- The diff alters behavior, UI, API contracts, or defaults that users would notice.
- The user asks to record a release or bump version (typically via
/commit-push). - Preparing a commit the user intends to ship as a versioned delivery.
Do not update during normal editing, planning, or commits outside /commit-push.
Do not update for: formatting, comments, dev-only config, test-only changes, or dependency bumps with no behavioral change.
Workflow
- Read
docs/release-history.json(create from template if absent). - Inspect the diff — decide bump level (
feat/fix/breaking/ skip). - If skipping, stop; do not touch the file.
- Compute next version from
currentVersionand bump rules. - Prepend a new entry to
entrieswithversion,date,title,summary,type. - Set
currentVersionandupdatedAt. - Align
package.json/ app manifests withcurrentVersionwhen those files exist in the project. - After commit, add
commit(short SHA) to the new entry if it was omitted.
Pair with caveman-commit for the git message; the release title/summary are user-facing, not the commit subject.
Writing entries
- title: what shipped — "Editable category codes", not "Update CategoryView.vue".
- summary: why it matters — scope, migration notes, breaking behavior.
- Match the project's UI language (Portuguese or English) for
titleandsummary; keep JSON keys in English. - One entry per shipped version, not one per commit (unless each commit is a release).
Validation checklist
Before finishing:
currentVersionmatchesentries[0].version- Version has exactly three numeric parts
- Entries sorted newest-first
- No duplicate
versionvalues typeis a allowed value- JSON is valid and pretty-printed with 2-space indent
Initializing a new project
When the file does not exist:
{
"currentVersion": "0.1.0",
"updatedAt": "2026-07-07T00:00:00.000Z",
"entries": []
}Add the first entry only when the first user-visible delivery ships.
Examples
See examples.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

