Agent Kit

Publishing skills and MCP

Put skills and MCP server definitions in a GitHub repo. Other people install them with Agent Kit. No npm package, no registry, no approval step.

Overview

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.
Agent Kit fetches the repo via the GitHub API and installs the selected items.
When you push updates, users with project installs can run update to pull the latest skill files.

Nothing to submit or register. Public repo, correct layout, and it works.

Quick start

Publish your first skill

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

Then verify and install 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

Layout

Repository layout

Repo must be public. Default branch is main. Folder names become install names. Use lowercase, hyphenated names.

text

your-skills-repo/
  skills/
    code-review/
      SKILL.md              # required
      checklist.md          # optional supporting file
    deploy/
      SKILL.md
  mcp/
    postgres/
      mcp.json              # required
      README.md             # optional documentation

Skills

Creating a skill

A skill is a folder with a SKILL.md file and optional supporting files. The description in frontmatter matters most. Agents read it to decide whether to activate the skill.

SKILL.md example

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

markdown

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

MCP

Creating an MCP server definition

An MCP definition tells Agent Kit how to wire up an MCP server in someone's agent. You are not shipping the server binary. You are publishing a recipe that points at an npm package, executable, or script.

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

json

{
  "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
    }
  }
}

Agent Kit merges into existing config files and leaves other MCP servers alone. Use the env block to prompt for API keys at install time. Do not commit real credentials.

Checklist

Publishing step by step

Step 1

Create the repo

Create a public GitHub repository.

Step 2

Add skills and MCP definitions

Follow the skills/ and mcp/ layout below.

Step 3

Commit and push

Push to your default branch (main unless you document otherwise).

Step 4

Test the install

Run through the verification checklist on your own machine.

Step 5

Share the install command

Give users: npx @levi-putna/agent-kit@latest add your-username/your-repo

Testing

Test before you share

# 1. Confirm 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. Test updating after you push a change
npx @levi-putna/agent-kit@latest update

Troubleshooting

Common problems

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
Rate limit errors during development	Unauthenticated GitHub API limits	Set GITHUB_TOKEN in the environment

Best practices

Tips for maintainers

One personal skills repo is usually enough. Split into separate repos only when packages are large or versioned independently.
Add a README that says what each skill does and what MCP servers need to run.
Tag releases if you want people to pin a version via owner/repo@v1.0.0.
Test a project install on both Cursor and Claude Code before you share it. Symlinks are where things usually break.

Contributing

Contributing to Agent Kit

Working on the CLI itself? Clone the repo, run npm test, and publish new versions to npm.

GitHub →npm →Usage guide →