Organizing and Distributing: Plugins and Marketplaces, Versioning and Team Sharing, and the Division of Labor Between Function Calling, MCP, and Skills

A plugin's directory layout and manifest

The spec itself defines only that a skill is a folder containing a SKILL.md, and it says nothing about distribution. So the package layer is each client's own mechanism, with different names and details, and you have to follow whichever you actually use. Below uses Claude Code's plugins as the example, because it is currently the most fully documented, and understanding it makes the others quick to read.

A plugin is a directory with a manifest at its root and component directories laid out by convention:

team-conventions/
├── .claude-plugin/
│   └── plugin.json          # the manifest: name, description, version, author
├── skills/
│   ├── commit-message/SKILL.md
│   ├── code-review/SKILL.md
│   └── release-report/SKILL.md
├── agents/                  # optional: subagent definitions
├── hooks/hooks.json         # optional: event hooks
├── .mcp.json                # optional: MCP server configuration shipped with the package
└── README.md

The manifest itself is extremely short, with four fields:

{
  "name": "team-conventions",
  "description": "A team's commit, review, and release conventions; effective as soon as installed",
  "version": "1.2.0",
  "author": { "name": "Platform Team" }
}

Two of those four fields carry rules that are easy to trip over.

First, name is the namespace. Skills in the package get prefixed as package-colon-skill, such as team-conventions:commit-message. That solves the collision from the opening: two packages each carrying a commit-message can be installed together without fighting. Changing the package name changes every skill's invocation name, so decide it once and properly.

Second, component directories must sit at the plugin root and cannot go inside the manifest's directory. skills/, agents/, and hooks/ all live at the root, and .claude-plugin/ holds only plugin.json. The official documentation flags this as the most common error, so check it first when something will not install.

Both are structural problems, and structural problems are exactly what a dozen lines of script should block at the door. The self-check below does three things: confirms the manifest is in its dedicated directory, confirms no component directory got misplaced inside it, and confirms every skill has a description. Run it before shipping and it saves far more effort than diagnosing after installation.

import { readFileSync, readdirSync, existsSync } from 'node:fs'
import { join } from 'node:path'
 
const COMPONENT_DIRS = ['skills', 'agents', 'hooks', 'commands']
 
export function checkPack(root: string): string[] {
  const errors: string[] = []
  const manifestPath = join(root, '.claude-plugin', 'plugin.json')
  if (!existsSync(manifestPath)) return [`manifest does not exist: ${manifestPath}`]
 
  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as Record<string, unknown>
  for (const key of ['name', 'description', 'version']) {
    if (!manifest[key]) errors.push(`the manifest is missing ${key}`)
  }
  // The most common error: a component directory placed inside the manifest's directory
  for (const dir of COMPONENT_DIRS) {
    if (existsSync(join(root, '.claude-plugin', dir))) {
      errors.push(`${dir}/ must sit at the plugin root and cannot go inside .claude-plugin/`)
    }
  }
  const skillsDir = join(root, 'skills')
  if (!existsSync(skillsDir)) return [...errors, 'there is no skills/ directory']
 
  for (const name of readdirSync(skillsDir)) {
    const file = join(skillsDir, name, 'SKILL.md')
    if (!existsSync(file)) {
      errors.push(`${name}/ has no SKILL.md, so it will not be treated as a skill`)
      continue
    }
    // A skill without a description can never be triggered, so shipping it ships nothing
    if (!/^description:\s*\S/m.test(readFileSync(file, 'utf8'))) {
      errors.push(`${name} is missing a description`)
    }
  }
  return errors
}

import json
import re
from pathlib import Path
 
