@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

Table of contents

1. For users: install and use @levi-putna/agent-kit with any skills repo
2. For skill & MCP developers: publish your own skills and MCP definitions
3. For agent-kit developers: run, test, and publish the CLI itself

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:

1. Show you the server definition and what env vars it needs
2. Prompt you for any required values (API keys, endpoints, etc.)
3. Ask permission before writing to each config file
4. 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.

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

1. You create a public GitHub repo with a skills/ and/or mcp/ directory.
2. Users run npx @levi-putna/agent-kit@latest add your-username/your-repo.
3. @levi-putna/agent-kit fetches the repo via the GitHub API and installs the selected items into the user's agent directories.
4. 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

1. Create the repo on GitHub (public).
2. Add your skills and/or MCP definitions following the layout above.
3. Commit and push to your default branch (main unless you document otherwise).
4. Test the install yourself (see below).
5. 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

6. 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/[email protected].
• 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

1. 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.

2. 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".

3. 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