---
name: claude
description: Use this skill when building plugins, MCP servers, skills, or
  connectors for Claude; integrating Claude into Slack with Claude Tag;
  deploying Claude Desktop; or customizing Claude with connectors and skills.
  Reach for this skill when agents need to understand Claude's architecture,
  build extensions, configure deployments, or help users set up Claude
  integrations.
metadata:
  mintlify-proj: claude
  version: "1.0"
---

# Claude AI Skill

## Product Summary

Claude AI is Anthropic's conversational AI platform available on claude.ai, Claude Desktop, mobile apps, and integrated into Slack (Claude Tag), Microsoft 365, and third-party platforms. Agents work with Claude through three main extension mechanisms: **MCP connectors** (give Claude access to external tools and data), **skills** (teach Claude how to do tasks your way), and **plugins** (package skills and connectors together for sharing). The primary documentation site is https://claude.com/docs. Key file paths: `.claude-plugin/plugin.json` (plugin manifest), `SKILL.md` (skill instructions), `.mcp.json` (MCP server references). CLI tool: `claude` (Claude Code command-line tool for testing plugins and skills).

## When to Use

Use this skill when:
- **Building extensions**: creating plugins, MCP servers, or skills for Claude
- **Integrating Claude into workflows**: setting up Claude Tag in Slack, Claude Desktop deployments, or Claude for Microsoft 365
- **Customizing Claude**: adding connectors, skills, or plugins to a Claude account or organization
- **Troubleshooting deployments**: diagnosing configuration issues, authentication failures, or connector problems
- **Publishing to the directory**: preparing plugins or MCP servers for Anthropic's directory submission
- **Setting up enterprise deployments**: configuring Claude Desktop with MDM, managing Claude Tag for teams, or deploying Claude for Government

## Quick Reference

### Plugin Structure
```
my-plugin/
├── .claude-plugin/plugin.json    # Required manifest
├── skills/
│   └── skill-name/
│       ├── SKILL.md              # Required: frontmatter + instructions
│       ├── references/           # Optional: documentation files
│       ├── assets/               # Optional: templates, images
│       └── scripts/              # Optional: executable code
├── commands/                     # Optional: slash commands
├── .mcp.json                     # Optional: MCP server references
├── README.md                     # Required for directory submission
└── LICENSE                       # Required for directory submission
```

### SKILL.md Frontmatter
```yaml
---
name: skill-name                  # Lowercase, hyphens, 64 chars max
description: What this skill does and when to use it (1024 chars max)
---
```

### MCP Server Authentication Types
| Type | Use Case | Registration |
|------|----------|--------------|
| `oauth_dcr` | User signs in with their account | Dynamic Client Registration |
| `oauth_cimd` | User signs in with metadata document | Client ID Metadata Document |
| `oauth_anthropic_creds` | Anthropic holds client secret | Developer portal entry |
| `static_headers` | Organization Owner enters API key once | Request header (beta) |
| `none` | No authentication required | N/A |

### Plugin Manifest Fields (Required)
```json
{
  "name": "plugin-name",           // Permanent identity, never change
  "displayName": "Display Name",   // User-facing label
  "version": "1.0.0",              // Increment on every release
  "description": "What it does",   // Shown in directory
  "author": { "name": "...", "url": "..." },
  "license": "MIT"                 // Or use LICENSE file
}
```

### Common CLI Commands
```bash
claude plugin validate ./plugin-folder      # Check manifest and files
claude --plugin-dir ./plugin-folder         # Test plugin locally
claude plugin eval ./plugin-folder          # Run eval cases
claude mcp add <url>                        # Add MCP server
claude mcp remove <name>                    # Remove MCP server
```

### Connector Callback URLs
- **Hosted Claude** (claude.ai, Desktop, mobile, Cowork): `https://claude.ai/api/mcp/auth_callback`
- **Claude Code**: `http://localhost/callback` and `http://127.0.0.1/callback` (port-agnostic match)

## Decision Guidance

### When to Use Connectors vs Skills vs Plugins

| Need | Use | Why |
|------|-----|-----|
| Give Claude access to external data/tools | **Connector (MCP server)** | Reaches live services; enables real-time actions |
| Teach Claude your process or format | **Skill** | Reusable instructions; loads only when needed |
| Share multiple pieces together | **Plugin** | One install for skills + connectors + commands |
| One-off task in a conversation | **Neither** | Describe it directly in chat |

### When to Build Local vs Remote MCP Server

| Scenario | Type | Transport |
|----------|------|-----------|
| Distribute through directory | **Remote** | Streamable HTTP |
| Desktop app only, no sharing | **Local** | Stdio (packaged as MCPB) |
| Testing before publishing | **Local** | Stdio (tunnel for testing) |

### When to Use Each Authentication Type

