@levi-putna/agent-kit

A configuration manager for AI coding agents. Install skills and MCP servers from any public GitHub repo into Claude, Cursor, Windsurf, and other agents, globally or per project.

Requirements: Node.js 18 or later

For users

Install

Recommended: run via npx with the scoped package name and @latest. This always uses the current release and avoids clashes with other npm packages named agent-kit:

npx @levi-putna/agent-kit@latest add owner/repo

Use the same prefix for any command:

npx @levi-putna/agent-kit@latest list owner/repo
npx @levi-putna/agent-kit@latest installed
npx @levi-putna/agent-kit@latest update

Alternative: install globally if you prefer a short command on your PATH:

npm install -g @levi-putna/agent-kit@latest

After a global install, the binary on your PATH is agent-kit. Only install the @levi-putna/agent-kit package to get this tool.

Commands

Command	Description
`npx @levi-putna/agent-kit@latest list <owner/repo>`	Browse skills and MCP servers available in a repo
`npx @levi-putna/agent-kit@latest add <owner/repo> [options]`	Install skills and/or MCP servers
`npx @levi-putna/agent-kit@latest installed`	List what is installed in the current project or globally
`npx @levi-putna/agent-kit@latest update`	Pull the latest versions of project-installed skills from source repos
`npx @levi-putna/agent-kit@latest remove <name>`	Remove a skill or MCP server by name

Using a skills repo

Point @levi-putna/agent-kit at any public GitHub repo that follows the expected layout. The repo is referenced as owner/repo:

npx @levi-putna/agent-kit@latest list owner/repo
npx @levi-putna/agent-kit@latest add owner/repo

To use a specific branch instead of main:

npx @levi-putna/agent-kit@latest add owner/repo@develop

`add` options

Option	Short	Description
`--skill <name>`		Install a specific skill (skips the interactive picker)
`--mcp <name>`		Install a specific MCP server (skips the interactive picker)
`--global`	`-g`	Install globally (available across all projects)
`--project`	`-p`	Install to the current project
`--agent <name>`		Target a specific agent (use with `--global` or `--project`)

If you omit --global and --project, @levi-putna/agent-kit detects which agents are present in your project (.claude, .cursor, .windsurf, etc.) and walks you through scope and selection interactively.

Examples

# Interactive: browse and pick skills/MCP servers
npx @levi-putna/agent-kit@latest add owner/repo

# Install a specific skill
npx @levi-putna/agent-kit@latest add owner/repo --skill code-review

# Install a specific MCP server
npx @levi-putna/agent-kit@latest add owner/repo --mcp postgres

# Install globally (prompts for Claude Code and/or Cursor)
npx @levi-putna/agent-kit@latest add owner/repo --global

# Install globally to Cursor only
npx @levi-putna/agent-kit@latest add owner/repo --skill code-review --global --agent cursor

# Install to the current project
npx @levi-putna/agent-kit@latest add owner/repo --project

# Install to a specific project agent
npx @levi-putna/agent-kit@latest add owner/repo --skill code-review --project --agent windsurf

Global vs project installs

Global: skills are written directly to your user directory:

~/.claude/skills/: Claude Code and Claude desktop app
~/.cursor/skills/: Cursor (all projects)

Project: skills are written to .agents/skills/ with symlinks from each agent directory you choose. Agent directories are created automatically if they do not exist yet. An agent-kit-lock.json file is created so teammates can reproduce the same setup.

npx @levi-putna/agent-kit@latest add owner/repo --project
npx @levi-putna/agent-kit@latest update    # refresh project skills from their source repos

Managing installed skills

npx @levi-putna/agent-kit@latest installed          # list what's installed
npx @levi-putna/agent-kit@latest update             # pull latest versions from source repos (project scope)
npx @levi-putna/agent-kit@latest remove code-review # remove a skill or MCP server by name

MCP server installation

When installing an MCP server, @levi-putna/agent-kit will:

Show you the server definition and what env vars it needs
Prompt you for any required values (API keys, endpoints, etc.)
Ask permission before writing to each config file
Merge the server entry without overwriting other servers you have already configured

npx @levi-putna/agent-kit@latest add owner/repo --mcp my-server --global

Supported agents

Agent	Skills	MCP config
Claude Code	`~/.claude/skills/` (global) · `.claude/skills/` (project)	`~/.claude.json` · `.mcp.json`
Claude Desktop	via global install	`~/Library/Application Support/Claude/...`
Cursor	`~/.cursor/skills/` (global) · `.cursor/skills/` (project)	`.cursor/mcp.json`
Windsurf	`.windsurf/skills/`	`.windsurf/mcp.json`
GitHub Copilot	`.github/skills/`	`.vscode/mcp.json`
Cline	`.cline/skills/`	None
OpenCode	`.opencode/skills/`	None

Valid values for --agent: claude, cursor, windsurf, copilot, cline, opencode.

UI Component Development Skills

This repository includes a comprehensive set of skills for building and testing UI components using modern best practices. These skills work both in isolation (for focused component development) and as part of the build flow (when the agent needs to create or test UI elements).

Available UI Skills

Skill	Purpose	Use In Isolation	Use In Build Flow
`ui-storybook-setup`	Set up Storybook for component isolation	When initialising component testing	When project needs component isolation
`ui-component-create`	Create reusable components following shadcn/ui patterns	When building individual components	When app needs new UI elements
`ui-component-test`	Add interaction tests with play functions	When adding tests to components	When validating component behaviour
`ui-visual-regression`	Set up visual regression testing (Chromatic/Percy)	When configuring visual tests	When preventing visual regressions
`ui-accessibility-test`	Test components for WCAG compliance	When ensuring accessibility	When validating a11y requirements
`ui-component-library`	Architect and govern a component library	When building design systems	When establishing standards

Workflow: Isolation vs Build Flow

Isolation Mode (Component Development)

Use skills independently to develop, test, and refine components:

Developer/Agent Task: "Create a new Button component"

┌─────────────────────────────────────┐
│  1. Use: ui-component-create        │
│     - Follow shadcn/ui patterns     │
│     - Implement with TypeScript     │
│     - Create Storybook stories      │
└─────────────────────────────────────┘
            ↓
┌─────────────────────────────────────┐
│  2. Use: ui-component-test          │
│     - Add interaction tests         │
│     - Test keyboard navigation      │
│     - Validate user behaviour       │
└─────────────────────────────────────┘
            ↓
┌─────────────────────────────────────┐
│  3. Use: ui-accessibility-test      │
│     - Run axe-core checks           │
│     - Test screen reader support    │
│     - Validate WCAG compliance      │
└─────────────────────────────────────┘
            ↓
┌─────────────────────────────────────┐
│  4. Use: ui-visual-regression       │
│     - Capture visual baselines      │
│     - Set up Chromatic/Percy        │
│     - Prevent unintended changes    │
└─────────────────────────────────────┘

Result: Fully tested, accessible, production-ready component

Build Flow Mode (Application Development)

Skills automatically kick in when agents build features:

User Request: "Build a user profile page"

Agent Analysis:
┌─────────────────────────────────────┐
│  Needs: UserCard component          │
│  Status: Does not exist             │
│  Action: Trigger ui-component-create│
└─────────────────────────────────────┘
            ↓
┌─────────────────────────────────────┐
│  1. ui-component-create runs        │
│     Creates UserCard component      │
│     with proper patterns            │
└─────────────────────────────────────┘
            ↓
┌─────────────────────────────────────┐
│  2. ui-component-test runs          │
│     Adds interaction tests          │
│     Validates behaviour             │
└─────────────────────────────────────┘
            ↓
┌─────────────────────────────────────┐
│  3. Continue with page implementation│
│     Uses newly created component    │
└─────────────────────────────────────┘

Agent proceeds with confidence that components are tested and reusable

Key Design Principles

Prefer Existing Components: Skills encourage using shadcn/ui and Vercel AI Elements before creating custom components
Testable by Default: Every component created includes tests (interaction, visual, accessibility)
Reusability: Components are built to be reusable across the application
Isolation: Storybook enables component development without running the full app
Quality Gates: Automated testing prevents regressions

