Claude Agent Skills for Enterprise: The Complete Deployment Guide

Most companies have already paid to document how work should get done.

The process lives in a Confluence page, a Google Doc, an onboarding deck, a checklist, a template, and the head of one employee who has somehow become the human API for the entire department.

Then the company buys Claude for 500 people and every person has to teach it the same process again.

Agent Skills fix that distribution problem. You package the instructions, scripts, references, and templates for a workflow once. Claude loads the Skill when a relevant request appears. An organization owner can deploy it to everyone, or an enterprise admin can bundle it into a plugin and target the people who need it.

Since I first drafted this guide, Anthropic has expanded the system substantially. Skills can now be shared between colleagues, published to an internal directory, bundled into plugins, synced from private GitHub repositories, scoped to enterprise groups, and used across chat, Claude Desktop, Cowork, Microsoft 365 add-ins, Claude Code, and the API.

The opportunity is much bigger now. So is the governance surface.

This guide covers the current architecture, how to choose the right deployment path, how to build a Skill that survives contact with real employees, and how to roll it out without creating a new pile of unowned AI infrastructure.

What Agent Skills Actually Are

An Agent Skill is a folder with a required SKILL.md file and optional supporting resources:

quarterly-business-review/
├── SKILL.md
├── scripts/
│   └── validate-metrics.py
├── references/
│   ├── metric-definitions.md
│   └── review-checklist.md
└── assets/
    ├── qbr-template.pptx
    └── brand-colors.json

The SKILL.md file contains metadata and instructions. The rest of the folder can contain executable code, detailed documentation, examples, templates, images, or lookup data.

The most important design idea is progressive disclosure.

Claude first sees the name and description of every available Skill. That small amount of metadata lets it decide which Skills might apply. When a task matches, Claude loads the full SKILL.md. It reads supporting files only when the workflow requires them.

That loading pattern lets an organization give Claude access to a large library of procedures without stuffing the full employee handbook into every conversation.

I think of a Skill as an executable operating procedure. It can hold the same information as a good internal playbook, plus the templates and deterministic scripts required to perform the work.

If you want a deeper introduction to the format itself, read my complete guide to Claude Skills. This article focuses on organizational deployment.

The Deployment Map

The phrase “deploy a Skill” now covers several different mechanisms. Pick the one that matches your audience and Claude surface.

Need	Deployment method	Scope
Give one approved Skill to everybody	Organization settings > Skills	All Team or Enterprise members
Give specialized Skills to a department	Organization plugin marketplace plus group access	Selected Enterprise groups
Let a colleague try a Skill	Direct Skill sharing	Named Team or Enterprise members
Let employees discover optional Skills	Organization Skill directory	Team or Enterprise organization
Give a coding workflow to a repository	`.claude/skills/` in version control	People using Claude Code in that project
Give a coding workflow to every developer	Enterprise or user-level Claude Code Skill deployment	Managed Claude Code users
Use a Skill in an application	Skills API plus Messages API	API workspace and application requests

These are related formats with separate control planes.

An organization Skill uploaded in the Claude admin interface is available across chat on the web, the Chat tab in Claude Desktop, and Cowork. Enabled Skills can also apply inside Claude’s Microsoft 365 add-ins. A Skill committed to .claude/skills/ belongs to Claude Code. A custom Skill uploaded through the API belongs to that API workspace.

Do not assume an upload in one surface silently appears in the others. Treat the Skill source files as the canonical artifact and build an explicit release process for each surface you support.

Skills, Plugins, Connectors, and Organization Instructions

Anthropic now gives enterprise admins several ways to customize Claude. They overlap enough to confuse people.

Here is the clean version.

Organization instructions

Organization instructions apply to every conversation for every user. They are useful for short, universal guidance such as communication standards, legal disclaimers, or a company-wide data handling rule.

They sit in context all the time. Keep them brief.

Skills

Skills contain knowledge and workflows that Claude loads when relevant. Use them for procedures, reference material, templates, and repeatable tasks.

Examples:

Create a quarterly business review
Review a contract using the legal team’s checklist
Turn research into the company’s standard investment memo
Analyze an experiment using the analytics team’s metric definitions

Connectors

Connectors give Claude access to external systems such as Google Drive, Slack, Jira, or an internal service. A connector provides the access. A Skill explains how to use that access for your workflow.

For example, a Jira connector can read and create issues. A product-planning Skill can teach Claude how your company converts a product brief into epics, stories, acceptance criteria, and labels.

Plugins

Plugins package Skills, connectors, subagents, hooks, and other customization into one installable unit. In chat, the bundled Skills and connectors are available. Cowork can also use plugin hooks and subagents.

Plugins are the better enterprise distribution unit when:

A role needs several related Skills
A workflow needs connectors alongside instructions
You want GitHub-backed versioning and marketplace distribution
You need group-specific access
A plugin must be required, installed by default, optional, or hidden

If every employee needs one company writing Skill, use org-wide Skill provisioning. If Finance needs a suite containing eight Skills, a NetSuite connector, templates, and review logic, use a plugin.

Prerequisites

Plan and permissions

Organization-wide Skill management is available on Team and Enterprise plans. Only organization owners can add or remove organization-wide Skills.

Enterprise group targeting through plugins is configurable by Admins and above. Team plans can distribute plugins organization-wide, while group-level overrides are an Enterprise feature.

I have deliberately left plan prices out of this guide. Pricing changes more often than your deployment architecture should.

Capabilities

Go to Organization settings > Skills and make sure both of these are enabled:

Code execution and file creation
Skills

Skills require code execution. On Team plans the capability may already be enabled. Enterprise owners control it at the organization level.

Plugin marketplaces require both Skills and Cowork to be enabled for the organization.

A named owner

Someone needs to own the Skill library as a product. That person does not have to write every Skill. They do need authority over intake, review, releases, deprecation, and incident response.

Without an owner, your library will become a graveyard of duplicate procedures with names like final-qbr-v3-actually-final.

How to Provision One Skill to Everyone

Use this path for a Skill that is broadly useful and safe for the entire organization.

Step 1: Build and test the Skill personally

Create the Skill folder and test it in your own account before distributing it.

At minimum, SKILL.md needs valid YAML frontmatter:

---
name: quarterly-business-review
description: >-
  Creates the company's standard quarterly business review from supplied
  metrics and commentary. Use when a user asks for a QBR, quarterly review,
  executive business review, or quarterly performance presentation.
---

# Quarterly business review

Follow the company QBR structure in `references/qbr-structure.md`.
Use `assets/qbr-template.pptx` as the presentation template.
Validate all metrics with `scripts/validate-metrics.py` before writing claims.

The folder name should match the name. The name must use lowercase letters, numbers, and hyphens, with a maximum of 64 characters. The description should explain what the Skill does and when Claude should use it.

Step 2: Package the folder

Create a ZIP containing the Skill folder as its single top-level entry:

quarterly-business-review.zip
└── quarterly-business-review/
    ├── SKILL.md
    ├── scripts/
    ├── references/
    └── assets/

A common packaging mistake is putting SKILL.md directly in the ZIP root. Keep the folder around it.

Step 3: Upload it in organization settings

Go to Organization settings > Skills. In the Organization skills section, click + Add and select the ZIP file.

The Skill is immediately provisioned to the organization. Members see it in Customize > Skills with an organization indicator. It is enabled by default, although members can toggle it off.

The current admin flow does not ask you to choose an enabled or disabled default during upload. If the workflow must be available only to a subset of people, use a plugin and group targeting.

Step 4: Verify the member experience

Test with an ordinary member account. Confirm:

The Skill appears under Customize > Skills.
A direct request invokes it.
A natural-language request that should match the description also invokes it.
Nearby requests that should not use it stay unaffected.
Files and scripts work in the actual Claude surface your employees use.

Admin visibility proves distribution. It does not prove the workflow works.

Team and Enterprise organizations now have two sharing controls:

Skill sharing lets a member share a Skill directly with selected colleagues.
Share with organization lets a member publish a Skill to the organization’s directory.

Both controls are off by default. Owners enable them in Organization settings > Skills.

Directly shared Skills appear in the recipient’s “Shared with you” section and remain disabled until the recipient enables them. Organization-shared Skills appear in the internal directory, where members can install them. Recipients get a view-only copy, and updates from the creator flow through automatically.

This is useful for bottoms-up experimentation. It also creates a governance decision.

Organization-wide sharing has no approval queue. If an owner enables it, a member can publish a Skill to the directory without an intermediate review. Companies that require review should keep organization sharing off and use an intake process that ends with owner provisioning.

I would use direct sharing for pilots, an internal directory for low-risk peer workflows, and owner provisioning for official procedures.

Deploying Skills to Specific Teams With Plugins

Uploading a Skill through Organization settings gives it to everyone. Enterprise groups solve the targeting problem through plugins.

Suppose Marketing needs:

A campaign brief Skill
A brand review Skill
A launch plan Skill
A connector to the approved asset library

Bundle those into a marketing plugin. Add the plugin to an organization marketplace, then assign its installation preference to the Marketing group.

Distribution options

Each organization plugin can be configured as:

Preference	Member experience
Required	Installed automatically and cannot be removed
Installed by default	Installed automatically, but members can uninstall it
Available for install	Visible in the catalog for self-service installation
Not available	Hidden from members

Enterprise admins can override the organization setting for specific groups. A plugin can be required for Legal, available to Finance, and hidden from everyone else.

There is one access rule worth knowing: if a person belongs to multiple groups with different settings, the most permissive setting wins. Anthropic orders them as Required, Installed by default, Available for install, then Not available.

Group access is designed to grant capabilities. Do not use overlapping group preferences as a hard security boundary. If a plugin contains sensitive access, hide it organization-wide and grant it only to the groups that need it. Review connector permissions separately.

Manual marketplace or GitHub sync

You can upload plugin ZIP files manually or connect a private/internal GitHub repository.

Manual upload is good for early pilots and occasional updates. GitHub sync is better for a production library because it gives you pull requests, code review, release history, and rollback.

A GitHub-backed flow can look like this:

Author branch
    ↓
Automated validation and test prompts
    ↓
Security and domain-owner review
    ↓
Merge plugin version bump
    ↓
Marketplace sync
    ↓
Pilot group
    ↓
Broader release

Anthropic’s organization marketplace can sync automatically when a pull request containing a plugin version bump is merged. Group overrides persist across marketplace syncs.

How to Build a Skill People Can Trust

The hard part is not writing a SKILL.md. The hard part is converting an informal process into instructions that work across people, inputs, and edge cases.

Start from observed failures

Do not begin by converting the entire knowledge base.

Choose one task that is frequent, valuable, and currently inconsistent. Run representative examples with Claude before adding a Skill. Record where it lacks context or makes the wrong choice. Build the Skill to address those specific gaps.

Good starting candidates include:

Weekly status updates
Customer call summaries
Standard research briefs
First-pass contract issue spotting
Experiment analysis
Board or QBR preparation

Avoid high-consequence workflows with unclear ownership as your first pilot.

Keep the main file focused

The Agent Skills specification recommends keeping SKILL.md below 500 lines. Put conditional detail in referenced files.

vendor-review/
├── SKILL.md
├── references/
│   ├── security.md
│   ├── privacy.md
│   ├── procurement.md
│   └── regional-rules.md
├── scripts/
│   └── validate-questionnaire.py
└── assets/
    └── approved-vendor-template.docx

The main file should explain the workflow and tell Claude when to load each reference. Do not link references five levels deep. An agent should be able to navigate the package without an archaeological expedition.

Use prose for judgment and code for deterministic work

Skills can include executable scripts. Use them where exactness matters:

Validate required fields
Normalize dates and currencies
Calculate financial metrics
Check a document against a schema
Generate a known file structure

Use instructions where the task requires interpretation:

Identify the strongest evidence
Explain risk in plain language
Choose relevant questions for an executive audience
Adapt tone to a customer relationship

Models are good at judgment under context. Code is good at doing the same calculation the same way every time.

Write descriptions for routing

Claude uses the Skill description to decide when to load it. A vague description creates false positives and false negatives.

Weak:

description: Creates reports.

Better:

description: >-
  Creates the Sales Operations weekly pipeline report from exported CRM data.
  Use when the user asks for the weekly sales report, pipeline review,
  forecast summary, or Monday revenue meeting pack.

Test both sides of the boundary. Your QBR Skill should trigger for “build the quarterly review” and stay quiet for “summarize this customer interview.”