| Scenario | Type | Notes |
|----------|------|-------|
| Each user has their own account | `oauth_dcr` or `oauth_cimd` | Standard OAuth flow |
| Organization has one shared API key | `static_headers` | Owner enters once (beta) |
| Custom per-customer setup | `oauth_anthropic_creds` | Anthropic holds secret |
| No auth needed | `none` | Public tools only |
| Some tools public, some private | Lazy auth | Mix of public and protected |

### When to Use Claude Tag vs Claude Desktop vs Claude for M365

| Use Case | Product | Reason |
|----------|---------|--------|
| Team collaboration in Slack | **Claude Tag** | Visible to whole channel; shared context |
| Individual desktop work | **Claude Desktop** | Local files; offline capable; Cowork support |
| Draft docs/emails in Office | **Claude for M365** | Native integration; works inside apps |
| API-driven integration | **Claude API** | Programmatic access; custom workflows |

## Workflow

### Building and Publishing a Plugin

1. **Plan the plugin**: Decide what it includes (skills, MCP server, commands). Read [Decide what to include in your plugin](/connectors/building/what-to-build).

2. **Create the folder structure**: Make `.claude-plugin/plugin.json` with required fields (name, displayName, version, description, license). Validate with `claude plugin validate ./plugin-folder`.

3. **Write skills**: For each skill, create `skills/<name>/SKILL.md` with frontmatter (name, description) and instructions. Keep under 500 lines; move detailed content to `references/`, `assets/`, or `scripts/` folders. Write descriptions as user situations, not feature summaries.

4. **Build the MCP server** (if needed): Implement the server using TypeScript or Python SDK. Choose authentication type (OAuth, static header, or none). Test with `claude mcp add <url>` or a tunnel. Reference it in `.mcp.json` by URL.

5. **Add interactive UI** (optional): Use MCP Apps to render components in conversations. Reference the resource in tool metadata.

6. **Test on each surface**: 
   - Claude Code: `claude --plugin-dir ./plugin-folder`
   - claude.ai/Cowork: Upload ZIP to Customize > Plugins > Add > Upload plugin
   - Verify skills load, connectors connect, commands appear

7. **Validate before submission**: Run `claude plugin validate ./plugin-folder` and check the developer portal's validation. Fix README (40+ words), LICENSE, and manifest issues.

8. **Submit to directory**: Push to GitHub, go to claude.ai/directory/manage, select Submit new, choose Plugin bundle or MCP connector, and follow the submission form. Submit MCP servers as connectors too, even when a plugin references them.

9. **Monitor after publishing**: Track installs, skill usage, and error rates in the developer portal. Update the plugin when issues arise or features improve.

### Setting Up Claude Tag in Slack

1. **Install the Claude app**: Go to claude.com/claude-for-slack, click Add to Slack, approve permissions.

2. **Pair the workspace**: Send `@Claude connect` in any Slack channel. Claude replies with a pairing code (expires in 15 minutes).

3. **Paste the code**: Go to claude.ai/admin-settings/claude-tag, paste the code, click Pair workspace.

4. **Configure access**: Add Claude to channels, set a monthly spend limit, add connections (GitHub, Jira, etc.), and launch Claude Tag.

5. **Add connections**: Go to Connections tab, add services Claude will access (GitHub, Datadog, Salesforce, etc.). Organization Owners add connectors; members connect with their own accounts.

6. **Migrate from legacy Claude in Slack** (if needed): Set Claude Tag version to "New" on the Advanced tab for each channel still on Legacy.

### Deploying Claude Desktop with MDM

1. **Choose an inference provider**: Claude API (default), Amazon Bedrock, Google Vertex AI, Microsoft Foundry, or a gateway you operate.

2. **Prepare the configuration**: Use the Admin Console (Enterprise Admin Console on claude.ai) or export from Developer > Configure Third-Party Inference.

3. **Deploy via MDM**: Export configuration as .mobileconfig (macOS), ADMX (Windows), or JSON (Linux). Deploy through your MDM tool (Intune, Jamf, etc.).

4. **Verify on devices**: Check that Claude Desktop reads the managed configuration (Settings > Developer > Configure Third-Party Inference opens read-only).

5. **Update configuration**: Changes take effect at next app launch. App re-checks every 10 minutes and prompts users to relaunch for most settings.

## Common Gotchas

- **Plugin name is permanent**: Never change the `name` field in plugin.json after release. Users install by this name; changing it breaks existing installs. Change `displayName` instead.

- **Secrets in plugin files**: Don't put API keys, tokens, or passwords in `.mcp.json`, skills, or scripts. Every person who installs the plugin receives these files. Use connectors with OAuth or have users sign in.

- **Skill descriptions matter**: Claude reads only the `description` field to decide when to load a skill. Write it as user situations ("File an expense when the user mentions a receipt"), not feature summaries ("This skill files expenses"). Vague descriptions mean Claude won't use the skill.

- **MCP server size limits**: Tool results are capped at ~150,000 characters on claude.ai/Desktop, 25,000 tokens on Claude Code. Paginate large results; return summaries first, let users request more.

