This document describes how aix manages remote Git repositories containing shareable resources.

Repositories are remote Git repos containing shareable aix resources--skills, commands, agents, and MCP configurations. They enable teams to distribute curated tooling across projects and share best practices through versioned, installable packages.

1. Discoverability - Browse and search resources across multiple repositories
2. Version control - Resources are tracked via Git, enabling updates and rollbacks
3. Isolation - Each repository is cloned independently, avoiding conflicts
4. Simplicity - Standard Git semantics for fetching and updating

A valid aix repository contains one or more resource directories:

my-aix-repo/
|-- skills/           # Skill definitions
 |   |-- code-review/
 |    |   `--- SKILL.md
 |   `--- security-audit/
 |       `--- SKILL.md
|-- commands/         # Slash command definitions
 |   |-- deploy/
 |    |   `--- command.md
 |   `--- test-coverage/
 |       `--- command.md
|-- agents/           # Agent definitions
 |   |-- go-expert.md
 |   `--- security-reviewer.md
`--- mcp/              # MCP server configurations
    |-- github.json
    `--- postgres.json

All directories are optional. A repository may contain only skills, only agents, or any combination.

Repositories are tracked in the aix configuration file. Each registered repository has the following fields:

{
  "repositories": [
    {
      "name": "company-tools",
      "url": "https://github.com/acme/aix-resources.git",
      "path": "/Users/dev/.cache/aix/repos/company-tools",
      "added_at": "2024-01-15T10:30:00Z"
    },
    {
      "name": "personal",
      "url": "[email protected]:user/my-aix-tools.git",
      "path": "/Users/dev/.cache/aix/repos/personal",
      "added_at": "2024-02-20T14:45:00Z"
    }
  ]
}

aix repo add <url>

Clones the repository and registers it for use. The repository name is derived from the URL (e.g., github.com/acme/tools becomes tools).

Flags:

Examples:

# Add from HTTPS URL
aix repo add https://github.com/acme/aix-resources.git

# Add from SSH URL with custom name
aix repo add [email protected]:user/tools.git --name personal-tools

# Add from git protocol
aix repo add git://github.com/org/shared-skills.git

aix repo list

Displays all registered repositories with their URLs and local paths.

Output:

NAME            URL                                         PATH
company-tools   https://github.com/acme/aix-resources.git   ~/.cache/aix/repos/company-tools
personal        [email protected]:user/my-aix-tools.git        ~/.cache/aix/repos/personal

aix repo update [name]

Pulls the latest changes from the remote. If no name is provided, updates all registered repositories.

Examples:

# Update a specific repository
aix repo update company-tools

# Update all repositories
aix repo update

aix repo remove <name>

Unregisters the repository and deletes the local clone.

Flags:

Examples:

# Remove and delete local files
aix repo remove old-tools

# Unregister but keep local clone
aix repo remove archived-tools --keep-files

# Register the repository
aix repo add https://github.com/acme/aix-resources.git

# List available skills from all repositories
aix skill list --source=repos

# Install a specific skill
aix skill install company-tools:code-review

# Find all security-related resources
aix search security --source=repos

# List agents from a specific repository
aix agent list --repo=company-tools

# Pull latest changes
aix repo update company-tools

# Reinstall to pick up updates
aix skill install company-tools:code-review --force

Repository names must conform to the following rules:

Valid names:

• company-tools
• my-skills
• aix-v2-resources
• tools

Invalid names:

• Company-Tools (uppercase)
• -tools (leading hyphen)
• my--tools (consecutive hyphens)
• my_tools (underscore not allowed)
• 123-tools (must start with letter)

Repository URLs must use one of the following protocols:

URLs must point to a valid Git repository. The .git suffix is optional but recommended for clarity.

# Repository not registered
$ aix repo update nonexistent
Error: repository not found: nonexistent

# Name already in use
$ aix repo add https://github.com/other/tools.git --name company-tools
Error: name collision: repository 'company-tools' already exists

# Invalid URL
$ aix repo add not-a-valid-url
Error: invalid URL: must use https://, git@, or git:// protocol

# Invalid name
$ aix repo add https://github.com/org/repo.git --name Invalid_Name
Error: invalid name: must be lowercase alphanumeric with hyphens (e.g., 'my-repo')

Repositories are cloned to ~/.cache/aix/repos/<name>/ (Linux/macOS) or %LOCALAPPDATA%\aix\cache\repos\<name>\ (Windows) by default. This location relies on the XDG Cache Home.

When installing resources, the syntax <repo>:<resource> specifies which repository to use:

aix skill install company-tools:code-review
#                 `------+-----+ `-----+----+
#                   repo name    skill name

If no repository is specified, aix searches all registered repositories and uses the first match.

All Git operations use the system's git binary. Authentication is handled through standard Git mechanisms (SSH keys, credential helpers, etc.).

When adding or updating a repository, aix validates the repository content and displays warnings for issues that may cause problems during resource installation.

$ aix repo add https://github.com/example/skills.git
[OK] Repository 'skills' added from https://github.com/example/skills.git
  Cached at: ~/.cache/aix/repos/skills

[WARN] Validation warnings:
  skills/broken/SKILL.md: invalid frontmatter: yaml: line 3: did not find expected '-' indicator
  mcp/server.json: invalid JSON: unexpected end of JSON input

• Missing optional directories (e.g., mcp/ when the repo only contains skills) do not generate warnings
• Validation warnings do not block the add or update operation
• Warnings help identify issues before attempting to install resources