feat(agent-skills): add toolchain-manager migration guides - #2877
Open
Erik Osterman (Cloud Posse) (osterman) wants to merge 4 commits into
Open
feat(agent-skills): add toolchain-manager migration guides#2877Erik Osterman (Cloud Posse) (osterman) wants to merge 4 commits into
Erik Osterman (Cloud Posse) (osterman) wants to merge 4 commits into
Conversation
…igration Add six ASD-STE100 reference files (from-asdf, from-aqua, from-tfenv, from-tofuenv, from-tenv, from-homebrew-brewfile) covering migration from external tool-version managers to the Atmos toolchain, each with a before/after config comparison, command mapping, shell integration steps, and functional-gap notes. Wire them into atmos-migration/SKILL.md with a new routing section, escalation link, anti-patterns, and resource index. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Erik Osterman (Cloud Posse) (osterman)
requested a review
from a team
as a code owner
August 5, 2026 20:36
Contributor
|
Tip Atmos Pro
No affected stacks workflow was detected for this pull request. 
|
Erik Osterman (Cloud Posse) (osterman)
added
the
no-release
|
💥 This pull request now has conflicts. Could you fix it Erik Osterman (Cloud Posse) (@osterman)? 🙏 |
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (7)
🚧 Files skipped from review as they are similar to previous changes (7)
📝 WalkthroughWalkthroughThe Atmos migration skill now covers six tool-version managers and Homebrew Brewfiles. It adds routing guidance and reference guides for configuration, command conversion, shell integration, tool resolution, and documented functional gaps. ChangesToolchain migration documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (1)
agent-skills/skills/atmos-migration/references/from-aqua.md (1)
59-62: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick winMake the lockfile example deterministic and repository-relative.
The default
toolchain.lock.yamlcan change whentoolchain.install_pathchanges, so this migration doc should not present it as a reliableaqua-checksums.jsonreplacement unless the path is also fixed. Addlock_file: toolchain.lock.yamlto the example config.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@agent-skills/skills/atmos-migration/references/from-aqua.md` around lines 59 - 62, Update the toolchain configuration example to explicitly set toolchain.lock_file to the repository-relative path toolchain.lock.yaml, and adjust the surrounding documentation to describe that configured path as the deterministic replacement for aqua-checksums.json.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@agent-skills/skills/atmos-migration/references/from-aqua.md`:
- Around line 42-44: Update the aqua source entry in the migration to preserve
the original aqua.yaml registry pin by replacing the moving main branch
reference with the corresponding v4.245.0 tag or commit, while retaining the
existing registry path.
- Around line 178-182: Update the command_aliases row in the Aqua-to-Atmos
mapping to direct users to toolchain.proxies for recreating command-name
behavior, and remove the incorrect reference to toolchain.aliases. Leave the
other migration mappings unchanged.
In `@agent-skills/skills/atmos-migration/references/from-asdf.md`:
- Around line 102-107: Update the shell-resolution sections at
agent-skills/skills/atmos-migration/references/from-asdf.md lines 102-107,
agent-skills/skills/atmos-migration/references/from-aqua.md lines 104-108,
agent-skills/skills/atmos-migration/references/from-homebrew-brewfile.md lines
105-108, agent-skills/skills/atmos-migration/references/from-tfenv.md lines
82-87, agent-skills/skills/atmos-migration/references/from-tofuenv.md lines
88-92, and agent-skills/skills/atmos-migration/references/from-tenv.md lines
108-114 to document .tool-versions as the project-wide default toolchain source
while retaining dependencies.tools as the stack/scoped override.
In `@agent-skills/skills/atmos-migration/references/from-homebrew-brewfile.md`:
- Around line 70-74: Update the Homebrew migration guidance for kubernetes-cli
to use the GitHub repository kubernetes/kubernetes instead of
kubernetes-sigs/kubectl. Replace the kubernetes-sigs/kubectl reference in the
later example or package registry entries while preserving the surrounding
mapping instructions.
In `@agent-skills/skills/atmos-migration/SKILL.md`:
- Around line 111-113: Update the shell initialization guidance around “atmos
toolchain env” and “atmos toolchain path” to use supported shell-specific forms:
evaluate the output of “atmos toolchain env” or explicitly prepend the output of
“atmos toolchain path” to PATH, with equivalent Fish and PowerShell commands.
Clarify that running “atmos toolchain path” alone does not modify PATH.
---
Nitpick comments:
In `@agent-skills/skills/atmos-migration/references/from-aqua.md`:
- Around line 59-62: Update the toolchain configuration example to explicitly
set toolchain.lock_file to the repository-relative path toolchain.lock.yaml, and
adjust the surrounding documentation to describe that configured path as the
deterministic replacement for aqua-checksums.json.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 6e87e746-2af4-4cbf-a8b4-6036acfae3cc
📒 Files selected for processing (7)
agent-skills/skills/atmos-migration/SKILL.mdagent-skills/skills/atmos-migration/references/from-aqua.mdagent-skills/skills/atmos-migration/references/from-asdf.mdagent-skills/skills/atmos-migration/references/from-homebrew-brewfile.mdagent-skills/skills/atmos-migration/references/from-tenv.mdagent-skills/skills/atmos-migration/references/from-tfenv.mdagent-skills/skills/atmos-migration/references/from-tofuenv.md
…gration-skill # Conflicts: # agent-skills/skills/atmos-migration/SKILL.md
Contributor
|
Note GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer. |
Dependency Review✅ No vulnerabilities or license issues found.Scanned FilesNone |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@agent-skills/skills/atmos-migration/references/from-homebrew-brewfile.md`:
- Around line 70-74: Update the candidate resolution guidance in the section
describing Homebrew formula mappings to use kubernetes-sigs/kubectl for kubectl,
matching the existing configured alias. Ensure this identifier is used
consistently for both brew info lookups and the Atmos toolchain owner/repo
value, replacing the conflicting kubernetes/kubectl reference.
In `@agent-skills/skills/atmos-migration/SKILL.md`:
- Around line 109-111: Update the Shell Integration section to distinguish
Homebrew from asdf-like shim or proxy managers: state that Homebrew exposes
tools through a global bin directory, while shim-based managers provide
per-directory resolution. Clarify that the Atmos toolchain resolves tools only
during an atmos <subcommand> invocation, without implying Homebrew offers
per-directory behavior.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 217ccb12-7835-4211-a1df-24815163506b
📒 Files selected for processing (7)
agent-skills/skills/atmos-migration/SKILL.mdagent-skills/skills/atmos-migration/references/from-aqua.mdagent-skills/skills/atmos-migration/references/from-asdf.mdagent-skills/skills/atmos-migration/references/from-homebrew-brewfile.mdagent-skills/skills/atmos-migration/references/from-tenv.mdagent-skills/skills/atmos-migration/references/from-tfenv.mdagent-skills/skills/atmos-migration/references/from-tofuenv.md
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #2877 +/- ##
==========================================
- Coverage 82.76% 82.76% -0.01%
==========================================
Files 1861 1861
Lines 180438 180438
==========================================
- Hits 149342 149334 -8
- Misses 23309 23315 +6
- Partials 7787 7789 +2
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
…uides - from-aqua.md: point command_aliases workaround at toolchain.proxies instead of toolchain.aliases, which only maps a short name to an owner/repo for lookup and cannot change a command's invoked name. - from-aqua.md: pin the mirrored aqua-registry with the dedicated `ref` field instead of baking the branch/tag into the `source` URL path, matching how pkg/toolchain/registry/loader.go actually resolves pins. - SKILL.md: describe atmos toolchain env/path as needing eval/export wrapping, and split the shim-based tools (asdf, aqua, tfenv, tofuenv, tenv) from Homebrew's global bin-directory model. - from-homebrew-brewfile.md: fix the kubernetes-cli formula mapping to kubernetes-sigs/kubectl, matching the file's own atmos.yaml example and the other reference files. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…ration source - Replace kubernetes-sigs/kubectl (not a real aqua-registry package) with kubernetes/kubectl across from-aqua.md, from-asdf.md, and from-homebrew-brewfile.md. Verified against the live aqua-registry index (aquaproj/aqua-registry registry.yaml): kubectl is a `type: http` package named kubernetes/kubernetes/kubectl with a documented `kubernetes/kubectl` alias, matching Atmos's own alias-resolution code (pkg/toolchain/registry/aqua/search.go) and the pre-existing demo/landing/fixtures/kubernetes/atmos.yaml example. - Clarify Shell Integration sections in from-aqua.md, from-asdf.md, from-tfenv.md, from-tofuenv.md, and from-tenv.md: `atmos toolchain env` (and per-invocation PATH injection) resolves tools from `.tool-versions` (the project-wide default) as well as `dependencies.tools` (a scoped override), not dependencies.tools alone -- matching pkg/toolchain/env.go, which reads only .tool-versions, and the canonical framing already in agent-skills/skills/atmos-toolchain/SKILL.md. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
what
atmos-migrationagent skill covering migration from external CLI tool-version managers to the built-in Atmos toolchain.agent-skills/skills/atmos-migration/references/, one per source tool:from-asdf.md,from-aqua.md,from-tfenv.md,from-tofuenv.md,from-tenv.md, andfrom-homebrew-brewfile.md.github_archivepackage type #2416, missing SemVer range constraints).atmos-migration/SKILL.md: new frontmatter references, a "Replace a Tool-Version Manager" routing section, an escalation link toatmos-toolchain, two new anti-patterns, and matching entries in Additional Resources.why
atmos-migrationskill only covered migrating Terraform/OpenTofu layouts, not tool-version-manager configs — an agent helping a user adopt the Atmos toolchain had no concrete recipe to follow.atmos toolchain env) up front avoids agents improvising inaccurate migration steps or missing that most of these tools auto-inject into the shell via a PATH shim, which the Atmos toolchain does not do by default.references
Summary by CodeRabbit