Deploying Claude Skills across an organization

A Skill encodes a workflow once so an agent runs it the same way every time. Authoring one is easy. Getting the right version to a whole team, on every surface they use, without it drifting or leaking, is the part nobody writes down. This is how I do it for a 90-person organization.

What a skill actually 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. That progressive loading is why you can have a hundred skills installed without drowning the context window.

Write the description for the model, not for a human

The single thing that determines whether a skill fires is its description. Claude reads every installed skill’s description against the task in front of it and picks. A vague description never gets selected; a specific one does. Three rules:

• Write it in the third person. “Writes press releases…”, not “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 out loud.
• 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, the fix is almost always the description, not the body.

Distributing across surfaces

The catch most teams hit: 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. You distribute to each surface on its own terms.

Claude Code

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 they can’t edit it — which is exactly 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. The gap that 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, the loose version stops scaling. What I keep in place:

• Source control. Skills live in a repo, with review on changes. A skill is instructions an agent will follow on real work; it deserves the same scrutiny 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 right group rather than the whole org.
• An audit trail. Log which skills ran on which tasks. When a skill touches regulated content, that record is what your compliance team will ask for.
• Tool grants are part of the contract. If a skill pre-approves tools, that’s a permission decision — review it like one.

Where to start

Don’t try to encode everything. Ship three skills you can defend — a drafting skill in your brand voice, a research skill with your sourcing rules, a review skill with your eval rubric — and add from there once people trust them.

If you want a running start, my Organization AI Skills pack is public: six skills that work out of the box and fifteen 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.