Integration with Agent Workflow

When an agent is asked to build UI:

Check Storybook: Does the component already exist?
Use Primitives: Can this be built with shadcn/ui or Vercel AI Elements?
Create if Needed: Trigger ui-component-create skill
Test Immediately: Run ui-component-test and ui-accessibility-test
Visual Baseline: Capture snapshot with ui-visual-regression
Use in App: Now safely use the component in the application

Example: Agent Using UI Skills

User: "Add a search feature with autocomplete"

Agent thinking:
- Needs: SearchBar component with dropdown
- Check: Does SearchBar exist in Storybook? → No
- Action: Create component using ui-component-create skill

Agent: *reads ui-component-create skill*
Agent: *creates SearchBar component*
Agent: *creates SearchBar.stories.tsx*
Agent: *reads ui-component-test skill*
Agent: *adds interaction tests for typing and selecting*
Agent: *reads ui-accessibility-test skill*
Agent: *ensures keyboard navigation and screen reader support*
Agent: *integrates SearchBar into the search page*

Result: Production-ready, tested, accessible SearchBar component

Setting Up UI Skills in Your Project

Install the UI skills for your project:

# Install all UI skills
npx @levi-putna/agent-kit@latest add levi-putna/agent-kit --project

# Or install specific skills
npx @levi-putna/agent-kit@latest add levi-putna/agent-kit --skill ui-storybook-setup --project
npx @levi-putna/agent-kit@latest add levi-putna/agent-kit --skill ui-component-create --project
npx @levi-putna/agent-kit@latest add levi-putna/agent-kit --skill ui-component-test --project

For Teams

Design Systems Team: Use ui-component-library to establish governance
Individual Contributors: Use ui-component-create for day-to-day work
QA Engineers: Use testing skills (ui-component-test, ui-accessibility-test, ui-visual-regression)
Product Teams: Use all skills as part of the build flow

For skill & MCP developers

Publish skills and MCP server definitions in a GitHub repo. Users install them with @levi-putna/agent-kit. No npm package, registry, or approval process is required.

npx @levi-putna/agent-kit@latest add your-username/your-repo
npx @levi-putna/agent-kit@latest add your-username/your-repo --skill my-skill
npx @levi-putna/agent-kit@latest add your-username/your-repo --mcp my-server

How publishing works

You create a public GitHub repo with a skills/ and/or mcp/ directory.
Users run npx @levi-putna/agent-kit@latest add your-username/your-repo.
@levi-putna/agent-kit fetches the repo via the GitHub API and installs the selected items into the user's agent directories.
When you push updates, users can run npx @levi-putna/agent-kit@latest update to pull the latest skill files (for project installs tracked in agent-kit-lock.json).

There is nothing to submit or register. If the repo is public and follows the layout below, it works immediately.

Quick start

Create a minimal repo and publish your first skill in a few minutes:

mkdir my-agent-skills && cd my-agent-skills
git init

mkdir -p skills/hello-world
cat > skills/hello-world/SKILL.md << 'EOF'
---
name: hello-world
description: A simple greeting skill. Use when the user asks for a hello-world example.
---

# Hello World

Respond with a friendly greeting and a one-line tip about agent skills.
EOF

git add . && git commit -m "Add hello-world skill"
gh repo create my-agent-skills --public --source=. --push

Verify it is discoverable, then install it locally:

npx @levi-putna/agent-kit@latest list your-username/my-agent-skills
npx @levi-putna/agent-kit@latest add your-username/my-agent-skills --skill hello-world --project

Repository requirements

Requirement	Details
Visibility	Must be public. Private repos are not supported unless the user sets `GITHUB_TOKEN`.
Default branch	`main` is assumed. If your default branch is different, users must pass `@branch` (e.g. `owner/repo@develop`).
Layout	Skills live under `skills/<name>/`. MCP definitions live under `mcp/<name>/`.
Naming	Folder names become install names. Use lowercase, hyphenated names (e.g. `code-review`, `postgres`).

