Skip to content

Blogs

Axon: One CLI to Control AI Agent Skills & Rules Across Every Editor

AI coding agents use different folders and file formats for skills and rules. Axon provides a single central hub and CLI to manage, stage, and symlink skills across Cursor, Claude Code, Gemini/Antigravity, Devin, Codex, Windsurf, and Copilot.

All blogs
1 min readAI AgentsCLIDeveloper ToolsAxonWorkflows

Every AI coding tool — Cursor, Claude Code, Gemini/Antigravity, Devin, Codex, Windsurf, and GitHub Copilot — has its own way of defining skills and coding rules.

Some use .cursor/rules/name.mdc. Others use .claude/skills/name/SKILL.md or .agents/rules/name.md. If you work across multiple agents or repositories, keeping your prompt instructions, coding standards, and runbooks in sync quickly becomes a copy-paste mess.

Axon solves this. It acts as a universal Skill & Constitution Management System. You write or stage your skills once in a central hub (~/.axon/), and Axon automatically symlinks them into every agent format your project needs.

Paired with community rulebooks like ai-assets, you can onboard any repository to production-ready AI skills in seconds.

Universal AI Agent CLIv0.2.0 Ready

Stop Copy-Pasting AI Prompts Across Agents

Cursor uses .mdc files. Claude Code uses .claude/skills/. Gemini & Antigravity use .agents/rules/. Axon connects them all from a single central hub.

GitHub RepositoryArchitecture Deep Dive
Important Safety Promise: Staging Does NOT Mutate Your Project!

Importing or adding skills with axon add or axon import is 100% safe. It only places raw files in your central hub (~/.axon/). Absolutely zero files in your repository break or change until you explicitly run axon enable.

🟢 Safe Staging
axon add / axon import

Stores files in central hub. Zero project mutation.

🟡 Minor Change
axon enable skill

Creates repo symlink in skills folder. Skill is now available.

🔴 Major Change
enable principle / activate

Alters always-on rules or enables autonomous LLM execution.

What Problem Does Axon Solve?

Modern AI development often involves using multiple tools — Cursor for coding, Claude Code for CLI tasks, Antigravity for subagent automation, or Devin for background refactoring. Managing your instructions across repositories means duplicating files, risking prompt drift, and struggling with incompatible folder formats.

Architecture Comparison: Fragmented Rules vs. Axon Central Hub
Before Axon (Fragmented & Out of Sync)

Each AI agent expects different paths, file extensions, and folder structures. You end up copying files into multiple directories across every repo.

.cursor/rules/formatting.mdcCursor format
.claude/skills/formatting/SKILL.mdClaude format
.agents/skills/formatting/SKILL.mdAntigravity format
.devin/skills/formatting/SKILL.mdDevin format
❌ Result: Out-of-sync prompts, duplicated files, high maintenance.
With Axon (Universal Staging Hub)

Keep a single source of truth in ~/.axon/. Axon creates exact, agent-aware symlinks into your project automatically.

~/.axon/ (Central Hub)
├── skills/fast-format/SKILL.md
├── principles/code-standards.md
└── workflows/pr-review.md
Smart Symlinks → Project Agent Directories
.cursor/rules/
.claude/skills/
.agents/skills/
✅ Result: Edit once, available everywhere instantly!
Ready-to-Use Skills & Architecture Deep Dives

Discover all 23 pre-built skills in our catalog or read our architectural deep dive on Principles vs Skills vs Workflows.

23 AI Skills CatalogArchitecture Deep Dive

Core Axon Workflow Commands

1. Install Axon

The automated installation script creates an isolated Python virtual environment at ~/.axon-env/ and links the executable to ~/.local/bin/axon. Zero global package pollution.

Install Script
$
curl -sSL https://raw.githubusercontent.com/aayushlalroy/axon/main/install.sh | bash📋

2. Stage Skills & Principles (axon import / axon add)

🟢 SAFE STAGING (0 PROJECT CHANGES)

Before initializing project repos or enabling skills, stage them into your central hub (~/.axon/). Importing or adding skills only populates your central staging area — zero files in your current project repository are mutated until you run axon enable.

Option A: Bulk Import Open-Source Skill Library (ai-assets)

Clone aayushlalroy/ai-assets and bulk stage battle-tested skills into ~/.axon/:

Import ai-assets
$
git clone https://github.com/aayushlalroy/ai-assets.git📋
$
cd ai-assets && axon import . --config axon-import.yaml📋
Option B: Stage Your Own Custom Skill or Principle

Stage a local folder or .md file into the central hub with a custom name:

Stage Custom Skill
$
axon add path/to/my-skill-folder --type skill --name=my-skill📋
$
axon add path/to/coding-standards.md --type principle --name=code-standards📋

