gaia-research/gaia-skill-tree / .agents/skills/gaia-release
gaia-release
VerifiedHelper for release operations, compilation of changelogs between tags, version lockstep syncing, and promotion of GitHub releases from canary/pre-release to latest/production. Use when the user asks to "compile the changelog", "promote release to latest", "tag a release", or do version release operations.
gaia-release
A skill for managing releases, compiling changelogs across tags, verifying version lockstep, and promoting releases from canary/beta to latest/production.
When to invoke
Trigger when the user requests release operations, including:
- "Compile the changelog from previous latest" / "generate release notes"
- "Mark tag vX.Y.Z as Latest" / "promote release to latest"
- "Update release notes on GitHub"
- Release bump checks and tag auditing
Do NOT use for:
- Standard git branch merging (use standard git procedures)
- Regular document sync routines (use
gaia-docs-syncor similar)
Operating Contract
1. Compile Changelogs
To compile a changelog from a previous version/tag to the target tag:
- Fetch all tags from remote to ensure your local tag list is up-to-date:
git fetch --tags - Find the commits and tags between the starting tag and the target tag:
git log <start_tag>..<target_tag> --decorate --oneline - Group commits by their release tags and format them into readable changelog groups:
- Features (
feat:,chore:, etc.) - Bug Fixes (
fix:, etc.) - Documentation (
docs:, etc.) - CI / Testing / Housekeeping (
infra:,test:, etc.)
- Features (
- Keep the list concise and link to the relevant Pull Requests or Issues.
2. Verify / Sync Version Lockstep
If requested to update version files:
- The three manifest files must remain in lockstep:
pyproject.tomlpackages/cli-npm/package.jsonregistry/gaia.json(gitignored pipeline-internal, but updated locally)
- Use
python3 scripts/verify_lockstep.pyto check current lockstep alignment. - Sync versions using:
Or if not bumping and only syncing manifests to the highest version:gaia dev release <patch|minor|major> --syncpython3 -m gaia_cli.main dev release --sync
3. Promote GitHub Release to Latest / Production
⚠️ Ancestry guard (mandatory — issue: split-brain release state). Before promoting or publishing any tag, verify the tag's commit is an ancestor of
main. Promoting/publishing a tag whose commit never landed onmaindesyncs the published version from the branch manifests, which makessync-artifacts.ymlrecompute the same patch version on every subsequent merge and hard-fail onfatal: tag 'vX.Y.Z' already exists(this is exactly what happened withv6.8.9). Run this and abort if it fails:git fetch --tags origin main if ! git merge-base --is-ancestor "$(git rev-list -n1 <tag>)" origin/main; then echo "ABORT: <tag> commit is not on main — land the version-bump commit first." exit 1 fiIf the tag is legitimately ahead of
main(e.g. the release commit is still in flight), do not promote/publish yet — merge the bump tomainfirst, or reconcilemain's manifests to the tag version so the branch owns it.
To change a canary or beta release to the latest production release on GitHub:
- Generate the changelog/notes in a markdown file (e.g.
generated-output/changelog_vX.Y.Z.md). - Run the
gh release editcommand with the appropriate flags to update the title, remove the prerelease flag, mark it as latest, and upload the notes:gh release edit <tag> --title "<tag>" --prerelease=false --latest --notes-file <path_to_notes.md> - Run
gh release view <tag>to verify that the release showsprerelease: falseand the title/notes are correct.
4. Manually Publish to PyPI
If the release needs to be manually published to PyPI (e.g., when bypassing automated CI triggers or for manual publication control):
⚠️ Apply the same ancestry guard from §3 first. Publishing a version to PyPI that
main'spyproject.tomldoes not carry is unrecoverable (PyPI versions are immutable) and strandsmainbehind the published version. Only publish whenmain's version ≥ the version being published.
- Use the GitHub CLI to trigger the
Publish gaia-cli to PyPIworkflow manually. Specify themainbranch as the reference, which will build the version defined inpyproject.tomlon themainbranch:gh workflow run publish-pypi.yml --ref main - Monitor the run to confirm that the build and publish steps complete successfully.
5. Code Change Constraint
- Always respect user instructions regarding code changes. If the user states "commit no code" or "just do the tagging and release," perform all tag/release modifications on GitHub directly using
ghCLI commands and output the compiled changelog text in the chat, rather than committing edits toCHANGELOG.md.
Example Invocation
User: Work on tag v5.4.10 and change it as Latest. Compile the CHangelog from previous latest. I will be publishing it to pypi.
Agent:
1. Fetches tags and inspects commits between v5.1.1 and v5.4.10.
2. Compiles a detailed changelog grouped by release.
3. Uses `gh release edit v5.4.10 --title "v5.4.10" --prerelease=false --latest --notes-file generated-output/changelog_v5.4.10.md` to promote the release to Latest.
4. Verifies the status using `gh release view`.
5. Presents the changelog to the user and confirms the release update.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |