agentleFS
Yesterday-AIYesterday-AI/paperclip-plugin-company-wizard/.claude/skills/release/SKILL.md

release

Skill171 starsChanged 8 months agoMITView on GitHub

Prepare a new release by updating CHANGELOG.md, verifying documentation (README.md, CLAUDE.md, AGENTS.md, ROADMAP.md, docs/), bumping patch version in package.json, building, and suggesting publish commands. Use when asked to release, bump version, prepare release, or publish.

  • Commits and pushes

193 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use create-agent-adapter, changelog-style and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    create-agent-adapter

    Technical guide for creating a new Paperclip agent adapter. Use when building a new adapter package, adding support for a new AI coding tool (e.g. a new CLI agent, API-based agent, or custom process), or when modifying the adapter system. Covers the required interfaces, module structure, registration points, and conventions derived from the existing claude-local and codex-local adapters.

    Also in 5 projects that use this

  • GrinvSkill

    changelog-style

    Turn a commit range into CHANGELOG.md entries following common-changelog style. Use when finishing a PR or cutting a release, to write/fix the [Unreleased] section's entries — moving [Unreleased] under a new dated version heading is a separate, automated step (see the release skill / scripts/sync-version.ts), not this skill's job.

    Also in 4 projects that use this

  • Microsoft AzureSkill

    component-release

    Prepares a verifiable Agent Landing Zone UI release. Use for release branches, VERSION, changelog entries, tags, release notes, and compatibility evidence; never publish without explicit human approval.

    Also in 4 projects that use this

  • GrinvSkill

    docs-consistency-check

    Check README/manifest.json/server.json/CHANGELOG.md/AGENTS.md and docs/*.md for drift against the actual registered tools and source. Use after adding, renaming, or removing a tool, or as part of a live-audit pass.

    Also in 4 projects that use this

  • Microsoft AzureSkill

    documentation-consistency

    Keeps AI Landing Zone contributor, user, and operator documentation aligned with shipped Bicep behavior. Use for parameters, defaults, outputs, topology, deployment flow, operations, or releases.

    Also in 8 projects that use this

  • parcadeiSkill

    agent-context-isolation

    Agent Context Isolation

    Also in 3 projects that use this

  • +3 more from Grinv

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 10 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 183 edited versions we read keep these.

  • 10

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Check each documentation file against the actual codebase.

    line 53
  2. Distinctive:

    Add any new backlog items discovered during development

    line 78
  3. Distinctive:

    Remove items that are no longer relevant

    line 79
  4. Distinctive:

    Only update what's actually wrong or missing.

    line 87
  5. Distinctive:

    If counts changed (e.g., "14 presets" → "15 presets"), update all occurrences across all files.

    line 88
  6. Distinctive:

    If a new state field was added, ensure CLAUDE.md's WizardContext description mentions it.

    line 89
  7. Distinctive:

    If new worker actions were added, ensure they're listed in the architecture section.

    line 90
  8. Distinctive:

    Also check: if the version appears in any other files (README badges, etc.) and update those too.

    line 102
  9. Distinctive:

    If any step fails, fix the issue before proceeding.

    line 111
  10. Distinctive:

    Do NOT run these commands — just print them for the user to review and execute manually.

    line 115
  11. Very specific:

    If the package is scoped (starts with @), remind the user that --access public is needed for public packages.

    line 137

“Common” is measured: kept by at least 6 in 10 of the 183 edited versions of this file we could read. “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

Release — Prepare and Document a New Version

Phase 1: Analyze Changes

Understand what changed since the last release:

  1. Read current version from package.json.
  2. Read CHANGELOG.md to understand the last documented version and its date. Note any gap — if package.json is ahead of the changelog, intermediate releases were shipped without entries.
  3. Find the release boundary. Try git tag -l 'v*' --sort=-v:refname | head -5 for the latest tag. If no tags exist, find the commit that last bumped the version (e.g., git log --oneline --all -- package.json | head -5) and use that SHA as the base.
  4. Run git log <base>..HEAD to collect all commit messages since the last release.
  5. Run git diff <base>..HEAD to see all committed file changes. Also run git diff HEAD to capture any uncommitted work in the working tree — this may contain unreleased feature work.
  6. Count templates from the filesystem to verify against documentation:
    • ls templates/presets/ | wc -l
    • ls templates/modules/ | wc -l
    • ls templates/roles/ | wc -l
  7. Pay attention to:
    • New features (new files, new actions, new UI steps)
    • Bug fixes (error handling, logic corrections)
    • Template changes (new presets, modules, roles, prompt updates)
    • Configuration changes (new settings, defaults)
    • Breaking changes (removed features, renamed fields, API changes)
  8. Categorize changes into: Added, Changed, Fixed, Removed, Template system (if applicable).

Phase 2: Update CHANGELOG.md

  1. Read CHANGELOG.md to understand the existing format and style.
  2. If intermediate versions exist without changelog entries (e.g., package.json jumped from 0.1.0 to 0.1.2 but the changelog only has 0.1.0), create brief entries for the skipped versions too — even if they were just version bumps or metadata changes.
  3. Add a new version section at the top (below the header), following Keep a Changelog format:

    ## [X.Y.Z] — YYYY-MM-DD
    
    ### Added
    - Feature description
    
    ### Changed
    - Change description
    
    ### Fixed
    - Bug fix description
  4. Match the tone and detail level of existing entries. Be specific — mention file names, action names, field names where relevant.
  5. Do NOT include trivial changes (formatting, comments) unless they affect behavior.

Phase 3: Verify Documentation

Check each documentation file against the actual codebase. For each file, read it and verify accuracy. Only edit if something is factually wrong or missing due to the changes being released.

Files to check

  1. README.md — Verify:
    • Feature descriptions match current behavior
    • Configuration options are up to date
    • Template counts (presets, modules, roles) are accurate
    • Example commands still work
    • Any new features from this release are mentioned where appropriate
  2. CLAUDE.md — Verify:
    • Architecture description matches current source layout
    • Key concepts are accurate (especially if state fields, actions, or API flow changed)
    • Template system description is current
    • Build/test commands are correct
  3. AGENTS.md — Verify:
    • Project vision still matches reality
    • Architecture diagram is current
    • Design principles haven't been violated by changes
    • Template/module/role counts are accurate
  4. ROADMAP.md — Verify:
    • Move newly completed items from "Backlog" or "In Progress" to "Done"
    • Add any new backlog items discovered during development
    • Remove items that are no longer relevant
  5. docs/ directory — Verify:
    • Any documentation files are consistent with template/module changes
    • Cross-references between docs are still valid

Documentation rules

  • Only update what's actually wrong or missing. Don't rewrite prose that's still accurate.
  • If counts changed (e.g., "14 presets" → "15 presets"), update all occurrences across all files.
  • If a new state field was added, ensure CLAUDE.md's WizardContext description mentions it.
  • If new worker actions were added, ensure they're listed in the architecture section.

Phase 4: Bump Version

You MUST bump the version. Do NOT skip this phase. Do NOT leave the version unchanged.

  1. Read package.json to get the current version.
  2. Check for recent version-bump commits — run git log --oneline -5 -- package.json to ensure you're not colliding with a version that was already bumped externally. If the current version was bumped by a recent commit you haven't accounted for, increment from that version instead.
  3. Increment the patch version (e.g., 0.1.5 → 0.1.6). Always patch. Never minor or major unless the user explicitly says so.
  4. Edit package.json — change the "version" field to the new version.
  5. Edit src/manifest.ts — change the version field to the same new version.
  6. Verify both files match — grep both files to confirm the version is identical.
  7. Also check if the version appears in any other files (README badges, etc.) and update those too.

Phase 5: Build and Verify

  1. Run pnpm build — ensure it succeeds with no errors.
  2. Run pnpm typecheck — ensure no type errors.
  3. Run pnpm test — vitest plugin tests.
  4. Run pnpm test:logic — node:test logic suite. Both test suites must pass.

If any step fails, fix the issue before proceeding.

Phase 6: Suggest Publish Commands

Do NOT run these commands — just print them for the user to review and execute manually.

Present the commands in order:

# Review the changes one more time:
git diff

# Commit everything:
git add -A
git commit -m "chore: release vX.Y.Z"

# Tag the release:
git tag vX.Y.Z

# Push:
git push && git push --tags

# Publish to npm:
pnpm publish --access public

If the package is scoped (starts with @), remind the user that --access public is needed for public packages.

Also mention: "After publishing, reload the plugin in the Paperclip UI to pick up the new version."

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.