COMPONENT_DIRS = ["skills", "agents", "hooks", "commands"]
 
 
def check_pack(root: Path) -> list[str]:
    errors: list[str] = []
    manifest_path = root / ".claude-plugin" / "plugin.json"
    if not manifest_path.exists():
        return [f"manifest does not exist: {manifest_path}"]
 
    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
    for key in ("name", "description", "version"):
        if not manifest.get(key):
            errors.append(f"the manifest is missing {key}")
    # The most common error: a component directory placed inside the manifest's directory
    for name in COMPONENT_DIRS:
        if (root / ".claude-plugin" / name).exists():
            errors.append(f"{name}/ must sit at the plugin root and cannot go inside .claude-plugin/")
 
    skills_dir = root / "skills"
    if not skills_dir.exists():
        return errors + ["there is no skills/ directory"]
 
    for entry in sorted(skills_dir.iterdir()):
        skill_md = entry / "SKILL.md"
        if not skill_md.exists():
            errors.append(f"{entry.name}/ has no SKILL.md, so it will not be treated as a skill")
            continue
        # A skill without a description can never be triggered, so shipping it ships nothing
        if not re.search(r"^description:\s*\S", skill_md.read_text(encoding="utf-8"), re.M):
            errors.append(f"{entry.name} is missing a description")
    return errors

During development you neither publish nor install: one command-line flag mounts a local directory so you can try it, and a reload command after an edit avoids a restart. That development mode is today's lab's main thread — the first thing to do with a finished package is load it locally, trigger each skill once, and confirm the namespace lines up.

Marketplaces and versions

The package is built, so how do others get it? Through a marketplace. A marketplace sounds like a shop and is far plainer than that: a repository with a marketplace.json at its root, listing which packages this marketplace offers and where each comes from.

{
  "name": "acme-tools",
  "owner": { "name": "Platform Team" },
  "plugins": [
    { "name": "team-conventions", "source": "./plugins/team-conventions", "version": "1.2.0" },
    { "name": "deploy-tools", "source": { "source": "github", "repo": "acme/deploy-plugin" } }
  ]
}

A source can be a relative path inside the marketplace repository, or another Git repository, an npm package, or an archive URL. Which means a marketplace is an index layer and need not hold the content — you can treat a repository containing only a manifest as a marketplace while the package bodies stay where they were.

On the user's side there are only two steps: add the marketplace, then install by package-at-marketplace.

Versioning is the only part here that needs thought, and the rules are worth memorizing precisely:

With a version written, that value governs, and users receive an update only when it changes. Without one, a Git source uses the resolved commit hash as the version, so every push you make updates every user. The former is controllable and the latter is convenient; the latter is fine inside a team, and an external release must pin the version.

Do not write the version in two places. The package's own manifest takes precedence, and a disagreement between the two leaves you in a state you cannot explain to yourself.

Which changes warrant a version bump? The criterion is not whether a file changed but whether users' behavior changes as a result. A changed description, a changed step in the body, a changed script argument — bump. A typo fix, an added comment — no. It is the same reasoning as releasing a library, except the interface here is not a function signature but the description and the body.

Three paths for sharing across a team

For a dozen people to share one set of skills there are three paths, chosen by who installs, who maintains, and who may edit.

First, ride along with the repository. Put the skills straight into the project's .agents/skills/ and commit them with the code. The upside is zero infrastructure, everyone has them as soon as they pull, and review goes through the same pull request flow. The downside is that it holds only for this repository, so five repositories mean maintaining five copies. For conventions tied to one codebase, pick this without hesitating.

Second, go through a marketplace. Create a marketplace repository, have team members add it once each, then install on demand and receive updates automatically. The upside is one place maintained and many places affected, with versions and upgrade notes. The downside is the extra cost of persuading everyone to add the marketplace. For cross-repository team conventions, pick this.

Third, go through organization management. Pushed down centrally, with members not needing to add it and not able to switch it off casually. The upside is guaranteed coverage and auditability for compliance. The downside is a heavy process and slow iteration. Only conventions that must be mandatory and cause incidents when absent are worth this path — the security and compliance ones.

The three paths are not exclusive. A common stable combination: security and compliance through organization management, cross-repository team conventions through a marketplace, and a project's own quirks riding along with that repository.

Function calling, MCP, and Skills compared in full

This course has owed you this table since day one. First, a division you can memorize: MCP handles the wiring, Skills handle the experience, and context engineering handles the trade-offs; and function calling is the shortest wire, before any wiring standard.

The last two rows are the ones most worth pulling out.