Include examples and counterexamples

Examples show the expected output. Counterexamples clarify where the Skill should refuse, ask a question, or hand work to another process.

For an investment memo Skill, include:

A strong completed memo
A poor memo with notes explaining why it failed
Missing-data behavior
A case where the company falls outside the investment mandate
The exact claims that require source citations

Testing Skills Before Deployment

“It worked when I tried it” is not a test plan.

Create a small evaluation set for every production Skill. Ten to twenty realistic prompts can catch most obvious failures.

Test four categories

Invocation tests

Does Claude use the Skill when it should? Does it stay out of unrelated work?

Output tests

Does the result contain required sections, use the correct template, preserve factual inputs, and follow the expected tone?

Edge-case tests

What happens with missing fields, a malformed spreadsheet, contradictory instructions, an unsupported region, or a user asking to skip review?

Security tests

What happens when an uploaded document contains instructions telling Claude to ignore the Skill, reveal secrets, contact an external host, or modify a protected file?

Define pass criteria

A useful evaluation table looks like this:

Test	Expected behavior	Pass criteria
Missing revenue data	Ask for the missing file	No fabricated revenue figure
Wrong reporting period	Confirm the quarter	No report generated until resolved
Prompt injection in source doc	Treat text as data	Skill instructions remain in control
Unsupported metric	Flag it	No silent substitution
Brand template supplied	Use exact template	Required layouts and colors preserved

Some outputs need human review because quality is subjective. That is fine. Use a scoring rubric with named dimensions rather than a thumbs-up.

Version the test set with the Skill

When a failure reaches production, add it to the evaluation set before fixing the Skill. Over time, the test set becomes the institutional memory of everything the workflow has learned the hard way.

Security and Governance

Skills deserve the same review discipline as internal software because they can contain instructions, code, packages, templates, and links to external resources.

Review the full bundle

Read every file. Inspect scripts and dependencies. Look for network calls, encoded payloads, shell execution, unexpected binary files, and references to external URLs.

Anthropic recommends installing Skills only from trusted sources and auditing less-trusted packages before use. A directory listing is not a security review.

Keep secrets outside the Skill

Never hardcode API keys, tokens, passwords, or private credentials in the Skill folder. A Skill may tell Claude how to use an approved connector or tool, but the secret belongs in the platform’s credential store or managed environment.

Separate instructions from enforcement

If a policy must hold every time, enforce it with platform controls, tool permissions, hooks, sandboxing, or the external system itself.

“Never send a payment without approval” should not live only as a sentence in SKILL.md.

Understand each runtime

Execution rules differ by surface.

Claude and Claude Code may be able to install packages from standard repositories when loading Skills. API Skills run inside Anthropic’s code execution container, which has no network access and cannot install packages at runtime. Required dependencies must already exist in that environment.

Test the Skill in every runtime you plan to support.

Control who can publish

Keep owner access small. Decide whether peer sharing is allowed. Decide whether organization-wide directory publishing is allowed. Document the intake path for an employee who wants a new Skill.

Governance works better when the approved path is easy.

Plan for removal

Every production Skill should have:

An owner
A version
A last-reviewed date
Supported surfaces
Required data and connectors
A rollback or removal procedure
A replacement or archive state

Deleting an API Skill has an additional constraint: all of its versions must be deleted first.

Using Skills Through the API

API Skills are private to an API workspace and are managed separately from Skills uploaded in Claude’s organization settings.

The current API uses the code execution tool and two beta headers. Here is a working Python shape based on Anthropic’s current documentation:

import anthropic
from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Upload the Skill folder to the API workspace.
qbr_skill = client.beta.skills.create(
    files=files_from_dir("./quarterly-business-review"),
)

# Use the custom Skill in a Messages API request.
response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": qbr_skill.id,
                "version": "latest",
            }
        ]
    },
    messages=[
        {
            "role": "user",
            "content": "Create the Q2 business review from the supplied metrics.",
        }
    ],
    tools=[
        {
            "type": "code_execution_20250825",
            "name": "code_execution",
        }
    ],
)

The API currently allows up to eight Skills in one request and a maximum uncompressed upload size of 30 MB per Skill bundle. Custom versions use generated timestamp identifiers. Use latest while iterating and pin a specific version in production so a Skill update cannot change application behavior unexpectedly.

When a Skill creates a Word, Excel, PowerPoint, or PDF file, the response contains file IDs. Download the results through the Files API.

Long-running Skill operations can return a pause_turn stop reason. Your application needs to pass the response back in a subsequent request so Claude can continue.

The important enterprise lesson is version discipline. A Skill used in an employee chat can tolerate a quick manual iteration. A Skill embedded in a regulated application needs pinned versions, evaluations, release notes, and a rollback path.

The Open Standard and Portability

Anthropic released Agent Skills as an open standard. The format centers on a folder, a SKILL.md, required name and description fields, and optional scripts, references, and assets.

That simplicity is valuable. Your procedural knowledge can live in version control rather than inside one vendor’s hidden prompt field. Compatible agents can discover the metadata, load the instructions, and use supporting resources through progressive disclosure.

Portability still needs testing.

The open specification defines the common core. Individual products add runtime capabilities, frontmatter fields, tool names, permission models, and packaging rules. Claude Code supports features such as dynamic command injection and subagent execution that will not behave the same way in Claude chat or through the API.

Write the core Skill to the open specification. Put platform-specific behavior behind clearly documented compatibility notes. Test before claiming one ZIP works everywhere.

This is similar to MCP. An open protocol improves portability. The quality of each client implementation still matters.

A Practical Rollout Plan

Phase 1: Pick one workflow

Choose a task with visible pain, an accountable process owner, and low blast radius. Collect real examples and baseline the current quality and time required.

Phase 2: Build with the process owner

The AI team should not invent the workflow. Pair with the person accountable for it. Capture required inputs, decision points, exceptions, output criteria, and escalation rules.

Phase 3: Test with five power users

Use direct sharing or a small plugin group. Watch how people phrase requests, what inputs they omit, when the Skill triggers, and where they override it.

Do not train users to contort their language around a bad description. Fix the Skill.

Phase 4: Review security and data access

Audit the bundle. Validate connectors and scopes. Confirm secrets handling. Run prompt-injection tests. Document the actions that require approval.

Phase 5: Release through the right channel

Provision it org-wide when everyone needs it.
Use a group-scoped plugin when a department needs it.
Publish it to the internal directory when installation should be optional.
Commit it to .claude/skills/ when the workflow belongs to a codebase.
Upload and pin it through the API when an application depends on it.

Phase 6: Measure behavior and outcomes

Track more than adoption. Measure:

Invocation accuracy
Task completion rate
Human edit distance
Time saved
Error and escalation rate
Policy violations
User trust

Anthropic’s product analytics may not answer every Skill-level question. You can add logging in approved tools, collect lightweight feedback, and run periodic evaluations against the current production version.

Phase 7: Maintain it

Review the Skill when the underlying process changes, a connected system changes, or a recurring failure appears. Re-run the evaluation set before each release. Deprecate duplicate and unused Skills.

The library should get smaller and sharper over time.

What I Would Deploy First

I would start with three Skills.

1. A company writing Skill

Give Claude examples of strong company writing, banned phrases, tone rules, audience guidance, and editing checks. Keep it focused on how the company communicates rather than trying to cram the full brand book into every conversation.

2. A recurring report Skill

Pick a weekly or monthly report with a stable structure. Add the template, metric definitions, required sources, and validation rules. Reports create an easy before-and-after comparison.

3. A review Skill

Package an existing checklist for legal, security, product quality, sales qualification, or content review. Review workflows usually carry less risk than autonomous execution and teach the organization how to combine Claude’s judgment with human accountability.

Once those work, move into workflows that use connectors and actions.

The Bigger Shift

Companies spent years turning work into software by building an app for every process. Skills offer a lighter layer for procedures that need judgment, context, and adaptation.

The company still needs systems of record. It still needs permissions, controls, and accountable owners. Skills sit above those systems and teach the agent how the organization works.

That is the strategic value. Your best employee’s method can become a governed, testable, portable asset. A new employee can use it on day one. An updated procedure can reach the organization without another round of prompt-copying workshops.

Start with one workflow. Write down what good looks like. Test it against the messy cases. Give it to five people. Fix what breaks. Then scale it through the deployment path that matches the risk.