Skip to content

Commit ba9e6f3

Browse files
anandgupta42claude
anandgupta42
and
claude
committed
feat: add Kit system — shareable bundles of skills, MCP servers, and instructions
Introduces the Kit extension system that enables anyone — vendors, solution architects, team leads, individual engineers — to create and distribute shareable development setups. ## What's included **Core runtime** (`packages/opencode/src/kit/`): - `Kit` namespace with Zod schemas, state management, YAML loading - Trust tiers (`built-in`, `verified`, `community`) - Skill packs with activation modes (`always`, `detect`, `manual`) - Activate/deactivate lifecycle with full cleanup **11 CLI commands** (`packages/opencode/src/cli/cmd/kit.ts`): - `kit list`, `kit create`, `kit show`, `kit install`, `kit remove` - `kit activate` — one command: installs skills, configures MCP, enables - `kit deactivate` — clean removal (instructions + MCP config + active-kits) - `kit detect`, `kit search`, `kit status`, `kit validate` **TUI startup nudge** (`packages/opencode/src/cli/cmd/tui/thread.ts`): - Non-blocking detection on TUI startup - Shows one-line suggestion when matching kits found **JSONC-preserving config writes**: - Uses `jsonc-parser` `modify`/`applyEdits` to preserve user comments - MCP servers added on activate, removed on deactivate **Documentation** (`docs/`): - User guide: `docs/docs/configure/kits.md` (CLI reference, locations, tiers) - Author guide: `docs/docs/develop/kits.md` (full schema, tutorial, examples) - Ecosystem plan: `docs/PARTNER_ECOSYSTEM_PLAN.md` (strategy + simulation results) - Roadmap with planned features (`kit switch`, inheritance, `kit enforce`) ## Testing - 60/60 automated E2E tests passing (name validation, activate/deactivate lifecycle, MCP merge, JSONC preservation, detect, validate, install) - 10 stakeholder simulations across 5 scenarios (Snowflake, Dagster, dbt Labs, Airbyte, Healthcare, MSP consulting, OSS contributor, self-serve, enterprise) - 29 bugs found and fixed across 3 review rounds ## External - Kit content lives in `AltimateAI/data-engineering-skills` (merged PR #9) - Registry at `data-engineering-skills/registry.json` with 1 real entry - `dbt-snowflake` kit: 9 skills + dbt MCP server Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 384335d commit ba9e6f3

13 files changed

Lines changed: 3450 additions & 0 deletions

File tree

‎docs/PARTNER_ECOSYSTEM_PLAN.md‎

Lines changed: 939 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/docs/configure/index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,14 @@ Set up your warehouses, LLM providers, and preferences. For agents, tools, skill
3838

3939
[:octicons-arrow-right-24: MCP Servers](mcp-servers.md) · [:octicons-arrow-right-24: ACP Support](acp.md)
4040

41+
- :material-package-variant:{ .lg .middle } **Kits**
42+
43+
---
44+
45+
Bundles of skills, MCP servers, and instructions. Activate a kit to get a complete development setup for dbt, Snowflake, Dagster, and more.
46+
47+
[:octicons-arrow-right-24: Kits](kits.md)
48+
4149
- :material-palette:{ .lg .middle } **Appearance**
4250

4351
---