Repository layout

your-skills-repo/
  skills/
    code-review/
      SKILL.md              # required
      checklist.md          # optional supporting file
      review-prompt.txt     # optional supporting file
    deploy/
      SKILL.md
  mcp/
    postgres/
      mcp.json              # required
      README.md             # optional documentation for humans browsing the repo

Skills: each subfolder of skills/ that contains a SKILL.md is installable. The folder name is what users pass to --skill.
MCP servers: each subfolder of mcp/ that contains an mcp.json is installable. The folder name is what users pass to --mcp and becomes the key in the agent's MCP config.
Supporting files: any file in the same folder as SKILL.md is copied alongside it during install. Keep supporting files in the skill folder root (nested subdirectories are not fetched).

You can publish skills only, MCP only, or both in the same repo.

Creating a skill

A skill teaches an AI agent how to handle a specific task. It is a folder with a SKILL.md file and optional supporting files.

SKILL.md format

---
name: code-review
description: Review code for bugs, security issues, and style problems. Use when asked to review, audit, or check code.
---

# Code Review

When asked to review code, follow these steps:

1. Read the changed files and understand the intent.
2. Check for bugs, edge cases, and security issues.
3. Note style or maintainability concerns.
4. Summarise findings with severity (critical, warning, suggestion).

Frontmatter fields

Field	Required	Description
`name`	Recommended	Skill identifier. Should match the folder name.
`description`	Required	Tells the agent when to activate this skill. Be specific and include trigger phrases the user might say.

The description is the most important field. Agents read it to decide whether to load the skill. A vague description like "Helps with code" will rarely activate. A good description names the task and lists example triggers:

description: Review pull requests for bugs and security issues. Use when asked to review a PR, audit code, or check for problems.

Writing effective skill content

Start with the goal: state what the agent should accomplish in the first paragraph.
Use numbered steps for multi-step workflows.
Include examples of good and bad output where helpful.
Reference supporting files in the skill body so the agent knows they exist (e.g. "Use the checklist in checklist.md").
Keep it focused: one skill per task. Split large workflows into separate skills.

Example: skill with supporting files

skills/
  api-design/
    SKILL.md
    rest-conventions.md
    example-response.json

---
name: api-design
description: Design REST API endpoints and request/response shapes. Use when asked to design, plan, or review an API.
---

# API Design

Follow the conventions in `rest-conventions.md`.

When proposing a new endpoint, include:
- HTTP method and path
- Request body schema
- Response body schema (use `example-response.json` as a template)
- Error cases

What gets installed

When a user installs your skill:

Global install: files are written to ~/.claude/skills/<name>/ and/or ~/.cursor/skills/<name>/.
Project install: files are written to .agents/skills/<name>/ with symlinks from each chosen agent directory (.cursor/skills/, .claude/skills/, etc.). An entry is added to agent-kit-lock.json so teammates can reproduce the setup.

Creating an MCP server definition

An MCP definition tells @levi-putna/agent-kit how to configure an MCP server in the user's agent. You are not publishing the MCP server binary itself. You are publishing a recipe that points to an npm package, executable, or script the user already has (or that npx can fetch).

mcp.json format

{
  "name": "postgres",
  "description": "Query and manage a PostgreSQL database",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-postgres"],
  "env": {
    "POSTGRES_CONNECTION_STRING": {
      "description": "PostgreSQL connection string (e.g. postgresql://user:pass@localhost:5432/mydb)",
      "required": true
    }
  }
}

Field reference

Field	Required	Description
`name`	Recommended	Server identifier. Should match the folder name.
`description`	Recommended	Shown in the install picker. Explain what the server does.
`command`	Required	Executable to run (e.g. `npx`, `node`, `python`, `/path/to/binary`).
`args`	Optional	Array of command-line arguments. Defaults to `[]`.
`env`	Optional	Environment variables the user must (or can) provide at install time.

Environment variable schema

Each key under env maps to an object with:

Field	Required	Description
`description`	Recommended	Shown to the user during the interactive prompt. Explain where to find the value.
`required`	Optional	If `true`, the user must provide a value before install continues. Defaults to optional.

"env": {
  "API_KEY": {
    "description": "API key from https://example.com/settings/api",
    "required": true
  },
  "API_URL": {
    "description": "API base URL (defaults to https://api.example.com)",
    "required": false
  }
}

What `@levi-putna/agent-kit` writes

During install, @levi-putna/agent-kit prompts for env values, then merges an entry into the user's MCP config. The written entry looks like:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://..."
      }
    }
  }
}

@levi-putna/agent-kit merges into existing config files. It never removes other MCP servers the user has configured.

Install scope	Config files updated
Global	`~/.claude.json`, Claude Desktop config
Project	`.mcp.json`, `.cursor/mcp.json`, `.windsurf/mcp.json`, `.vscode/mcp.json` (per agent chosen)

MCP examples

npm package via npx:

{
  "name": "filesystem",
  "description": "Read and write files on the local filesystem",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
}

Local script:

{
  "name": "my-tool",
  "description": "Custom internal tool",
  "command": "node",
  "args": ["./dist/index.js"],
  "env": {
    "AUTH_TOKEN": {
      "description": "Bearer token from the internal dashboard",
      "required": true
    }
  }
}

Add a README.md in the MCP folder to document setup steps, links to your npm package, and where users can get API keys. This is for humans browsing your repo. @levi-putna/agent-kit uses mcp.json for install.

Publishing step by step

Create the repo on GitHub (public).
Add your skills and/or MCP definitions following the layout above.
Commit and push to your default branch (main unless you document otherwise).
Test the install yourself (see below).
Share the install command with users:

# Browse what's available
npx @levi-putna/agent-kit@latest list your-username/your-repo

# Install everything interactively
npx @levi-putna/agent-kit@latest add your-username/your-repo

# Install specific items
npx @levi-putna/agent-kit@latest add your-username/your-repo --skill code-review
npx @levi-putna/agent-kit@latest add your-username/your-repo --mcp postgres

# Install from a non-default branch
npx @levi-putna/agent-kit@latest add your-username/your-repo@develop

Ship updates by pushing to GitHub. Users with project installs can refresh skills with:

npx @levi-putna/agent-kit@latest update

Testing before you share

Run through this checklist on your own machine before sharing your repo:

# 1. Confirm @levi-putna/agent-kit can see your skills and MCP servers
npx @levi-putna/agent-kit@latest list your-username/your-repo

# 2. Install a skill to a test project
mkdir /tmp/agent-kit-test && cd /tmp/agent-kit-test
npx @levi-putna/agent-kit@latest add your-username/your-repo --skill my-skill --project

# 3. Verify files landed in the right place
ls .agents/skills/my-skill/
cat .agents/skills/my-skill/SKILL.md

# 4. Install an MCP server and confirm the config was merged
npx @levi-putna/agent-kit@latest add your-username/your-repo --mcp my-server --project --agent cursor
cat .cursor/mcp.json

# 5. Test updating after you push a change
npx @levi-putna/agent-kit@latest update

Verify:

npx @levi-putna/agent-kit@latest list shows all your skills and MCP servers
SKILL.md frontmatter has a clear, specific description
Supporting files appear alongside SKILL.md after install
MCP env prompts show helpful descriptions
MCP config merges without removing existing servers
Folder names match what you document in your README

Troubleshooting

Problem	Likely cause	Fix
`No skills or MCP servers found`	Repo is private, wrong branch, or missing `skills/` / `mcp/` directory	Make the repo public, confirm the branch, check folder names
`Skill "foo" not found`	Folder name mismatch	Folder must be `skills/foo/` and users pass `--skill foo`
`Could not fetch skill`	Missing `SKILL.md`	Every skill folder needs a `SKILL.md` file
Supporting files missing after install	Files are in a nested subdirectory	Move files to the skill folder root. Only top-level files are fetched
Users on a different default branch	`@levi-putna/agent-kit` defaults to `main`	Tell users to use `owner/repo@your-branch`
Rate limit errors during development	Unauthenticated GitHub API limits	Set `GITHUB_TOKEN` in the environment

