AI Stack Kit

Install AI skills, subagents, and hooks like npm packages - across Cursor, Claude, and Copilot.

Stop copy-pasting AI workflows between repos. Install them like packages.

Not a fan of the CLI? Use the VS Code / Cursor extension from your IDE — same spec.yaml workflow, no global install required.

A CLI to discover, install, apply and sync reusable AI capabilities from GitHub, npm, and registries - using a simple declarative spec.

Think: npm (distribution) + Terraform (setup) for AI dev environments

Install options

Method	Command
npm registry (public)	npm install -g ai-stack-kit
GitHub Packages	npm install -g @deb-adarsh/ai-stack-kit (requires .npmrc auth)
No global install	npx github:deb-adarsh/ai-stack-kit <command> (same as the Skill browser)
VS Code / Cursor extension	Install from Marketplace

VS Code extension

Install from the Marketplace (VS Code or Cursor) — same spec.yaml workflow as the CLI, no global install required.

• Activity Bar → Modules, Catalog, Outputs
• Commands: Initialize, Sync, Doctor, Search/Add, Switch Client
• Settings: aiStackKit.clientType, aiStackKit.githubToken, aiStackKit.dryRun, aiStackKit.autoSyncOnSave

See Extension guide for workflows.

---

🔄 Keeps your AI stack in sync

AI Stack Kit doesn’t just install modules — it stays aligned with the open-source ecosystem.

• Skill browser auto-rebuilt from upstream sources
• aistack catalog refresh pulls newly discovered modules into your spec
• No manual tracking of repos

Your AI stack evolves as open-source evolves.

---

⚡️ 10-second demo

npm install -g ai-stack-kit

aistack init
aistack search react
aistack add react-ui-expert
aistack sync

Your AI capabilities are now installed and configured in your IDE.

---

What happens after aistack sync

• Skills are installed into your project or user scope
• Subagents are generated and configured per client
• Prompts are derived automatically from the same source
• Hooks run as part of lifecycle (if configured)

Everything is generated from the same spec — no duplication.

---

🧠 Works out of the box

• Auto-detects your AI client (Cursor, Claude, Copilot)
• Installs and configures everything in the right place
• No manual wiring per tool

---

Why this exists

AI capabilities are scattered across GitHub repos, npm packages, and community lists.

There’s no standard way to:

• discover them
• install them
• keep them in sync across tools

AI Stack Kit introduces a spec-driven approach:

• sources.config.yaml → where to fetch from
• spec.yaml → what your project uses
• CLI + adapters → resolve and apply across tools

---

🔁 The workflow

search → add → sync

1. aistack init — create spec.yaml + sources.config.yaml (auto-detects Cursor / Copilot / Claude)
2. aistack search <query> — discover modules from configured catalogs (Skill browser too)
3. aistack skill add <name> — append to spec.yaml
4. aistack sync — resolve, install, and write IDE outputs from one spec

Run aistack doctor to validate your setup. See USER_GUIDE.md for full workflows.

---

Overview

AI Stack Kit lets you:

• 📦 Assemble AI capabilities (skills, subagents, and hooks) in spec.yaml—portable, versioned modules you can sync and apply as reusable intelligence.
• 🔄 Pull modules from GitHub, npm, registries, or local paths using sources.config.yaml.
• 🎯 Apply the same portable manifests through client adapters (Cursor, Copilot / VS Code settings, Claude, …)—output paths follow client.type, not copy-paste sprawl.
• 🔒 Version and lock dependencies like you would with package managers.
• 🚀 Share a single spec.yaml across machines and teammates.
• 🌐 Browse the Skill browser (listings sync from upstream via templates/sources.config.yaml — see Why this exists) and use catalog refresh to append new upstream names into modules: without rewriting your whole file.

---

Quick Start

npm install -g ai-stack-kit
aistack init
aistack sync

User guides — CLI · Extension

---

Who is this for?