3. Initialize Project Repository (axon init)

Scaffold agent configuration directories for your repository. Axon automatically creates the required folder structures for all supported AI agents (.cursor/rules/, .claude/skills/, .agents/skills/, etc.).

Initialize Repository
$
cd your-project📋
$
axon init📋

4. Inspect Hub & Project State (axon list / axon list --all)

Inspect what skills and principles are staged in your central hub versus what is actively enabled in your current project repository.

axon list

Lists all skills and principles currently enabled in the active project repository.

axon list --all

Lists all skills and principles staged in your central hub (~/.axon/), showing enabled/disabled status across repositories and activation state.

Inspection Commands
$
axon list📋
$
axon list --all📋

5. Enable & Disable (axon enable / axon disable)

Link or unlink staged items from your central hub into the current project repository.

🟡 Enabling a Skill: Minor Impact

Running axon enable my-skill creates agent-specific symlinks in your repo. The skill is now available in your repository.

🔴 Enabling a Principle: Major Impact

Running axon enable principle skill-attribution adds an always-on constitution rule to agent rules, modifying LLM behavior across every conversation turn.

Enable & Disable Commands
$
axon enable my-skill📋
$
axon enable principle skill-attribution📋
$
axon disable my-skill📋

6. Activate & Deactivate (axon activate / axon deactivate)

🔴 MAJOR IMPACT (MODEL AUTO-INVOCATION)

Control model auto-invocation behavior for skills and principles. Activating or deactivating is a Major Impact change because it controls whether the LLM is allowed to auto-invoke skills autonomously on intent match.

Activate & Deactivate Commands
$
axon activate skill clarify-first📋
$
axon deactivate skill clarify-first📋
Command Lifecycle & Key Differences Breakdown
Addition: add/import → enable → activate
1. axon add / axon import (Stage to Hub)

Copies raw skill/principle files into your central hub at ~/.axon/. Zero project mutation! Absolutely nothing changes in your project repository until enabled.

2. axon enable (Link to Project Repo)

Creates atomic symlinks in your current project repository (e.g. .cursor/rules/, .claude/skills/). The skill is now active in this repository for human or agent invocation.

3. axon activate (Enable Auto-Invocation)

Updates frontmatter (disable-model-invocation: false). Allows the AI model to trigger the skill autonomously on matching user intent without explicit prompt invocation.

Removal: deactivate → disable → remove
1. axon deactivate (Disable Auto-Trigger)

Sets disable-model-invocation: true. Stops the LLM from auto-triggering the skill autonomously, but leaves the skill symlinked in the project for manual use (saves LLM tokens).

2. axon disable (Unlink from Project Repo)

Removes project symlinks from the current repository. The canonical skill source stays 100% safe inside ~/.axon/ so you can enable it again later.

3. axon remove (Purge from Central Hub)

Completely deletes the skill or principle from your central ~/.axon/ hub and unlinks it across all projects.

8. Uninstall Axon CLI

Need to uninstall? Axon includes a script to clean up binary symlinks and virtual environment. You can choose to keep your staged skills or purge everything.

Uninstall Commands
$
curl -sSL https://raw.githubusercontent.com/aayushlalroy/axon/main/uninstall.sh | bash📋
$
curl -sSL https://raw.githubusercontent.com/aayushlalroy/axon/main/uninstall.sh | bash -s -- --keep-data📋
$
curl -sSL https://raw.githubusercontent.com/aayushlalroy/axon/main/uninstall.sh | bash -s -- --purge📋

Supported AI Agents Matrix