‎docs/docs/configure/kits.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# Kits
2+
3+
Kits bundle skills, MCP servers, and instructions into a single activatable unit. Instead of configuring each piece separately, activate a kit to get a complete development setup.
4+
5+
## Quick Start
6+
7+
```bash
8+
# List available kits
9+
altimate-code kit list
10+
11+
# Auto-detect kits for your project
12+
altimate-code kit detect
13+
14+
# Activate a kit
15+
altimate-code kit activate dbt-snowflake
16+
17+
# Check active kits
18+
altimate-code kit status
19+
20+
# Deactivate
21+
altimate-code kit deactivate dbt-snowflake
22+
```
23+
24+
## Installing Kits
25+
26+
Install kits from GitHub repositories or local paths:
27+
28+
```bash
29+
# From GitHub
30+
altimate-code kit install AltimateAI/data-engineering-skills
31+
32+
# From local path
33+
altimate-code kit install ./my-kits
34+
35+
# Install globally (available in all projects)
36+
altimate-code kit install AltimateAI/data-engineering-skills --global
37+
```
38+
39+
## KIT.yaml Format
40+
41+
Kits are defined in `KIT.yaml` files:
42+
43+
```yaml
44+
name: my-kit
45+
description: What this kit configures
46+
version: 1.0.0
47+
48+
# Skills to install
49+
skills:
50+
- source: "owner/repo"
51+
select: ["skill-a", "skill-b"]
52+
53+
# MCP servers to configure
54+
mcp:
55+
server-name:
56+
type: stdio
57+
command: ["uvx", "my-mcp-server"]
58+
env_keys: ["API_KEY"]
59+
description: "Server description"
60+
61+
# Instructions for every conversation
62+
instructions: |
63+
Project-specific conventions and rules.
64+
65+
# Auto-detection rules
66+
detect:
67+
- files: ["config.yaml"]
68+
message: "Detected my-tool — activate kit?"
69+
```
70+
71+
## What `kit activate` Does
72+
73+
When you activate a kit, it:
74+
75+
1. **Installs skills** from referenced repositories into `.opencode/skills/`
76+
2. **Configures MCP servers** by merging entries into your project's config file
77+
3. **Creates instruction files** at `.opencode/instructions/kit-<name>.md`
78+
4. **Registers the kit** as active in `.opencode/active-kits`
79+
80+
All changes are reversible with `kit deactivate`.
81+
82+
## Creating Your Own Kit
83+
84+
```bash
85+
altimate-code kit create my-team-standards
86+
```
87+
88+
This scaffolds `.opencode/kits/my-team-standards/KIT.yaml` with a template. Edit it, then activate:
89+
90+
```bash
91+
altimate-code kit activate my-team-standards
92+
```
93+
94+
### Validating
95+
96+
Check your kit for issues before sharing:
97+
98+
```bash
99+
altimate-code kit validate my-team-standards
100+
```
101+
102+
## Multiple Active Kits
103+
104+
You can activate multiple kits simultaneously. Their MCP servers are merged and instruction files coexist:
105+
106+
```bash
107+
altimate-code kit activate dbt-snowflake
108+
altimate-code kit activate my-team-standards
109+
altimate-code kit status # shows both
110+
```
111+
112+
## Trust Tiers
113+
114+
| Tier | Description |
115+
|------|-------------|
116+
| `built-in` | Ships with Altimate Code, maintained by the team |
117+
| `verified` | Published by official vendors, reviewed |
118+
| `community` | Created by anyone, use at your discretion |
119+
120+
## Kit Locations
121+
122+
Kits are discovered from:
123+
124+
1. **Project**: `.opencode/kits/` and `.altimate-code/kits/`
125+
2. **Global**: `~/.config/altimate-code/kits/`
126+
3. **Config paths**: `kits.paths` in your config file
127+
4. **Installed**: `~/.local/share/altimate-code/kits/`
128+
129+
## CLI Reference
130+
131+
| Command | Description |
132+
|---------|-------------|
133+
| `kit list` | List all available kits |
134+
| `kit list --json` | JSON output for scripting |
135+
| `kit list --detect` | Show only project-matching kits |
136+
| `kit create <name>` | Scaffold a new kit |
137+
| `kit show <name>` | Display full kit details |
138+
| `kit install <source>` | Install from GitHub or local path |
139+
| `kit activate <name>` | Install skills, configure MCP, enable |
140+
| `kit activate <name> --yes` | Skip confirmation prompt |
141+
| `kit deactivate <name>` | Remove from active kits, clean up |
142+
| `kit remove <name>` | Delete an installed kit |
143+
| `kit detect` | Find kits matching current project |
144+
| `kit search [query]` | Search the kit registry |
145+
| `kit status` | Show active kits |
146+
| `kit validate [name]` | Validate kit format and references |
147+
148+
## Sharing Kits
149+
150+
Share kits via Git repositories. The recommended structure:
151+
152+
```
153+
my-kits/
154+
kits/
155+
kit-a/KIT.yaml
156+
kit-b/KIT.yaml
157+
README.md
158+
```
159+
160+
Others install with: `altimate-code kit install owner/my-kits`
161+
162+
## Available Kits
163+
164+
See [data-engineering-skills](https://github.com/AltimateAI/data-engineering-skills) for the official kit registry.
165+
166+
## Roadmap
167+
168+
The kit system is actively evolving based on community feedback. Here's what's planned:
169+
170+
### Coming Soon
171+
172+
| Feature | Description | Status |
173+
|---------|-------------|--------|
174+
| **`kit switch`** | Switch between kits in one command (deactivate all, activate one) | Planned |
175+
| **Kit inheritance** | `extends: base-kit` to share conventions across kits | Planned |
176+
| **`kit update`** | Pull newer versions of installed kits from source | Planned |
177+
| **Registry expansion** | More built-in kits for BigQuery, Databricks, Airflow, Dagster | In progress |
178+
| **`kit enforce`** | CI command that fails if required kits are not active | Planned |
179+
180+
### Future
181+
182+
| Feature | Description |
183+
|---------|-------------|
184+
| **Auto-activation** | Automatically suggest or activate kits when detection rules match on project open |
185+
| **Kit locking** | Prevent deactivation of compliance-critical kits without admin override |
186+
| **Conflict detection** | Warn when two active kits have contradictory instructions |
187+
| **Kit analytics** | Activation counts and skill usage metrics for kit authors |
188+
| **MCP tool filtering** | Allow kits to expose only specific tools from an MCP server |
189+
190+
### Contributing to the Roadmap
191+
192+
Have a feature request? [Open an issue](https://github.com/AltimateAI/altimate-code/issues) with the `kit` label, or contribute directly to the [data-engineering-skills](https://github.com/AltimateAI/data-engineering-skills) repo.

‎docs/docs/develop/ecosystem.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,24 @@ altimate has a growing ecosystem of plugins, tools, and integrations.
1818
- **MCP**: Model Context Protocol servers
1919
- **ACP**: Agent Communication Protocol for editors
2020

21+
## Kits
22+
23+
Kits bundle skills, MCP servers, and instructions into shareable development setups. Anyone can create and distribute kits.
24+
25+
| Kit | Description |
26+
|-----|-------------|
27+
| [dbt-snowflake](https://github.com/AltimateAI/data-engineering-skills/tree/main/kits/dbt-snowflake) | Complete dbt + Snowflake setup |
28+
29+
Browse the [kit registry](https://github.com/AltimateAI/data-engineering-skills/blob/main/registry.json) for more.
30+
31+
### Creating Kits
32+
33+
See the [Kit documentation](../configure/kits.md) for the full guide, or run:
34+
35+
```bash
36+
altimate-code kit create my-kit
37+
```
38+
2139
## Community
2240

2341
- [GitHub Repository](https://github.com/AltimateAI/altimate-code): Source code, issues, discussions

0 commit comments

Comments
 (0)