• Developers using AI tools like Cursor, Claude, or Copilot
• Teams that want consistent AI setups across projects
• Builders creating reusable AI skills, agents, or workflows

---

Not for

• One-off prompt usage
• Simple ChatGPT workflows
• Non-technical users

AI Stack Kit is designed for teams and developers managing reusable AI capabilities.

---

Architecture

High-Level Design

┌─────────────────────────────────────────┐
│              CLI Layer                  │
│  (init, install, apply, sync)           │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│           Core Engine                   │
│  (orchestration, resolution)            │
└──┬───────┬─────────┬──────────┬────────┘
   │       │         │          │
   ▼       ▼         ▼          ▼
┌─────┐ ┌─────┐ ┌─────┐ ┌─────────┐
│Src  │ │Reg  │ │Adp  │ │ Storage │
│     │ │     │ │     │ │         │
└─────┘ └─────┘ └─────┘ └─────────┘

Key Interfaces

1. SkillSource: Fetch skills from GitHub, npm, registries, or local files
2. RegistryProvider: Query and publish to skill registries
3. IDEAdapter: Apply skills to different IDEs (Cursor, VSCode, etc.)

Design Principles

• ✅ Pluggable: Easy to add new sources, registries, and IDEs
• ✅ Loose Coupling: Modules communicate via interfaces
• ✅ Single Responsibility: Each module has one clear purpose
• ✅ Testable: Clear boundaries enable mocking and isolation

---

Project structure

Repository layout and module boundaries: ARCHITECTURE.md.

---

Key Features

1. Pluggable Sources

Fetch skills from multiple sources:

• GitHub: Public/private repos
• npm: npm packages
• Registry: Custom registries (like npm registry)
• Local: File system paths

2. Version Management

• Semantic versioning (^1.0.0, ~2.1.0, latest)
• Lock files for reproducibility
• Dependency resolution
• Conflict detection

3. IDE Adapters

spec.yaml → client.type (cursor, copilot, claude) plus optional client.installScope: project (default) writes under the repo; user writes under your home directory for global tooling.

Skills — each resolved skill becomes a folder with SKILL.md (and any bundled paths preserved). There is no separate filename convention beyond normal skill packaging.

Scope	Cursor	Copilot	Claude
Personal / global (installScope: user)	~/.cursor/skills/	~/.copilot/skills/	~/.claude/skills/
Repo / project (default)	.cursor/skills/	.github/skills/	.claude/skills/

Subagents — generated agent files:

Scope	Cursor	Copilot	Claude
Personal / global	~/.cursor/agents/*.md	~/.copilot/agents/*.agent.md	~/.claude/agents/*.md
Repo / project	.cursor/agents/*.md	.github/agents/*.agent.md	.claude/agents/*.md

The *.agent.md pattern (basename: ., -, _, a-z, A-Z, 0-9 only before the suffix) is GitHub Copilot only. Cursor and Claude emit ordinary *.md agents.

Prompt sets — same payload as skills (no extra fetch) — Prompt files are not downloaded on their own. After each skill is resolved and fetched once, the normalizer derives prompts from that same in-memory payload (e.g. SKILL.md → instruction prompt; skill.json / manifest description → optional short system summary when present). aistack sync / apply then emits those files next to the skill trees and agents; agents carry promptIds wired by each adapter.

Scope	Cursor	Copilot	Claude
Repo / project (default)	.cursor/prompts/*.md	aistack.copilot.promptSnippets in project .vscode/settings.json (id → body)	.claude/prompts/*.md, .claude/system-bundle.aistack.md, .claude/README.aistack.md
Global (installScope: user)	~/.cursor/prompts/*.md	same promptSnippets merge at project root (tree outputs still target ~/.copilot/)	~/.claude/prompts/*.md (+ Claude bundle/readme under ~/.claude/)

Copilot + VS Code: .vscode/settings.json is still merged under the aistack key at the project root (e.g. promptSnippets), even when skill/agent trees target ~/.copilot/ via installScope: user.

4. Lifecycle Hooks

Run commands at different stages:

• preInstall / postInstall
• preApply / postApply
• preSync / postSync

5. Caching

• Content-addressable cache (like Git)
• Checksum verification
• Offline mode support

6. Skill browser & catalog refresh

• Hosted UI: filters and copy-paste CLI commands (live demo).
• aistack catalog refresh: compare configured catalogs with spec.yaml and append missing modules under modules: using a YAML-safe merge (new rows default to enabled: false; backs up spec.yaml first).

---

Common commands

aistack init
aistack validate
export GITHUB_TOKEN=ghp_…   # recommended when searching GitHub-backed catalogs
aistack search <query>
aistack skill add [name]   # or: aistack add [name]
aistack catalog refresh --write
aistack sync

For the full command list — skill / subagent / hook, catalog refresh flags, install / apply, registry, and maintenance — see CLI guide.

---

Documentation

📚 Architecture

• ARCHITECTURE.md: Single architecture reference — diagrams, dependency rules, actual repository layout, interface shapes, pipeline flows, configuration examples, extension points, CLI reference, and ops concerns (performance, security, errors).

• CONTRIBUTING.md: How to contribute—including extending the default catalog (templates/sources.config.yaml) for the CLI and Skill browser.

• USER_GUIDE.md: Hub — CLI and extension guides

• CLI guide: Install, commands, env vars, troubleshooting

• Extension guide: VS Code / Cursor sidebar workflows

• VS Code extension (Marketplace): Install the sidebar UI

📝 Configuration

• templates/spec.yaml: Template spec file
• templates/sources.config.yaml: Default catalog sources

---

Development

Build from source, run tests, extend sources/adapters, or publish the extension: CONTRIBUTING.md.

---

Comparison to Similar Tools

Feature	AI Stack Kit	npm	Terraform	kubectl
Declarative Config	✅	❌	✅	✅
Version Locking	✅	✅	✅	❌
Multiple Sources	✅	⚠️	⚠️	❌
IDE Agnostic	✅	❌	N/A	N/A
Dependency Resolution	✅	✅	✅	❌
Lifecycle Hooks	✅	✅	✅	❌

---

Roadmap

Snapshot of what’s in the repo today and what might come next—adjust as the project evolves.

Area	Status
CLI	Shipped: init, search, typed skill / subagent / hook, add, sync, catalog refresh, validation, etc. Some commands are still placeholders (e.g. update, clean, registry login / publish).
spec.yaml	Load + Zod validation, apply pipeline, modules merge (skills + modules).
Sources	GitHub fetch/install + npm packages; dynamic catalogs from sources.config.yaml (GitHub tree + npm tree providers).
Discovery	Composite registry, hybrid search, catalog refresh for additive spec merges.
IDE outputs	Cursor, Copilot (VS Code settings path), Claude client adapters; VS Code extension for in-editor sync and catalog browse.
Skill browser	Static web app + catalog.json build + GitHub Pages deploy (weekly cron + pushes).
Hosted registry product	No dedicated public registry server or npm-like publish flow yet—discovery is aggregate-from-upstreams plus local spec.

Possible next steps (community-driven, not commitments): richer VS Code story, real registry/auth, watch mode, polish placeholders, tests/CI depth—track via Issues and CONTRIBUTING.md.

---

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

---

License

Licensed under the Apache License 2.0. See LICENSE.

---

Support

• 📖 Documentation: User guides · ARCHITECTURE.md
• 🧩 VS Code extension: Visual Studio Marketplace (deb-adarsh.ai-stack-kit)
• 🐛 Issues: GitHub Issues
• ✉️ Maintainer: debadarsh7@gmail.com

---

Acknowledgments

Inspired by:

• npm: Registry abstraction and versioning
• Terraform: Declarative infrastructure
• kubectl: CLI user experience
• Cursor: IDE extensibility

Built with ❤️ for developers who want portable, reproducible IDE configurations.