- **Tool call timeout**: 240 seconds per tool call on claude.ai/Desktop, configurable on Claude Code. Long-running operations should return progress updates or queue the work.

- **OAuth callback URLs must match exactly**: Register both `https://claude.ai/api/mcp/auth_callback` (hosted Claude) and loopback redirects for Claude Code (`http://localhost/callback`, `http://127.0.0.1/callback` with port-agnostic matching). Mismatches cause "Authorization failed" errors.

- **401 required for OAuth discovery**: Return `401 Unauthorized` with `WWW-Authenticate: Bearer resource_metadata="..."` to start sign-in. Claude ignores the header on `200` responses.

- **Zipping plugins correctly**: Zip the plugin folder itself, not its contents. The archive should have `plugin-name/SKILL.md` at the top level, not `SKILL.md` directly. Use `zip -r plugin-name.zip plugin-name/` from the parent folder.

- **Skills in plugins load only when needed**: Claude doesn't read every skill's full SKILL.md at the start. It checks descriptions first, loads matching skills, then opens referenced files. Keep SKILL.md focused; move reference material elsewhere.

- **MCP server discovery fails silently**: If your authorization server isn't reachable, Claude shows "Couldn't reach the MCP server" even though your MCP endpoint is fine. Check that your authorization server's `/.well-known/` paths are reachable from Anthropic's IP range (160.79.104.0/21).

- **Refresh tokens must rotate for public clients**: If Claude registers as a public client (DCR or CIMD), rotate refresh tokens on every use. Return the new token in the same response that invalidates the old one.

- **Claude Code doesn't use Anthropic-held credentials**: Anthropic-held OAuth clients work for claude.ai, Desktop, mobile, and Cowork, but Claude Code uses its own Client ID Metadata Document and loopback redirect. Test Claude Code separately.

- **Plugin validation blocks submission**: Run `claude plugin validate ./plugin-folder` before submitting. The developer portal runs the same checks; fixing issues locally saves submission cycles.

## Verification Checklist

Before submitting a plugin or MCP server:

- [ ] Plugin manifest (`plugin.json`) has all required fields: `name`, `displayName`, `version`, `description`, `license`
- [ ] Plugin `name` is lowercase, hyphens only, 64 characters max, and matches folder name
- [ ] All SKILL.md files have frontmatter with `name` and `description` fields
- [ ] Skill descriptions describe user situations, not features (e.g., "File an expense when..." not "This skill files expenses")
- [ ] No API keys, tokens, or passwords in plugin files, `.mcp.json`, or scripts
- [ ] README.md exists and is at least 40 words (not counting code blocks)
- [ ] LICENSE file exists or `license` field is set in plugin.json
- [ ] All referenced files in SKILL.md exist (references/, assets/, scripts/)
- [ ] Scripts use `${CLAUDE_SKILL_DIR}` for paths in SKILL.md
- [ ] Plugin zipped correctly: `plugin-name/` at top level, not contents directly
- [ ] `claude plugin validate ./plugin-folder` passes with no errors
- [ ] Tested on Claude Code: `claude --plugin-dir ./plugin-folder`
- [ ] Tested on claude.ai: uploaded ZIP, verified skills load, connector connects
- [ ] MCP server OAuth endpoints respond within 10 seconds (30 for refresh)
- [ ] MCP server returns `401` with `WWW-Authenticate: Bearer resource_metadata=...` for protected tools
- [ ] Callback URLs registered: `https://claude.ai/api/mcp/auth_callback` and loopback for Claude Code
- [ ] Tool results stay under size limits (150K chars on claude.ai, 25K tokens on Claude Code)
- [ ] No `.DS_Store`, `Thumbs.db`, or `__MACOSX` in plugin folder
- [ ] Repository under 50 MiB, fewer than 10,000 files, each file under 5 MiB

## Resources

- **Comprehensive page navigation**: https://claude.com/docs/llms.txt lists every page in the documentation
- **Build for Claude**: https://claude.com/docs/build/overview — start here for plugins, MCP servers, and skills
- **Plugin structure and testing**: https://claude.com/docs/plugins/build — folder layout, manifest reference, testing on each surface
- **Create custom skills**: https://claude.com/docs/skills/how-to — write SKILL.md, add resources and scripts, test and measure
- **Build an MCP server for Claude**: https://claude.com/docs/connectors/building/index — plan, authenticate, expose tools, test
- **Authentication for connectors**: https://claude.com/docs/connectors/building/authentication — OAuth types, client registration, token refresh
- **Claude Tag setup**: https://claude.com/docs/claude-tag/admins/setup-overview — pair Slack, add connections, launch
- **Claude Desktop configuration**: https://claude.com/docs/third-party/claude-desktop/configuration — MDM deployment, inference providers, managed settings

---

> For additional documentation and navigation, see: https://claude.com/docs/llms.txt