Deploying Claude Skills across an organization

A Skill encodes a workflow once so an agent runs it the same way every time. Writing one is easy. Getting the right version to a whole team, on every surface they use, without it drifting or leaking, is harder, and few people write down how they do it. Here is how I do it for a 90-person organization.

What a skill is

A skill is a folder with a SKILL.md at its root:

my-skill/
  SKILL.md        # YAML frontmatter (name, description) + markdown instructions
  scripts/        # optional helper scripts
  reference.md    # optional supporting docs, loaded on demand

The frontmatter carries two fields that matter:

---
name: press-release
description: Writes wire-ready press releases with QA checklists and source verification. Use when the user asks to draft or review a press release or announcement.
---

Everything below the frontmatter is the instruction body. Claude loads only the name and description at startup so it knows the skill exists; it pulls the full body into context only when it decides to use the skill. Because of this progressive loading, you can install a hundred skills without filling the context window.

Writing a description that triggers

Whether a skill fires depends on its description. Claude compares every installed skill's description against the task in front of it and picks one, and it passes over vague descriptions. Follow these rules:

Write it in the third person: "Writes press releases…" instead of "I can help you write…". Mixed point of view confuses selection.
Say what it does and when to use it: lead with the capability, then add explicit triggers: "Use when the user mentions PDFs, forms, or document extraction." Claude tends to under-trigger, so name the situations explicitly.
Be concrete: "Helps with documents" loses to "Extracts text and tables from PDFs, fills forms, merges files." Keep the combined description under ~1,500 characters.

If a skill isn't firing when you expect, rewrite the description before you touch the body.

Distributing across surfaces

Most teams trip over this: skills do not sync across surfaces. Claude Code reads them from the filesystem, claude.ai stores them in your account, and the API has its own upload endpoint. A skill you set up in one place is not available in the others, so you distribute to each surface separately.

Claude Code

Claude Code has three scopes, in increasing precedence: project skills in .claude/skills/ (commit them so the repo carries them to the team), personal skills in ~/.claude/skills/ (available across all your projects), and enterprise-managed skills. When the same name exists at multiple levels, the higher-precedence one wins.

The fastest way to install from a public repo is the Vercel Labs skills CLI. It works against any repo that has SKILL.md files in subdirectories, with zero setup on the repo's side:

npx skills add alectivism/organization-ai-skills

It finds the skills, lets you pick, and copies them into ~/.claude/skills/. For a team, a private repo of skills doubles as a plugin: members npx skills add your-org/your-skills or you wire it as a marketplace and /plugin install.

claude.ai (web and desktop)

Skills live under Settings > Skills. To add one, zip the skill folder and upload it. Code execution has to be enabled for skills to run. To give a whole team the same skills, an org owner provisions them centrally: on Team and Enterprise plans, Organization settings > Skills lets an admin upload a skill once and push it to every member. Members can turn a provisioned skill off but can't edit it, which is what you want for a governed workflow.

This is how my coworkers get the same skills I use: I author in the repo, then the org-provisioned copies show up in everyone's claude.ai.

ChatGPT

ChatGPT adopted the same Agent Skills standard, so a skill is the same SKILL.md folder with no re-authoring. An individual adds one at chatgpt.com/skills via Create then Upload, or builds it in-app. A workspace admin manages them at chatgpt.com/admin/skills: enable Skills under Permissions and roles, then publish or share to the workspace (Skills turn on by default for Enterprise on 2026-07-23). For a GitHub-backed, auto-updating source, package the skills as a plugin and run codex plugin marketplace add owner/repo; Codex reads a Claude Code .claude-plugin/marketplace.json in legacy-compatible mode, so one repo can serve both. One gap remains. The managed workspace-skills library is upload-based, so it doesn't re-pull from a repo the way an org-provisioned Claude plugin does.

Govern it like production code

Once more than one person depends on a skill, informal copies drift apart. I keep five controls in place:

Source control: skills live in a repo, with review on changes. An agent follows a skill's instructions on real work, so changes get the same review as code.
One source, many surfaces: author in the repo, then push to Claude Code (CLI/plugin) and claude.ai (zip/org provisioning) from that one source so versions don't fork.
Scoping: bundle sensitive or team-specific skills into a plugin assigned to the group that needs them.
An audit trail: log which skills ran on which tasks. When a skill touches regulated content, your compliance team will ask for that record.
Tool grants: if a skill pre-approves tools, that's a permission decision, so review it like one.

Where to start

Don't try to encode everything at once. Ship three skills you can defend (a drafting skill in your brand voice, a research skill with your sourcing rules, and a review skill with your eval rubric), then add more once people trust them.

For a head start, my Organization AI Skills pack is public: thirteen skills that work out of the box and seventeen templates you fill with your own context. Install the whole set with npx skills add alectivism/organization-ai-skills, or read the individual SKILL.md files in the repo to see how the descriptions are written.