Best practices

One repo or many: a single my-skills repo works well for a personal collection; separate repos make sense for large or independently versioned packages.
Document your repo: add a README explaining what each skill does and what MCP servers need (API keys, accounts, etc.).
Version with git: tag releases (v1.0.0) if you want users to pin to a branch or tag via owner/repo@v1.0.0.
Keep secrets out of the repo: use the env block in mcp.json to prompt users for API keys at install time. Never commit real credentials.
Test across agents: if your skill is agent-agnostic, test a project install with both Cursor and Claude Code to confirm symlinks work.

For agent-kit developers

This section is for contributors and maintainers working on the @levi-putna/agent-kit package itself.

Clone and install

git clone https://github.com/levi-putna/agent-kit.git
cd agent-kit
npm install

Run tests

npm test

Tests run automatically before every npm publish via the prepublishOnly script.

Run the CLI locally

Without installing globally, which is useful while iterating:

node bin/cli.js --help
node bin/cli.js list owner/repo
node bin/cli.js add owner/repo --project

Or link it globally so the agent-kit binary points at your local source (the global binary name comes from package.json; users should still prefer npx @levi-putna/agent-kit@latest for the published package):

npm link
npx @levi-putna/agent-kit@latest --help

Unlink when you are done:

npm unlink -g @levi-putna/agent-kit

Tip: Set GITHUB_TOKEN in your environment if you hit GitHub API rate limits during development.

Project structure

agent-kit/
  bin/cli.js          # CLI entry point
  src/
    commands/         # add, list, installed, remove, update
    lib/              # agents, github, installer, lockfile, mcp
    ui/               # interactive prompts

Publishing a new version

These steps apply to anyone with publish access to the npm package scope.

First-time setup

Log in to npm with an account that has publish access:

npm login
npm whoami

Release checklist

Bump the version in package.json following semver:

npm version patch   # 0.1.0 → 0.1.1  (bug fixes)
npm version minor   # 0.1.0 → 0.2.0  (new features)
npm version major   # 0.1.0 → 1.0.0  (breaking changes)

This updates package.json and creates a git tag automatically.

Publish to npm. Tests run automatically via prepublishOnly:

npm publish --access public

The --access public flag is required for scoped packages on the first publish. Subsequent publishes do not need it if publishConfig.access is already set to "public".

Push the version tag to GitHub:

git push && git push --tags

What gets published

The files field in package.json controls the npm package contents:

bin/
src/

Dry run

Preview what will be included before publishing:

npm publish --dry-run

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
bin		bin
skills		skills
src		src
.gitignore		.gitignore
README.md		README.md
UI-SKILLS-INTEGRATION.md		UI-SKILLS-INTEGRATION.md
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml

Folders and files

Latest commit

History

Repository files navigation

@levi-putna/agent-kit

Table of contents

For users

Install

Commands

Using a skills repo

add options

Examples

Global vs project installs

Managing installed skills

MCP server installation

Supported agents

UI Component Development Skills

Available UI Skills

Workflow: Isolation vs Build Flow

Isolation Mode (Component Development)

Build Flow Mode (Application Development)

Key Design Principles

Integration with Agent Workflow

Example: Agent Using UI Skills

Setting Up UI Skills in Your Project

For Teams

For skill & MCP developers

How publishing works

Quick start

Repository requirements

Repository layout

Creating a skill

SKILL.md format

Frontmatter fields

Writing effective skill content

Example: skill with supporting files

What gets installed

Creating an MCP server definition

mcp.json format

Field reference

Environment variable schema

What @levi-putna/agent-kit writes

MCP examples

Publishing step by step

Testing before you share

Troubleshooting

Best practices

For agent-kit developers

Clone and install

Run tests

Run the CLI locally

Project structure

Publishing a new version

First-time setup

Release checklist

What gets published

Dry run

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`add` options

What `@levi-putna/agent-kit` writes

Packages