Skip to main content

Declare and Lock AI Skills with Version Tracks

· 2 min read
Erik Osterman
Erik Osterman
Founder @ Cloud Posse

Shared AI skills need a record of where they came from and which revision a project uses. Declarative skill sources put that selection in Atmos configuration and lock each contributing repository for repeatable installation.

The Problem​

Installing a repository manually records an action, but does not give a team a shared declaration of the skills, plugins, clients, and versions their project needs. A marketplace may also reference plugins in other repositories, each advancing independently.

The Fix​

Declare sources under ai.skills and commit the resulting skills lock. Configuration commands edit those declarations independently of installation. Project installations have their own ownership records, and ordinary synchronization retains obsolete copies until you explicitly prune them.

Managed refs can use the version function to follow an Atmos version track.

How to Use It​

atmos ai skill add cloudposse/atmos --name cloudposse
atmos ai skill set cloudposse plugins '[atmos]'
atmos ai skill sync
atmos ai skill sync --frozen
atmos ai skill sync --check

Commit skills.lock.yaml and ignore .atmos/skills/. See the configuration reference for managed versions, local sources, explicit pruning, and recovery.

Migrating Claude Code Automation​

Existing MCP configurations previously caused Claude Code to approve every tool automatically. The atmos ai chat, atmos ai ask, and atmos ai exec commands now enforce Atmos tool permissions for requests Claude delegates to Atmos. Native and provider-preapproved requests follow Claude’s own permission policy. With the default confirmation policy, unattended runs fail when a tool needs approval.

Before upgrading CI jobs, set an explicit policy. For example, allow avoids prompts while still enforcing blocked tools on delegated requests:

ai:
  tools:
    mode: allow
    blocked: ["Edit", "Write"]

For narrower approvals, configure ai.providers.claude-code.allowed_tools with the specific Claude Code tools your job needs. The yolo mode bypasses all Atmos permission checks, including blocked tools. Edition pins do not restore the former implicit approval. See the automation migration guide.

Get Involved​

Report issues and share your workflows in the Atmos repository.