Supported AI Agents & Format Adapters7 Agents Supported
Cursor
.cursor/rules/*.mdc
Flat .mdc rules
Claude Code
.claude/skills/*/SKILL.md
Folder & flat .md
Gemini / Antigravity
.agents/skills/*/SKILL.md
Folder & flat .md
Devin
.devin/skills/*/SKILL.md
Folder & flat .md
Codex
.codex/skills/*/SKILL.md
Folder & flat .md
Windsurf
.windsurf/rules/*.md
Flat .md rules
GitHub Copilot
.github/instructions/*.md
Flat instructions

🔍 Exhaustive Architecture & Advanced Reference

In-Depth Guide

An exhaustive reference on Axon's hub-and-spoke architecture, lifecycle state transitions, AI agent adapter formats, CLI command options, and hierarchical configuration schemas.

Axon Staged Asset Lifecycle & State Machine

Visualizing asset flow from source repos, central staging (~/.axon/), symlinked enablement, to agent discovery.

1. STAGED HUB (~/.axon/)
Safe Central Storage

Assets are added using axon add <path> or bulk-imported with axon import . into ~/.axon/skills/, principles/, or workflows/. Zero changes occur in project repos until enabled.

↓ axon enable [TYPE] NAME (creates agent symlinks)
2A. ENABLED (LOCAL REPO)Project Symlink Created

Axon links staged assets into .cursor/rules/, .claude/skills/, .agents/skills/, etc. Editing in ~/.axon/ updates all enabled repos automatically.

2B. ENABLED (GLOBAL)User Global Directory

Passed with --global to enable assets in machine-wide agent folders (~/.cursor/rules/, ~/.claude/, ~/.gemini/config/).

↓ axon activate [TYPE] NAME (turns on auto-invocation / detached override)
3. ACTIVATED (AGENT DISCOVERABLE & AUTO-INVOCABLE)
Active AI Discovery

Activating sets disable-model-invocation: false (or creates an un-linked physical local file copy if custom repo tweaks are needed). The AI agent detects the skill autonomously on user intent!

axon deactivate → Reverts override back to symlink / turns auto-invocation offaxon disable → Removes target symlinks cleanly

1. Asset Lifecycle States & Transitions

Axon enforces a clean state machine for every asset across your machine:

🟢 STAGED (~/.axon/)

Stored in central hub (~/.axon/{skills,principles,workflows}). Canonical source of truth across all repos on your machine.

🟡 ENABLED (Local / Global)

Axon creates target symlinks in initialized agent directories (.cursor/rules, .claude/skills, etc.). Changes in ~/.axon/ reflect instantly.

🟣 ACTIVATED (Auto-Invocable)

Enables LLM auto-invocation (disable-model-invocation: false) or detaches symlink into a local physical override file for project-specific customization. Discoverable by agents!

🔵 DEACTIVATED

Disables auto-triggering or reverts physical local overrides back to managed symlinks pointing to ~/.axon/.

🟠 DISABLED

Symlinks are safely unlinked from project repositories. The staged asset stays 100% intact in ~/.axon/.

🔴 REMOVED

Purges item from ~/.axon/ hub and cleans up all target symlinks, local overrides, and config references.

2. Architecture & AI Agent Mechanics

Axon relies on a Hub-and-Spoke model. Staged assets in ~/.axon/ act as single sources of truth. Agent adapters dynamically convert canonical formats into whatever format each AI IDE or CLI expects:

Folder Skills
folder_skill_md

Used by Devin, Claude Code, Gemini/Antigravity, Codex. Symlinks whole folder containing SKILL.md and auxiliary scripts.

Flat MDC Rules
flat_mdc

Used by Cursor. Symlinks SKILL.md as .cursor/rules/name.mdc and compiles principles into .cursorrules.

Flat Markdown Rules
flat_md

Used by Windsurf and Copilot. Symlinks skills or principles as flat .md instruction files.

3. Exhaustive CLI Command Reference

All 15 CLI commands supported by Axon with full arguments, options, and tooltips:

Project & Environment Commands
$
axon setup📋
$
axon version📋
$
axon update --version v1.1.0📋
$
axon agents📋
$
axon init --agent cursor,devin📋
$
axon deinit --agent cursor -y📋
Staging & Import Commands
$
axon add skills/my-skill --type skill📋
$
axon add schema-sync.md --skill openapi-first📋
$
axon import . --config axon-import.yaml --dry-run📋
$
axon remove skill my-old-skill -y📋
Enable, Disable, Activate & Sync Commands
$
axon enable skill clarify-first --agent cursor📋
$
axon enable principle skill-attribution --global📋
$
axon disable skill clarify-first📋
$
axon activate skill clarify-first📋
$
axon deactivate skill clarify-first📋
$
axon list --all📋
$
axon sync -y📋

4. Hierarchical Configuration Schema & Storage Reference

Axon resolves configuration in order of precedence: Project (axon-config.yaml) > Global (~/.axon/config.yaml) > Built-in Defaults.

# Complete axon-config.yaml Schema Reference

# Managed agent frameworks scaffolded during 'axon init'
enabled_agents:
  - gemini
  - cursor
  - devin
  - windsurf
  - codex
  - copilot

# Operational defaults
defaults:
  name_source: auto        # Strategies: auto | frontmatter | folder | file
  scope: local             # Scopes: local | global
  ignore_patterns:         # Globs ignored when staging or importing
    - "README.md"
    - "INDEX.md"
    - ".DS_Store"
    - "*.tmp"

# 'axon import' overrides
import:
  name_source: auto
  ignore_patterns:
    - "README.md"
    - "INDEX.md"
    - "AGENTS.md"

# Skill staging options
staging:
  ignore_readme: true      # Exclude README.md files inside skill directories

Ready to Supercharge Your AI Agent Workflow?

Explore the 23 pre-built skills in our catalog or read the architectural deep dive on Principles vs Skills vs Workflows.

Explore AI Skills CatalogArchitecture Deep Dive