How to Package and Share AI Agent Skills with Your Team

You will package an AI agent skill into a standardized plugin directory and distribute it through a shared Git repository. Packaging your skill in an Agent Plugins manifest standardizes prompt instructions, tool configurations, and version numbers across your engineering team. When you update the plugin version in version control, your team members pull the exact same prompts and tools without copying manual files into individual workspace settings.

Before you start

A compatible agent client such as VS Code, Cursor, Codex CLI, or Claude Code.
Git installed with push access to a shared team repository.
A working task workflow to package into a skill.

How it works

flowchart LR
  A[Define skill in SKILL.md] --> B[Configure plugin.json manifest]
  B --> C[Push plugin directory to Git]
  C --> D[Team installs plugin from repository]
  D --> E[Client loads identical skills and tools]

Step 1: Create the directory layout

Create the folder tree for the plugin package. Store skill definitions inside a dedicated skills/ directory at the plugin root.

mkdir -p my-team-plugin/skills/deploy-helper

Step 2: Write the skill instructions

Create my-team-plugin/skills/deploy-helper/SKILL.md. Define the YAML frontmatter with the skill name and matching description, followed by the execution steps.

---
name: deploy-helper
description: Guides the agent through deploying the application and running verification tests.
---
# Deploy Helper Skill

You are an expert deployment assistant. Follow these steps to deploy and verify the application:

1. Run the build script: `npm run build`.
2. Execute the verification suite: `./scripts/validate.sh`.
3. If any tests fail, analyze the logs in `./logs/error.log` and suggest a fix.

Step 3: Define the plugin manifest

Create my-team-plugin/plugin.json in the root directory. The Agent Plugins specification uses this manifest to define identity, versioning, and author metadata. The top-level schema is strictly enforced.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-team-plugin",
  "version": "1.0.0",
  "description": "Shared deployment and verification skills for our dev team.",
  "author": {
    "name": "Platform Engineering Team",
    "email": "platform@example.com"
  }
}

Step 4 (optional): Configure Model Context Protocol servers

If your skill requires live database access or dynamic external tools, define them in my-team-plugin/mcp.json. This attaches the tool execution configuration directly to the plugin package.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "db-fetcher": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

Step 5: Publish the plugin to your team Git repository

Initialize the repository, commit all plugin files, and push them to your team's remote. Team members can now clone or point their clients to this repository to load identical workflows.

cd my-team-plugin
git init
git add .
git commit -m "feat: initial agent plugin release"
git remote add origin git@github.com:example-org/agent-plugins.git
git push -u origin main

Common mistakes

Hardcoded absolute paths. Paths must be relative to the plugin root starting with ./ or use environment variables like ${CLAUDE_PLUGIN_ROOT}. Absolute paths fail across different developer environments.
Symlinks resolving outside the root. The specification strictly forbids symlinks that resolve outside the plugin directory. Clients reject the package on load for security reasons.
Unrecognized manifest schema fields. The plugin.json schema is closed. Place custom client configurations under an extensions object rather than creating new top-level keys.
Heavy lifecycle hooks on startup. Running compile or dependency installation commands on every startup introduces agent latency. Ensure setup hooks check for existing build artifacts before running.

How to Create Custom Skills for Claude Code and Codex
How to Create a Claude Code Skill (SKILL.md), Step by Step
Read the official specification at agent-plugins-spec.