agentleFS
farukzahrafarukzahra/agent-skills/.agents/skills/semantic-version/SKILL.md

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

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
  1. Very specific:

    Do not: update docs/release-history.json while editing docs, specs, plans, or code.

    line 14
  2. Very specific:

    Create docs/ if missing. Never split history across multiple files.

    line 22
  3. Very specific:

    If the project already has docs/release-history.json, use it.

    line 24
  4. Very specific:

    Start at 0.1.0 for new projects unless the repo already defines a version.

    line 61
  5. Distinctive:

    When in doubt whether the change is user-visible, ask once.

    line 70
  6. Very specific:

    Update docs/release-history.json in the same /commit-push run when:

    line 74
  7. Very specific:

    Do not update during normal editing, planning, or commits outside /commit-push.

    line 80
  8. Distinctive:

    Do not update for: formatting, comments, dev-only config, test-only changes, or dependency bumps with no behavioral change.

    line 82
  9. Very specific:

    Read docs/release-history.json (create from template if absent).

    line 86
  10. Distinctive:

    If skipping, stop; do not touch the file.

    line 88
  11. Very specific:

    After commit, add commit (short SHA) to the new entry if it was omitted.

    line 93
  12. Distinctive:

    When the file does not exist:

    line 117
  13. Distinctive:

    Add the first entry only when the first user-visible delivery ships.

    line 127

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.json while 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-commit in the same /commit-push run.

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

FieldRules
currentVersionLatest version MAJOR.MINOR.PATCH. Must match newest entry version.
updatedAtISO 8601 UTC timestamp of last file write.
entriesNewest first. Never delete past entries unless user explicitly asks.
versionStrict MAJOR.MINOR.PATCH — always three numeric parts.
dateYYYY-MM-DD in local project timezone or UTC; be consistent within a project.
titleImperative or past-tense headline, ≤80 chars, user-facing language.
summaryPlain explanation of user-visible impact; no commit-message boilerplate.
typeOne of: feat, fix, refactor, perf, docs, chore, breaking.
commitShort 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.

ChangeBumpExample
New user-visible featureMINOR0.12.0 → 0.13.0
Bugfix or small adjustment, no new featurePATCH0.13.0 → 0.13.1
Breaking change (API, migration, removed behavior)MAJOR0.13.1 → 1.0.0
Docs, tests, CI, refactors with zero user-visible effectNo bumpDo 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:

  1. The diff alters behavior, UI, API contracts, or defaults that users would notice.
  2. The user asks to record a release or bump version (typically via /commit-push).
  3. 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

  1. Read docs/release-history.json (create from template if absent).
  2. Inspect the diff — decide bump level (feat / fix / breaking / skip).
  3. If skipping, stop; do not touch the file.
  4. Compute next version from currentVersion and bump rules.
  5. Prepend a new entry to entries with version, date, title, summary, type.
  6. Set currentVersion and updatedAt.
  7. Align package.json / app manifests with currentVersion when those files exist in the project.
  8. 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 title and summary; keep JSON keys in English.
  • One entry per shipped version, not one per commit (unless each commit is a release).

Validation checklist

Before finishing:

  • currentVersion matches entries[0].version
  • Version has exactly three numeric parts
  • Entries sorted newest-first
  • No duplicate version values
  • type is 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.