How to turn your best workflows into AI skills your whole team can use

Picture two people using the exact same AI coding agent. One types a request, gets a generic answer, cleans it up manually, and moves on. The other types nearly the same request, and the agent formats the document exactly the way their team likes it, follows their company's specific checklist, and hands off a finished result. Same tool. Wildly different outcomes.

The difference isn't a better prompt. It's a skill — a saved, reusable set of instructions that teaches the AI your exact way of doing something, once, so you never have to explain it again.

This guide breaks down what agent skills actually are, how to build one, and how to share your best skills across an entire team using a single GitHub repository that works in both Claude Code and Codex.

What exactly is an AI skill?

An agent skill is essentially an SOP (standard operating procedure) written for AI instead of for a human employee. Instead of re-explaining your formatting preferences or your process every single time you open a chat, you write it down once as a markdown file, and the AI reads it automatically whenever it's relevant.

Anthropic describes this well in its own documentation: Claude operates in a virtual machine with filesystem access, allowing Skills to exist as directories containing instructions, executable code, and reference materials, organized like an onboarding guide you'd create for a new team member. That "onboarding guide" comparison is the whole concept in a nutshell — you're not writing a prompt, you're writing training material.

Technically, a skill is a folder containing a SKILL.md file. According to the open standard both Anthropic and OpenAI have adopted, a SKILL.md file is a manifest and instruction document for AI agents, containing YAML frontmatter with metadata and a Markdown body with step-by-step instructions that tell the AI agent how to perform a specific task. That's it. No code required, no API keys, just clear writing.

The official Agent Skills overview explains that Claude supports both pre-built skills and custom ones you write yourself: Anthropic provides pre-built Agent Skills for common document tasks, and you can create your own custom Skills — once a Skill is available in your environment, Claude uses it automatically when relevant to your request.

Why does this beat just writing a better prompt?

A prompt disappears after one conversation. A skill persists. Once you save it, it lives in your file system permanently, and the agent pulls it in automatically whenever the topic matches — no copy-pasting the same instructions into every new chat.

This matters more than it sounds. Anyone who has ever pasted the same release checklist into a chat window five times knows the pain point skills solve — instead of that instruction living only in your memory (or in a doc nobody reopens), it becomes something the agent actively watches for. One breakdown of Claude Code's internals puts it simply: a skill packages a procedure or body of domain knowledge into a folder that the agent loads only when the current task calls for it, and otherwise ignores at almost no cost.

How do you actually build a skill?

You don't need to be a developer to write one. If you're using Claude Code, custom skills live as plain folders on your machine.

According to Claude Code's documentation, custom skills in Claude Code are filesystem-based and don't require API uploads: you place them in ~/.claude/skills/ (personal) or .claude/skills/ (project). Claude then discovers and uses them automatically once they exist as directories with SKILL.md files.

Here's the basic build process:

Pick one repeatable task. Something you or your team does the same way every time — formatting a Notion doc, writing a release note, structuring a client proposal.
Write down your exact process in plain language, the way you'd explain it to a new hire on day one. Include the specific formatting rules, tone, and structure you want.
Save it as SKILL.md inside a folder named after the skill, with a short YAML header describing what it does and when to use it.
Drop that folder into .claude/skills/ in your project, or ~/.claude/skills/ if you want it available everywhere on your machine.
Test it by asking Claude to do the task naturally — don't force the skill name, just describe the work and see if it gets triggered.

A well-written description field matters more than people expect. Anthropic's own best-practices guidance stresses this: when authoring a skill, check the description — ensure it's specific and includes relevant keywords, because that's how the agent decides which skill applies to which request.

What's a "skill chain" and when do you need one?

Not every process fits in one skill. Bigger workflows — like taking a fully edited video all the way through to a published YouTube upload — often break down more naturally into a sequence of smaller skills that hand off to each other. One skill formats the title and description, the next generates chapter markers, a third handles thumbnail notes, and so on, run in order.

Thinking in chains rather than one giant mega-skill keeps each piece focused and easier to fix later. If your YouTube publishing skill breaks, you only have to debug that one small piece instead of untangling a 40-step monolith.

This is where things go from "personal productivity trick" to "team-wide unfair advantage." Instead of every teammate rebuilding the same skill from scratch (or worse, five slightly different versions floating around in random docs), you centralize everything in one GitHub repository and install that repo as a plugin.

Anthropic's own example repository, anthropics/skills, demonstrates exactly this pattern. As their README explains, you can register the repository as a Claude Code Plugin marketplace by running a command in Claude Code, and once installed, you can ask Claude Code to use a specific skill by name to complete a task.

The setup process, based on Claude Code's plugin discovery documentation, works roughly like this:

Create a GitHub repo to hold your team's skills — one folder per skill, each with its own SKILL.md.
Add it as a marketplace inside Claude Code. GitHub repos are recognized directly in owner/repo format, so pointing Claude Code at your repo URL is enough.
Install the plugin from that marketplace using the plugin's name.
Teammates repeat step 2 and 3 on their own machines, pointing to the same repo.

Because the marketplace lives on GitHub, updates propagate automatically. Push a fix to the shared repo, and the next time each teammate's agent syncs, it pulls the newer version. Claude Code even refreshes marketplaces at install time by default, so people aren't stuck running stale instructions from weeks ago.

For teams that want this to happen without anyone manually re-adding the marketplace, Claude Code supports auto-installing trusted marketplaces at the project level through a settings file, so the moment a team member opens the shared project folder and trusts it, the skills are already there waiting.

Does this work the same way in Codex?

Mostly, yes — and that's by design. OpenAI adopted the same open SKILL.md format for its own coding agent. According to OpenAI's developer documentation on Codex skills, agent skills extend ChatGPT and Codex with task-specific capabilities, and a skill packages instructions, resources, and optional scripts so either product can follow a workflow reliably — skills build on the open agent skills standard.

Codex reads skills from its own local and project-level folders, and for distributing your own reusable skills across a team, OpenAI's own guidance is direct: use this for local setup and experimentation — for reusable distribution of your own skills, prefer plugins. That means the same "one repo, install as a plugin" pattern that works in Claude Code carries over to Codex, which is exactly why keeping skills in a portable, standard format pays off — write once, install in both agents.

What should your first team skill actually be?

Don't start with something ambitious. Start with whatever small, annoying inconsistency shows up in your team's output every single week. A formatting skill that makes every Notion doc match your house style is a good first candidate — low risk, immediately visible, and painless to test since nobody's production pipeline depends on it yet.

Once that one works and people trust it, expand into higher-stakes territory: client-facing document templates, code review standards, or a full content-publishing chain. The Claude Code skills guide and the Agent Skills overview are worth bookmarking as you go — both get updated as the standard evolves, and both cover troubleshooting for when a skill doesn't trigger the way you expect.

What should you actually watch out for?

Speed is tempting, and it's easy to crank out a dozen skills in a weekend because building them feels fast and fun. But a skill that's vague, untested, or copied without understanding what it does will quietly produce bad output at scale — the exact opposite of the consistency you were trying to build. A skill installed with your credentials runs with your permissions, so before pulling in anything from a public marketplace you didn't write yourself, it's worth actually reading what it does.

Treat each skill the way you'd treat onboarding documentation for a real employee: specific, tested, and revised when it stops matching how the team actually works. Skills that get ignored and never updated become exactly as useless as an onboarding doc nobody's touched since 2019.

The teams pulling ahead right now aren't the ones with the fanciest AI setup — they're the ones who took the time to write down what "good" actually looks like, once, clearly, and let the agent handle the repetition from there. Everyone else is still typing the same instructions into a chat box for the hundredth time.