aivcraft

AIV Craft

The engineering tool for software engineers to effortlessly manage skills and configurations in the multi-agent era.

The Core Problem

If you're like us, you probably switch between multiple AI Agents (like Claude Code, codex, Code Buddy) in your daily workflow. You've also likely experienced the friction:

• Configuration Chaos: Imagine needing to configure a "execute Python script" skill for three different mainstream SWE Agents:
  • For Anthropic's Claude Code, you need to create a skill folder containing a SKILL.md file to describe the skill instruction, and then place this folder into the ~/.claude/skills directory.
  • For Tencent's Code Buddy, you'd write the same skill instruction as a Markdown file, place it in the ~/.codebuddy/agents directory, and define its metadata in the Frontmatter.
  • For OpenAI's Codex Agent, you need to create an AGENTS.md file and describe the skill within it, ensuring the Agent can read and understand it.

  Each tool speaks a completely different "skill dialect," making knowledge and configuration entirely non-reusable.

• Knowledge Silos: Great skills and prompts remain trapped on individual machines, with no easy way to share, discover, or promote them across the team.
• Lack of Engineering Practices: The whole process relies on an "artisanal" approach, lacking versioning, automation, and reproducibility.

What is AIV Craft?

AIV Craft is the "Homebrew for AI Agent Skills," built on a "Configuration as Code" philosophy.

It allows you to manage all your agent skills, repositories, and environment settings from a single, declarative aivcraft.yml file. A single aivcraft CLI command then applies these configurations, freeing you from the manual, repetitive setup work.

✨ Features

• Declarative & Reproducible: Use a single aivcraft.yml as the source of truth to ensure a consistent environment for your entire team.
• Cross-Agent Compatibility: With the "Installer" architecture, one set of skills can be seamlessly applied to different agents like Claude Code, codex, etc.
• Open Skill Ecosystem: Supports an official central repository as well as custom third-party or private skill repositories.
• Layered Configuration: Merges a global (~/.aivcraft/...) and a project-specific (aivcraft.yml) configuration, balancing personal habits and team standards.
• CLI + GUI: Provides a powerful aivcraft CLI for automation, supplemented by an intuitive GUI for browsing and management (GUI planned for a future release).

🚀 Quick Start (MVP)

Step 1: Install

We recommend macOS users install via Homebrew.

macOS (Recommended)

# Add our tap (assuming the tap repo is named homebrew-aivcraft)
brew tap kofj/aivcraft
brew install aivcraft

Linux / macOS (Alternative) You can also use our installation script:

curl -fsSL https://raw.githubusercontent.com/kofj/aivcraft/main/install.sh | sh

Windows Support for Winget, Scoop, or an MSI installer is planned for a future release.

Step 2: Initialize Project

In your project directory, generate a sample aivcraft.yaml file.

aivcraft init

An example aivcraft.yaml will be created:

# aivcraft.yaml

# 1. Declare which agents this project uses
agents:
  - claude-code
  - aider

# 2. Declare which skills this project needs
skills:
  # Install from the official 'center' repository
  - center:git/pro-commit-message
  # You can also add your own skill repositories (defined in your global config)
  # - my-repo:frontend/react-helper

Step 3: Apply Configuration

AIV Craft will automatically configure everything for you.

aivcraft apply

📖 How It Works

AIV Craft's core consists of a declarative execution engine and "Installer" plugins.

1. Layered Configuration: aivcraft intelligently merges the global (~/.aivcraft/config.yml) and project-specific (aivcraft.yml) configurations, with project settings taking precedence.
2. Installer Mechanism: When apply is executed, AIV Craft calls the dedicated "Installer" plugin for each agent listed in the agents section. For example, the "codex Installer" knows how to read and modify .aider.conf.yml, while the "Claude Code Installer" knows how to operate on the ~/.claude/skills directory. This makes AIV Craft easily extensible to support any new agent.

CLI Reference (Core)

• aivcraft init: Initializes a project-level aivcraft.yml file in the current directory.
• aivcraft apply: Applies the current project and global configurations to sync all declared agents.
• aivcraft repo add <name> <url>: Adds a new skill repository to your global configuration.
• aivcraft repo list: Lists all currently active skill repositories (merged from global and project configs).
• aivcraft install --global <skill_name>: Installs a global skill that will be active in all your projects.
• aivcraft config set --global <key> <value>: Sets a global configuration key, e.g., model gpt-4o or api_keys.openai env(OPENAI_API_KEY).

🛣️ Roadmap

AIV Craft is in its early stages of development as we focus on delivering the core MVP features. In the future, we hope to explore and evolve in the following directions:

• Broader Agent Support: Provide official installers for more mainstream AI Agents (e.g., Cursor).
• Richer Skill Ecosystem: Grow the quantity and quality of skills in the official central repository and lower the barrier for community contributions.
• Enhanced GUI Experience: Deliver a mature, easy-to-use graphical interface for skill discovery, management, and configuration.
• Team Collaboration Features: Explore solutions for team-oriented skill sharing, permission management, and service hosting (e.g., MCP).

🤝 Contributing

AIV Craft is an open-source project, and we welcome contributions of all kinds!

• Submit an Issue: Share problems you've encountered or ideas for new features.
• Develop an Installer: Contribute code to AIV Craft, especially "Installer" plugins for new agents.
• Contribute a Skill: Submit high-quality, general-purpose skill packages to our official central repository.