Agents & OrchestrationHow It Works

Building AI Skills: Turning Repeated Workflows into Reusable Tools Your Whole Team Can Use

In brief

A skill is a reusable, parameterized AI workflow stored as a markdown file — a function call where the function is a multi-step AI process. Teams use them to encode institutional knowledge so every team member gets the same quality result on demand, not just the person who figured it out first.

10 min read·

Contents

♡Sign in to save

There's a person on every team who gets dramatically better results from AI than everyone else. They've figured out the right questions to ask, the right data to pull in, the right output format to request. They do it quickly, consistently, and the output is actually useful.

The problem: that knowledge lives in their head. When they're out sick, in back-to-back meetings, or on vacation, their teammates either don't run the workflow at all or run it badly.

A skill is how you capture what they know and make it available to everyone.

What a skill actually is

A skill is a SKILL.md file that contains:

A description of what the skill does (used for discovery — how does Claude know when to invoke it?)
Trigger phrases that activate it
Step-by-step instructions for how to execute the workflow
The expected output format
Which tools to call and in what order

Claude Code loads these files at session start. When a user says "run the deal intel report" or "pull the BDR audit," Claude matches the request against the trigger phrases in the skill files and executes the defined workflow.

A skill is stored in a plugin folder. The plugin is just a directory with a skills/ subfolder. You publish a new skill with a PR. Any team member with Claude Code access gets it immediately.

A concrete example: the deal intelligence skill

Here's what a deal intelligence skill file looks like:

# Deal Intelligence Report

## Description
Generates a structured Deal Intelligence Report for one or more HubSpot deals,
pulling from HubSpot CRM and Gong call data to produce a three-section report:
Discovery (when it started), How It Went (engagement timeline), How's It Going
(current status and risks).

## When to use
When someone asks to "run the deal intel report", "pull deal history", "give me
the full story on [company]", or wants to understand a prospect's engagement
timeline.

## Steps

1. Ask which company or deal to analyze (if not specified)
2. Call `get_deal_by_company_name` with the company name
3. Call `get_gong_calls_for_deal` with the deal ID
4. Call `get_hubspot_activity_timeline` with the deal ID
5. Call `get_contact_history` for each primary contact on the deal

## Output format

### Discovery
[When the deal entered the pipeline, how it was sourced, first contact date,
who initiated, what problem they were trying to solve]

### How It Went
[Chronological timeline of touchpoints: demo calls, follow-up emails,
objections raised, stakeholders involved, notable moments]

### How's It Going
[Current stage, days in stage, risk signals (no activity > 14 days, key
stakeholder went dark, competing vendor mentioned), recommended next action]

When a sales rep says "give me the full history on Acme," Claude loads this skill, follows the steps, makes the tool calls in order, and generates a formatted report — pulling from HubSpot and Gong automatically.

The sales rep who figured out this workflow did so once. Now it's a skill the whole team uses.

What makes a good skill candidate

Not every workflow should be a skill. The economics favor skills that are:

Repeated. If someone does it less than once a month, the overhead of maintaining a skill file isn't worth it. Good candidates run weekly or daily.

Consistent. The workflow should have roughly the same steps every time. If every execution is genuinely different, a skill won't capture it well.

Multi-step. A skill where Claude just calls one API and returns the result isn't much better than calling the API directly. The value is in encoding complex sequences — call this API, then join with that one, then apply this logic, then format like this.

Skill-dependent. The "good output" depends on knowing your business context, not just executing the workflow. The deal intel skill is better because the person who wrote it knows that call transcripts under 30 minutes usually mean the prospect wasn't engaged, and the skill flags that. That's institutional knowledge encoded in the instructions.

High-value skills across teams

Different teams have different high-value workflows. Here are real examples:

Sales:

Deal intelligence report — full engagement history from HubSpot + Gong for any deal
Pre-call research brief — pull everything known about a prospect before a meeting
BDR compliance audit — scan pipeline against SOP, flag accounts without follow-up within 48 hours

Finance:

Monthly variance report — compare actuals from QuickBooks against forecast, flag significant variances
Revenue recognition summary — pull ChargeOver data, apply recognition rules, format for the CFO
Vendor spend summary — aggregate all AP from QuickBooks by vendor for budget review

Customer Success:

Account health brief — product usage, open tickets, renewal status, last call summary
QBR prep — pull all relevant data for a quarterly business review, generate talking points
Renewal risk report — scan all accounts coming up for renewal, flag those with risk signals

Engineering:

PR review brief — summarize recent PRs by area, flag anything touching critical paths
Deploy status check — check recent deploys, error rates, any active incidents
Dependency audit — scan package.json for known vulnerability flags

Operations:

Weekly meeting brief — pull yesterday's Granola notes, extract action items, format agenda for standup
Event pipeline tracker — group conference-sourced deals by event, show stage distribution

The skill lifecycle

1. Identify a repeated workflow.
Watch your team. When does the same person do the same sequence of steps more than once a week? Interview them: "walk me through what you do when you need to prep for a customer call." That's your skill.

2. Write the SKILL.md.
Start with the description and trigger phrases. Then document the steps as specifically as you can. What tools get called? In what order? What logic is applied to the results? What does the output look like?

3. Test and iterate.
Give the skill to the person who originally did the workflow manually. Ask them to run it for 10 real cases. What does it get wrong? What does it miss? What would they do differently? Update the skill based on their feedback.

4. Publish to the team plugin.
Add the skill file to the plugin's skills/ directory. Open a PR. Merge. Every team member with Claude Code access gets it at their next session start.

5. Maintain it.
Workflows change. Data sources change. Output formats change. Treat skills like code — they need maintenance. A designated "skill owner" per skill (usually the person who originally did the workflow) is responsible for keeping it current.

How skills call tools

Skills invoke tools through MCP. When the skill says "call get_deal_by_company_name," Claude makes an MCP tool call to your internal MCP server, which routes to HubSpot, applies ACL checks, shapes the response, and returns clean data.

The skill itself doesn't know about HubSpot's API. It knows about the tool name. This means:

If you change from HubSpot to Salesforce, you update the MCP tool implementation — not all the skills that use it
Access control is enforced at the MCP layer — a sales rep can run the deal intel skill, but a skill that requires hr_admin permission won't work for them even if they have the skill file
Logging happens at the MCP layer — every tool call is audited regardless of which skill triggered it

The compounding effect

The value of skills compounds in a specific way: each skill you publish makes the next skill more valuable.

When you have one skill (deal intel report), you have one workflow automated. When you have ten skills (deal intel, pre-call brief, BDR audit, QBR prep, variance report, account health, deploy status, PR review, vendor spend, event pipeline), each team member has a toolbox of institutional knowledge they can invoke on demand.

The CS manager who goes on parental leave doesn't need to document everything — the skills encode their workflows. The new hire on day three can run the same account health brief as the five-year veteran.

And as you add more MCP tools (more data sources, more services), every existing skill that calls those tools gets more powerful automatically.

Getting started

The fastest path to a working skill:

This week: Pick one workflow that someone on your team does manually more than twice a week. Interview them for 30 minutes. Write the SKILL.md based on that interview.

Next week: Test it with the same person on 5-10 real cases. Fix what's wrong.

Week three: Publish it to your plugin. Watch what the rest of the team does with it.

Month two: Build the second skill based on what you learned from the first.

The first skill takes a week. The second takes three days. The tenth takes a day. By month six, your team is running a dozen workflows that used to require the institutional knowledge of specific people — and anyone can run any of them.