The what-happens-when-it-cannot-be-installed row explains why a skill is cheap. Tools and protocols are binary: wired up and you have it, not wired up and you do not. A skill that cannot be installed is still a clearly written Markdown file that a person can read and another client can read. That is the fundamental reason it spread sideways across dozens of clients — it requires the host to implement no protocol, only to read files.

The who-writes-it row decides where each sits in an organization. Functions and servers can only be produced by engineers, while a skill can be written by the person who genuinely understands the business, with an engineer at most reviewing it. The holder of the experience and the holder of the code are often not the same people, and a skill lets the former deliver directly for the first time.

Finally, to be clear: these three do not replace each other, and combining them is the norm. A typical combination: an MCP server brings the company's ticketing system in as a callable tool; and a skill's body says "first pull this week's tickets with the ticket query tool, then classify them against the template below, and note that tickets in the merged state are excluded." The tool gives it hands and the skill gives it method. How that protocol side is designed and how prompt injection is defended against is covered from the beginning in the sister course, MCP in 7 Days.

Selection criteria: a flow you can run on the spot

Asked in an interview when to use which, the best answer is not reciting the table above but giving a decision flow you can run on the spot.

flowchart TB
  A[The model handles this poorly today] --> B{Is it missing capability<br/>or missing method}
  B -- Missing capability, cannot do it --> C{Does only this one<br/>application need it}
  C -- Yes --> D[Write function calling<br/>the shortest path, do not over-design]
  C -- No, several agents need it --> E[Build an MCP server<br/>wire once, use everywhere]
  B -- Missing method, can do it but breaks convention --> F{Does this method need<br/>deterministic execution}
  F -- No, instructions suffice --> G[Write a skill<br/>the body states steps and pitfalls]
  F -- Yes, results must match to the letter --> H[Write a skill with a script<br/>determinism goes to code]

Three lines you can memorize outright:

Separate capability from method first. Get that cut wrong and everything after is wrong. The test is plain: hand this to a contractor clever enough but unfamiliar with your company — if they cannot do it, capability is missing; if they can do it but not to your conventions, method is missing.

On the capability side, choose by breadth of reuse. If only this application needs it, function calling is the end of it and building a server for it is over-design; only when several agents or clients need it is the protocol worth the trip.

On the method side, choose by determinism. What can be settled with clear instructions goes in the body; what must match to the letter gets a script the moment any of day four's three criteria hits.

Source Reading

Hands-On Lab

Today is a documentation-style lab: the deliverable is a plugin package and a delivery document, not code. The easiest ones to fudge are criteria 2 and 5 — with a blurry boundary, somebody will ask within two weeks why it does not handle their situation. When you are done, extract the three descriptions and run them through day three's positive-and-negative apparatus again to confirm they do not steal from each other.

1. Read the solution's plugin package and see by what standard the three skills' boundaries were drawn.
2. Complete the plugin manifest's name, description, and version fields in the starter.
3. Arrange the three skills you wrote on earlier days per the plugin directory convention, with one line of boundary statement each.
4. Load the package locally in development mode, trigger each of the three skills, and record the namespaces.
5. Write upgrade notes for the package, stating which changes warrant a version bump and which do not.

Interview Questions

Today's 3 questions are in the question bank below, weighted toward organizing and distributing skills, versioning and team governance, and choosing among the three extension mechanisms. Expand each one and read the analysis before the key points — practicing the derivation beats memorizing bullets. The high-frequency labels for the domestic and overseas markets are there so you can pick by target market.

Checklist and Tomorrow

• Package a group of skills into a plugin with a manifest and a version, and load it locally to verify it
• Explain the three paths for sharing skills across a team and when each fits
• Use a comparison table to explain the division of labor between function calling, MCP, and Skills, and give selection criteria
• State that every change to a description is a behavioural change, and explain why it is the most easily missed
• All 5 acceptance criteria of the lab pass
• Answer at least 2 of the 3 interview questions without looking at the key points

Tomorrow (D7) closes the course: split a real team convention document into three skills, hand a real task to a clean subagent to execute, and use a set of assertions to prove it really beats going without the skills — not that it feels better, but by how many percentage points the pass rate rose. Finally, compress the delivery into one portfolio entry that survives follow-up questions.