Set up Claude with an AI agent

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

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

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

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.

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