igmarinigmarin/rails-agent-skills/skills/release-engine/SKILL.md

release-engine

Skill26 starsChanged 4 months agoMITView on GitHub

Use when preparing a versioned Rails engine release (SemVer, changelog). Trigger words: release engine, version bump, publish gem, changelog.

In this repository32 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- apply-code-conventionsSkill
- apply-stack-conventionsSkill
- code-reviewSkill
- create-engine-installerSkill
- create-engineSkill
- document-engineSkill
- extract-engineSkill
- generate-api-collectionSkill
- implement-authorizationSkill
- implement-background-jobSkill
- implement-graphqlSkill
- implement-hotwireSkill
- load-contextSkill
- optimize-performanceSkill
- plan-testsSkill
- rails-featureSkill
- rails-maintenanceSkill
- rails-reviewSkill
- refactor-codeSkill
- review-architectureSkill
- review-engineSkill
- review-migrationSkill
- security-checkSkill
- seed-databaseSkill
- setup-environmentSkill
- test-engineSkill
- test-serviceSkill
- upgrade-engineSkill
- version-apiSkill
- write-testsSkill

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 5 are distinctive, and 5 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.
5
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific
could be automatic: a setting could enforce it

Distinctive:
Use this skill when the task is to ship a Rails engine as a gem or prepare a new version.
line 16
Very specific:
Run full test suite: bundle exec rspec.
line 35
Distinctive:
Update changelog and upgrade notes.
line 37
Distinctive:
Verify gemspec metadata and dependencies match tested Rails/Ruby versions.
line 38
Distinctive:
Ask the user to approve publishing the exact gem name and version.
line 41
Very specific:
Read assets/release_checklist.md when producing the release verification checklist or quality gates.
line 48
Very specific:
Read assets/release_notes_template.md when drafting GitHub release notes, a long-form announcement, or public release copy.
line 49
Very specific:
Read assets/examples.md only when the user needs concrete release examples.
line 50
Very specific:
Document user-visible changes, not commits.
line 53
Distinctive:
If the engine requires host changes during upgrade, document them explicitly even if the version bump is minor.
line 55

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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

Release Engine

Use this skill when the task is to ship a Rails engine as a gem or prepare a new version.

Quick Reference

Bump	When to use	Action
Patch	Bug fixes and internal changes without public behavior breakage	Update version constant, document under Fixed
Minor	Backward-compatible features and new extension points	Update version constant, document under Added/Changed
Major	Breaking changes to API, setup, routes, migrations, config, or supported framework versions	Update version constant, document under Changed/Deprecated; write explicit upgrade notes

HARD-GATE

DO NOT release without updating CHANGELOG and version file.

Core Process

Confirm scope and compatibility impact — is this patch, minor, or major?
Run full test suite: bundle exec rspec. Fix all failures before proceeding.
Set the version bump — update the version constant once: module MyEngine; VERSION = "1.2.0"; end in lib/my_engine/version.rb.
Update changelog and upgrade notes.
Verify gemspec metadata and dependencies match tested Rails/Ruby versions.
Dry-run the gem build: gem build *.gemspec && gem push --dry-run *.gem. Verify contents.
Confirm installation docs and README match the release — update if needed.
Ask the user to approve publishing the exact gem name and version. Preparing a release is not authorization to publish.
Publish only after that approval: gem push *.gem.

Extended Resources

Load release assets conditionally and say which one informed the output:

Read assets/release_checklist.md when producing the release verification checklist or quality gates.
Read assets/release_notes_template.md when drafting GitHub release notes, a long-form announcement, or public release copy.
Read assets/examples.md only when the user needs concrete release examples.

Changelog Guidelines

Document user-visible changes, not commits; group by Added/Changed/Fixed/Deprecated.
For deprecations, document removal plan and replacement; keep deprecated code for at least one minor cycle.
If the engine requires host changes during upgrade, document them explicitly even if the version bump is minor.

Examples

## [1.2.0] - 2024-03-15
### Added
- `widget_count` config option to limit dashboard widgets (default: 10).
### Changed
- Minimum Rails version is now 7.0.

assets/release_checklist.md
assets/release_notes_template.md
assets/examples.md

Output Style

Version bump — patch/minor/major with explicit reasoning.
Version constant — updated lib/[engine_name]/version.rb.
CHANGELOG entries — under Added/Changed/Fixed/Deprecated headers.
Upgrade notes — host app steps (config, migrations, dependencies).
Gemspec + test status — metadata, files, dependency ranges confirmed; pass/fail result of bundle exec rspec.
Dry-run output — exact command gem build *.gemspec && gem push --dry-run *.gem plus contents verification (tar tf pkg/*.gem or gem contents).
Asset usage — state which of assets/release_checklist.md, assets/release_notes_template.md, assets/examples.md was loaded, or explicitly say none was needed.
GitHub release notes — concise draft with summary, highlights, upgrade notes, and verification status.
Release blockers — open issues, or explicitly "No blockers".

Integration

Skill	When to chain
document-engine	Updating README, setup instructions, or API docs for the release
upgrade-engine	Verifying Rails/Ruby version support or deprecation impact
test-engine	Ensuring tests pass before release and match documented behavior

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.

Check your setup, free