Authoring Custom Agent Skills and Packaging MCP Bundles (.mcpb) for IDE Integration
The standardization of Agent Skills alongside Model Context Protocol Bundles (.mcpb) simplifies how AI engineering capabilities are distributed across development environments.
Historically, installing local MCP tools required end users to manually provision Node.js or Python runtimes and edit hidden JSON configuration files. The .mcpb archive specification packages local stdio tools together with embedded execution runtimes, enabling single-click zero-dependency installation.
Agent Skills (SKILL.md) vs MCP Bundles (.mcpb)
┌────────────────────────────────────────────────────────────────────────┐
│ AGENT TOOLING DISTRIBUTION │
└───────────────────────────────────┬────────────────────────────────────┘
│
┌─────────────────────────┴─────────────────────────┐
▼ ▼
┌──────────────────────────────┐ ┌──────────────────────────────┐
│ SKILL.MD PLAYBOOKS │ │ MCP BUNDLES (.MCPB) │
├──────────────────────────────┤ ├──────────────────────────────┤
│ • Instructions & Prompts │ │ • Binary Runtime Archive │
│ • YAML Frontmatter Metadata │ │ • Manifest Definition │
│ • No Runtime Binary Needed │ │ • Single-Click Installation │
└──────────────────────────────┘ └──────────────────────────────┘| Layer | Primary Responsibility | File Manifest | Target User Experience |
|---|---|---|---|
| Agent Skill | Defines multi-step workflows & prompts | skills/<name>/SKILL.md | Auto-discovered domain expertise |
| MCP Bundle | Distributes executable binary tools | bundle.json in .mcpb | Zero-dependency 1-click install |
Step 1: Authoring a Custom SKILL.md Playbook
Create a skill directory at .claude/skills/db-migration/SKILL.md:
---
name: database-migration
description: Automated Prisma & PostgreSQL schema migration playbook with rollback checks
---
# Database Migration Skill Playbook
When the user asks to run or generate database migrations, follow these steps:
1. **Schema Check**: Inspect `prisma/schema.prisma` for uncommitted structural changes.
2. **Dry Run**: Execute `npx prisma migrate dev --create-only` to generate sql file without applying.
3. **Audit**: Inspect the generated SQL script for non-reversible drops (`DROP TABLE` / `DROP COLUMN`).
4. **Apply**: Execute `npx prisma migrate deploy` after user confirmation.Step 2: Packaging an MCP Bundle (.mcpb)
Build an .mcpb package using build-mcpb:
# Install the MCP Bundle CLI Tool
$ npm install -g @modelcontextprotocol/build-mcpb
# Compile the local MCP server into a single portable bundle
$ build-mcpb --input ./my-mcp-server --output db-tools.mcpbOnce generated, double-clicking db-tools.mcpb opens your desktop AI client and installs the MCP tool bundle instantly with zero manual JSON editing.
