How to Create a Skill: A Practical Guide to Agent Skills
Build an agent skill for Claude end to end: when a skill beats an MCP server, SKILL.md frontmatter that actually triggers, progressive disclosure, bundled scripts and references, evals, debugging, and rolling it out to your whole team.
By Osamah Aldoaiss · 18.11.2026
Every team that uses an AI assistant seriously ends up repeating itself. The same paragraph about tone of voice pasted into every chat. The same "remember, prices come from the price list, never invent one" reminder. The same explanation of how your proposals, reports or release notes are structured. A skill is how you stop repeating yourself: a folder that packages your instructions, templates, reference material and scripts so the assistant loads them by itself, exactly when the task needs them.
This guide is a build-along. By the end you will have a working, tested skill — a proposal-writing skill with a bundled validation script — running in Claude Code and claude.ai, plus the method to roll it out to a team. It complements our guide on how to build an MCP server: MCP connects the assistant to your systems, skills teach it how your company does the work. Most of the practical AI tools we build for clients use both, and the sections on evals, failure modes and rollout come from skills that misfired first.
Copy & paste
Start here: plan it with AI
Copy this prompt into any LLM or coding agent (Claude, ChatGPT, Cursor …) to apply this guide to your own project.
Guide: https://blackcard.dev/guides/how-to-create-a-skill Markdown version (fetch this for the full method): https://blackcard.dev/guides/how-to-create-a-skill.md I want to create an agent skill (a SKILL.md folder) for Claude, following the guide "How to Create a Skill" from blackcard.dev. The method in short: pick ONE repeated task where the assistant needs the same instructions every time; collect 3 real examples of the task and note what the assistant gets wrong without help; write the frontmatter first (name: lowercase-hyphens, max 64 chars, no "claude"/"anthropic"; description: third person, says what it does AND when to use it, key trigger words in the first 200 characters); keep the SKILL.md body short (well under 500 lines) and move detail into references/ files linked one level deep; put deterministic checks into scripts/ that the assistant runs instead of reads; test triggering (should fire / should not fire), then quality against a 3-5 case eval list, with and without the skill; ship it via the repo (.claude/skills/), a claude.ai zip upload, or a plugin marketplace for the team. Before writing anything, interview me one question at a time: 1. Which task do I want to package, and how often does my team do it? 2. What do I currently have to explain to the assistant every time (tone, structure, rules, sources)? 3. What does a great output look like? Can I share 2-3 real examples? 4. Which mistakes does the assistant make today without guidance? 5. Is any part of the task deterministic enough to check with a script (structure, numbers, length, forbidden words)? 6. Does the task need live data from a system (CRM, shop, database)? If yes, that part belongs in an MCP server, not the skill. 7. Where will it run (Claude Code, claude.ai, API) and who needs it (just me, one repo, the whole team)? Then produce: a skill name, a description under 200 characters, a folder tree, a section outline for SKILL.md, the list of reference files and scripts with one line each, and a 5-case eval list (3 should trigger, 2 should not). Challenge me if the task is too broad for one skill.
What a skill actually is
A skill is a directory with a SKILL.md file in it. That file starts with a short block of YAML frontmatter — at minimum a name and a description — followed by plain Markdown instructions. Optionally, the directory also contains supporting files: reference documents, templates, examples and executable scripts.
writing-proposals/
├── SKILL.md ← required: frontmatter + instructions
├── references/
│ ├── pricing.md ← read only when prices come up
│ └── case-studies.md ← read only when proof is needed
├── assets/
│ └── proposal-template.md
└── scripts/
└── check_proposal.py ← executed, never loaded into context
The format started at Anthropic and is now published as an open standard (Agent Skills), so the same folder works across Claude Code, claude.ai, the Claude API and a growing list of other agents that read SKILL.md. Write it once, use it in several places.
The magic is in how it loads. This is called progressive disclosure, and it is the single most important idea in this guide:
- Level 1 — metadata, always loaded. At startup, only the
nameanddescriptionof every installed skill go into the assistant's context — roughly 100 tokens per skill. This is how the assistant knows the skill exists. - Level 2 — instructions, loaded when triggered. When a request matches the description, the assistant reads the body of
SKILL.md. Anthropic's guidance is to keep this under 500 lines (well under 5,000 tokens). - Level 3 — resources, loaded as needed. Reference files enter context only when the instructions point the assistant to them and the task needs them. Scripts are run, and only their output enters context — the code itself costs nothing.
Because of this, you can install dozens of skills without slowing anything down, and a single skill can bundle a 40-page reference manual that costs zero tokens until the one section that matters is read.
Skill or MCP server? Choosing the right tool
This is the question we get most, and the answer is simple once you see the split:
- A skill is know-how. Procedures, house rules, templates, examples, checklists and local scripts. "How we write proposals." "How we review pull requests in this repo." "How our monthly report is structured." No live connection, no authentication, no server to run.
- An MCP server is access. A live, authenticated connection to a system: your CRM, shop, ERP, database or ticketing tool. "Look up this customer." "Create a draft invoice." It runs as a program and enforces permissions.
Practical decision rules:
- If the assistant needs instructions it keeps forgetting, write a skill.
- If it needs data or actions it cannot reach, build an MCP server — the MCP server guide walks through it.
- If it needs both — the very common case — build the MCP server for access and a skill that teaches how to use those tools well: which tool to call first, which fields matter, which actions always need human confirmation. A skill can reference MCP tools by their fully qualified name (for example
Orders:get_order_status) so the assistant finds the right one even when several servers are connected. - If the "skill" would be one sentence ("always answer in British English"), it belongs in a project instruction file such as
CLAUDE.mdor your project's custom instructions, not in a skill.
A cost note that tips many decisions: a skill has no hosting, no OAuth and no uptime to worry about. If a task can be solved with instructions plus a local script, a skill is the cheaper, faster and safer option.
What you need
- An assistant that supports skills. This guide uses Claude Code for building and testing (fastest feedback loop: skills reload live as you edit) and shows how to ship the same folder to claude.ai. On claude.ai, custom skills are available on paid plans with code execution enabled.
- Python 3.8 or newer for the example's validation script (standard library only, nothing to install).
- A text editor and a terminal.
- Three real examples of the task you want to package — past proposals, reports, reviews. This matters more than anything technical: skills built from imagined requirements fail; skills built from real examples work.
Time and cost, realistically: a pure-instructions skill takes 30–60 minutes including testing. A skill with references, a validation script and a proper eval round, like the one below, takes half a day to a day. Rolling a library of skills out to a team through a plugin marketplace is another one to three days, mostly spent on evals and agreeing on conventions. There is no extra license cost; skills run on the plan you already have, and the always-on token cost is about 100 tokens per installed skill.
Step 1: Pick one task and collect evidence
The most common mistake is the "company knowledge" skill that tries to cover everything. A skill should do one job your team repeats weekly. Good candidates:
- Writing proposals, quotes or statements of work in your structure and with your prices
- Producing a recurring report (weekly client update, monthly KPI summary) in a fixed format
- Reviewing code, copy or designs against your own checklist
- Applying your brand voice to marketing drafts (a natural next step after you build a brand guide)
- Running a release, migration or onboarding procedure that must happen in a fixed order
Our example is a proposal-writing skill for a small services business. Before writing a line, do this:
- Ask the assistant to write a proposal without any skill, using a realistic request ("Draft a proposal for Acme Logistics: they re-type emailed orders into their ERP, three people, about 12 hours a week").
- Write down everything that is wrong. Typical findings: it invents prices, uses a different structure every time, writes 1,800 words when owners read 600, and leans on words like "seamless" and "cutting-edge" that your clients distrust.
- Gather the material that would fix those failures: your price list, your section order, one or two of your best past proposals, your banned-phrases list.
That list of failures is your specification. Every line in the skill should exist because it fixes one of them.
Step 2: Create the folder in the right place
Where a skill lives decides who gets it. In Claude Code:
- Personal (all your projects):
~/.claude/skills/<skill-name>/SKILL.md - Project (everyone who clones the repo):
.claude/skills/<skill-name>/SKILL.md - Plugin (distributed to a team, covered in Step 9):
<plugin>/skills/<skill-name>/SKILL.md
Start personal while you iterate:
mkdir -p ~/.claude/skills/writing-proposals/{references,assets,scripts}
cd ~/.claude/skills/writing-proposals
touch SKILL.md references/pricing.md references/case-studies.md assets/proposal-template.md scripts/check_proposal.py
Naming rules, using the strictest set so the skill works on every surface: the name is at most 64 characters, only lowercase letters, numbers and hyphens, contains no XML tags and does not use the reserved words anthropic or claude. Keep the folder name identical to the name field — claude.ai uploads expect it, and it avoids confusion everywhere else. Anthropic recommends gerund names (writing-proposals, reviewing-pull-requests, analyzing-spreadsheets); whatever you choose, keep one pattern across your library. Avoid vague names like helper, utils or company-stuff.
Step 3: Write the frontmatter — the part that decides everything
The description is the only thing the assistant sees before deciding to load your skill. If it is vague, the skill never fires; if it is too broad, it fires when it shouldn't. Write it in the third person (it is injected into the system prompt), and make it answer two questions: what does it do and when should it be used, using the words your team actually types.
---
name: writing-proposals
description: Drafts client proposals, quotes and statements of work in our house structure with prices from our official price list, then validates the draft. Use when the user asks for a proposal, quote, offer, SOW or pricing document for a client or prospect.
---
Limits to design around:
- 1,024 characters is the hard maximum for
descriptionin the open format and the API. - Claude Code truncates the combined
descriptionand optionalwhen_to_usetext at 1,536 characters in its skill listing, so put the key use case first. - claude.ai's upload documentation has listed a much tighter 200 characters. Our rule: make the first 200 characters self-sufficient, then add detail after that.
Weak versus strong:
# Weak: no trigger words, no "when". This will rarely fire.
description: Helps with documents for clients.
# Weak: first person and too broad. Fires on every email.
description: I can help you write anything you send to clients.
# Strong: specific job, the vocabulary users type, an explicit trigger.
description: Drafts client proposals, quotes and statements of work in our house structure with prices from our official price list. Use when the user asks for a proposal, quote, offer, SOW or pricing document.
Claude Code supports several optional fields on top of the two required ones. The ones worth knowing for a first skill:
---
name: writing-proposals
description: Drafts client proposals, quotes and statements of work ...
# Only the user can start it with /writing-proposals; the assistant never auto-loads it.
# Use for skills with side effects (deploys, sending, publishing).
disable-model-invocation: false
# Shown as an autocomplete hint after /writing-proposals
argument-hint: [client-name]
# Tools the assistant may use without asking while the skill runs
allowed-tools: Read Write Bash(python3 *)
---
Two cautions. First, Claude Code silently ignores a misspelled field name — allowed_tools with an underscore does nothing — so copy names exactly. Second, these extra fields are Claude Code features; claude.ai and the API read name and description and ignore the rest, so never rely on them for safety.
Step 4: Write the SKILL.md body
The body is an onboarding brief for a very capable new colleague. It should contain what that colleague cannot know — your rules, your structure, your sources — and nothing they already know. Do not explain what a proposal is. Here is the complete file:
---
name: writing-proposals
description: Drafts client proposals, quotes and statements of work in our house structure with prices from our official price list, then validates the draft. Use when the user asks for a proposal, quote, offer, SOW or pricing document for a client or prospect.
---
# Writing proposals
## Before drafting
Collect these facts. Ask the user for anything missing, one question at a time.
Never guess a fact about the client.
- Client name and contact person
- The problem in the client's own words, with a number (hours, cost, errors)
- Which package fits (see Pricing below)
- Desired start date
## Workflow
Copy this checklist into your response and tick it off:
```
- [ ] 1. Facts collected
- [ ] 2. Package chosen from references/pricing.md
- [ ] 3. Draft written from assets/proposal-template.md
- [ ] 4. Validation script passed
- [ ] 5. Draft shown to user with open questions listed
```
1. Read `assets/proposal-template.md` and follow its section order exactly.
2. Write in plain language. One page for a busy owner: 900 words maximum.
3. Save the draft as `proposal-<client>.md` in the working directory.
4. Run the validator. The script path is relative to this skill's
directory (the folder this SKILL.md is in), not the working directory:
```bash
python3 scripts/check_proposal.py proposal-<client>.md
```
5. If it prints FAILED, fix every listed problem and run it again.
Only show the draft to the user once it prints PASSED.
## Pricing
Prices come ONLY from `references/pricing.md`. Never invent, round or
discount a price. If no package fits, say so and propose the closest
package plus a note that a human must confirm a custom price.
## Proof and case studies
When the user asks for references, or the client is in logistics,
e-commerce or professional services, read `references/case-studies.md`
and use at most one case that matches the client's industry.
## Tone
- Concrete numbers over adjectives: "saves about 12 hours a week", not "boosts efficiency".
- Never use: cutting-edge, synergy, world-class, best-in-class, seamless, revolutionary.
- Address the client as "you", refer to us as "we".
## Example
Input: "Proposal for Acme Logistics. They re-type emailed orders into
their ERP, 3 people, about 12 hours a week. Start in January."
Good summary line: "We automate your order intake so nobody re-types
emails into the ERP again, which frees about 12 hours a week."
What that body does well, and why each choice matters:
- It is short. Around 60 lines. Detail lives in the reference files.
- It names files exactly and says when to read each one ("when the user asks for references"). Without that sentence, the assistant either never opens the file or reads all of them every time.
- It says whether to run or read a script. "Run the validator" tells the assistant to execute it, not to load its source into context.
- It has a feedback loop: draft, validate, fix, validate again. This one pattern produces a bigger jump in output quality than any amount of extra instruction text.
- It uses one term per concept. Always "draft", always "package", always "validator". Mixing synonyms makes instructions harder to follow.
- It contains a concrete example. One input/output pair communicates tone better than five adjectives.
Match the strictness to the risk. For open-ended work (tone, structure of an argument), give direction and trust the model. For fragile operations (prices, migrations, anything legal), be exact and tell it not to improvise.
Step 5: Add references and assets (progressive disclosure in practice)
Reference files hold facts the assistant looks up; assets hold material it copies or fills in. Create the price list at references/pricing.md:
# Pricing
- Discovery sprint: 2 workshops, process map, written recommendation. €2.400
- Starter build: one workflow or tool, 2-3 weeks, 30 days support. €6.500
- Growth build: up to three connected workflows, 4-6 weeks. €14.000
- Monthly care: monitoring, fixes, small changes, per month. €900
And the template at assets/proposal-template.md:
# Proposal for [CLIENT]
## Summary
One sentence: what changes for the client, with a number.
## The problem
Two to four sentences in the client's words. Include the cost of doing nothing.
## What we will do
Three to five bullet points, each a deliverable the client can check.
## Timeline
Start date, milestones, go-live date.
## Investment
Package name and price from references/pricing.md. Optional add-ons listed separately.
## Next step
One action for the client, with a date.
Rules that keep references working as the skill grows:
- Keep every reference one level deep from
SKILL.md. IfSKILL.mdpoints toadvanced.mdwhich points todetails.md, the assistant may only preview the deeper file and miss what it needs. Link everything directly fromSKILL.md. - Split by domain, not by size. A sales-analysis skill with
references/finance.md,references/sales.mdandreferences/marketing.mdloads only the one the question is about. - Add a short table of contents at the top of any reference file longer than about 100 lines, so a partial read still shows the whole scope.
- Use forward slashes in paths (
references/pricing.md), even on Windows. - Name files for their content (
pricing.md, notdoc2.md). The assistant navigates your folder like a filesystem and file names are its signposts. - Keep reference content free of dates that will expire. "Current price" sections age well; "until March use the old prices" does not.
Large reference material is cheap in a skill. A full product catalog or a long style manual costs nothing until it is read — which is exactly why it belongs in references/ rather than in the main body. The quality of those reference files decides the quality of the answers, so the same discipline from preparing your company data for AI applies: one source of truth, current versions, no contradictions between files.
Step 6: Bundle a script for anything deterministic
Anything that can be checked by code should be checked by code. Scripts are more reliable than generated logic, they cost almost no context (only their output is read), and they behave the same on every run. Here is the complete validator at scripts/check_proposal.py — standard library only, so it runs on any machine with Python 3.8+:
#!/usr/bin/env python3
"""Check a proposal draft against the house rules before it goes to a client.
Usage: python3 scripts/check_proposal.py path/to/draft.md
Exit code 0 = all checks passed, 1 = problems found (listed on stdout).
"""
import re
import sys
from pathlib import Path
REQUIRED_SECTIONS = [
"Summary",
"The problem",
"What we will do",
"Timeline",
"Investment",
"Next step",
]
# Phrases our clients told us they distrust. Keep this list short and real.
BANNED_PHRASES = [
"cutting-edge",
"synergy",
"world-class",
"best-in-class",
"seamless",
"revolutionary",
]
# One page of reading for a busy owner. Longer drafts get skimmed, not read.
MAX_WORDS = 900
PRICE_PATTERN = re.compile(r"(?:€|EUR\s?)\s?(\d{1,3}(?:[.,]\d{3})+|\d+)")
PLACEHOLDER_PATTERN = re.compile(r"\[(?:TODO|CLIENT|NAME|DATE)[^\]]*\]")
def normalize(price: str) -> str:
return price.replace(".", "").replace(",", "")
def load_price_table(skill_dir: Path) -> set:
"""Return every price that appears in references/pricing.md."""
pricing = (skill_dir / "references" / "pricing.md").read_text(encoding="utf-8")
return {normalize(m) for m in PRICE_PATTERN.findall(pricing)}
def check(draft_path: Path) -> list:
if not draft_path.exists():
return [f"File not found: {draft_path}. Save the draft first, then run this check."]
problems = []
text = draft_path.read_text(encoding="utf-8")
headings = [h.strip() for h in re.findall(r"^##\s+(.+)$", text, flags=re.MULTILINE)]
for section in REQUIRED_SECTIONS:
if section not in headings:
problems.append(
f'Missing section "## {section}". Required order: {", ".join(REQUIRED_SECTIONS)}.'
)
present = [h for h in headings if h in REQUIRED_SECTIONS]
expected = [s for s in REQUIRED_SECTIONS if s in present]
if present != expected:
problems.append(f"Sections are out of order. Found: {present}. Expected: {expected}.")
lowered = text.lower()
for phrase in BANNED_PHRASES:
if phrase in lowered:
problems.append(f'Banned phrase "{phrase}". Replace it with a concrete, checkable claim.')
words = len(re.findall(r"\b\w+\b", text))
if words > MAX_WORDS:
problems.append(f"Draft has {words} words; the limit is {MAX_WORDS}. Cut the problem section first.")
# The script lives in <skill>/scripts/, so the skill root is one level up.
allowed = load_price_table(Path(__file__).resolve().parent.parent)
for raw in PRICE_PATTERN.findall(text):
if normalize(raw) not in allowed:
problems.append(
f"Price €{raw} is not in references/pricing.md. Use a listed package price or flag it for a human."
)
if PLACEHOLDER_PATTERN.search(text):
problems.append("Unfilled placeholder found (e.g. [CLIENT]). Fill it in or ask the user.")
return problems
def main() -> int:
if len(sys.argv) != 2:
print("Usage: python3 scripts/check_proposal.py path/to/draft.md")
return 1
problems = check(Path(sys.argv[1]))
if problems:
print(f"FAILED: {len(problems)} problem(s)")
for p in problems:
print(f"- {p}")
return 1
print("PASSED: structure, length, wording and prices all check out.")
return 0
if __name__ == "__main__":
sys.exit(main())
The design rules behind it are the same ones we use for MCP tool errors:
- Every error message says what to do next. "Price €7.200 is not in references/pricing.md. Use a listed package price or flag it for a human" lets the assistant fix the draft on its own. "Invalid price" would not.
- Handle errors instead of crashing. A missing file returns a clear instruction, not a stack trace.
- No magic numbers.
MAX_WORDS = 900carries a comment explaining why. If you cannot justify a value, the assistant cannot either. - Stick to the standard library or state dependencies explicitly in
SKILL.md. Skills on the Claude API run in a sandbox with no network access and no package installation; on claude.ai network access depends on settings. A script that needspip installwill fail there.
Verify the script before the assistant ever touches it. Save a deliberately bad draft as bad.md and run it:
cat > /tmp/bad.md <<'EOF'
# Proposal for [CLIENT]
## Summary
A seamless, cutting-edge solution.
## What we will do
Everything.
## The problem
Stuff.
## Investment
€7.200
EOF
python3 ~/.claude/skills/writing-proposals/scripts/check_proposal.py /tmp/bad.md
echo "exit code: $?"
Expected output: FAILED: 7 problem(s) listing two missing sections, the wrong order, both banned phrases, the unlisted price and the placeholder, then exit code: 1. Run it on a correct draft and you get PASSED and exit code 0. If both behave, the script is ready.
Step 7: Test triggering, then quality
Testing a skill has two separate questions, and most people only test the second one.
Question 1: Does it fire when it should — and only then? Start Claude Code in any project and check the skill is loaded:
claude
# inside the session:
/skills
writing-proposals should appear in the list. Claude Code watches skill directories, so edits to an existing SKILL.md take effect without a restart; if you created a brand-new top-level skills directory during the session, run /reload-skills. Then run a trigger test with fresh sessions:
SHOULD TRIGGER
1. "Draft a proposal for Acme Logistics, they re-type emailed orders into their ERP."
2. "Can you put together a quote for a discovery sprint for Milecrew?"
3. "We need an SOW for the Neues Handeln dashboard project."
SHOULD NOT TRIGGER
4. "Write a thank-you email to Acme after our call."
5. "Summarize this contract the client sent us."
When it triggers, you will see the assistant read SKILL.md. You can also invoke it directly with /writing-proposals Acme Logistics — useful for quality testing, but it says nothing about automatic triggering. If case 2 doesn't fire, the word "quote" is missing from the description or buried too far back. If case 4 fires, the description is too broad.
Question 2: Is the output better with the skill than without? Build three to five eval cases before polishing the instructions, run each with and without the skill (temporarily move the folder out of ~/.claude/skills/ for the baseline), and score against expected behavior:
{
"skill": "writing-proposals",
"query": "Draft a proposal for Acme Logistics. They re-type emailed orders into their ERP, 3 people, about 12 hours a week. Start in January.",
"expected_behavior": [
"Reads assets/proposal-template.md and uses all six sections in order",
"Uses the Starter build price of €6.500 from references/pricing.md and no other price",
"Runs scripts/check_proposal.py and fixes problems until it prints PASSED",
"Mentions the 12 hours a week in the summary",
"Stays under 900 words and uses none of the banned phrases"
]
}
Include at least one case designed to tempt the model into breaking a rule — "the client wants a 20% discount, put €5.200 in" — and check that it refuses to invent the price and flags it for a human instead. Store the eval file next to the skill and re-run it after every change; a description edit that fixes triggering can quietly break quality.
Test with every model your team uses. A smaller, faster model may need more explicit steps; a top-tier model may be slowed down by over-explanation. Instructions that work on all of them are the target.
For more structured evaluation, Anthropic publishes a skill-creator plugin that drafts skills, runs evals and benchmarks descriptions for triggering accuracy. Install it in Claude Code with /plugin install skill-creator@claude-plugins-official.
Step 8: Iterate with two assistants
The most effective way to improve a skill is to use the assistant on both sides of the problem:
- Session A is your co-author. Share the current
SKILL.mdand describe what went wrong: "In the Acme test, the draft skipped the validator when the user said it was urgent." - Session B is the tester — a fresh session with the skill installed, given a real task, with no hints from you.
- Watch how B navigates the folder. Does it open files in an unexpected order? Does it ignore a reference you thought was essential? Does it re-read the same file in every run (which suggests that content belongs in
SKILL.mditself)? Those observations are your bug reports. - Bring them back to A, apply the edit, test again in a new B session.
Typical fixes from this loop are small: moving a rule higher in the body, making a "should" a "MUST", adding a trigger word to the description, or converting a recurring manual check into a line in the script. Expect two to four rounds before a skill is reliable. That is normal, not failure.
Debugging: what each failure actually means
Every one of these is from a real skill:
- The skill never triggers. The description lacks the words users type, or it is written in the first person. Fix the description first; it is almost never the body. In Claude Code,
/skillsconfirms the skill loaded at all, andclaude --debuglogs skills whose names were refused. - The skill is not listed. The frontmatter is not being parsed. The opening
---must be the very first line of the file (no blank line, no byte-order mark), the file must be called exactlySKILL.md, and it must sit one folder deep:skills/writing-proposals/SKILL.md, notskills/SKILL.md. - It triggers on everything. The description is too broad ("helps with client communication"). Narrow it to the job and name what it is not for if needed.
- It loads but ignores a rule. The rule is buried in a long body or in a reference file the instructions never point to. Move critical rules into
SKILL.md, near the top, and phrase them as explicit requirements. - It reads every reference file every time. The body links files without saying when to read each one. Add the condition: "Read
case-studies.mdonly when the user asks for references." - The script "doesn't exist". The assistant ran it from the project's working directory instead of the skill's folder. Say explicitly that script paths are relative to the skill directory, as the example body does. In a Claude Code-only skill you can also write
${CLAUDE_SKILL_DIR}/scripts/check_proposal.py, which Claude Code substitutes with the skill's own directory before the assistant sees it. - The script fails on claude.ai or the API but works locally. It depends on a package or network access that the sandbox does not have. Rewrite it with the standard library or move the networked part into an MCP server.
- Two skills fight over the same requests. Their descriptions overlap. Draw the boundary in both descriptions ("for quotes use writing-proposals; this skill is for invoices").
Step 9: Distribute it to your team
Custom skills do not sync between surfaces. A skill in Claude Code is not automatically on claude.ai, and a skill uploaded to claude.ai is not available in the API. Pick the channel per surface:
Option A — commit it to the repository (Claude Code, one project). Move the folder into the project and push:
mkdir -p .claude/skills
mv ~/.claude/skills/writing-proposals .claude/skills/
git add .claude/skills/writing-proposals
git commit -m "Add writing-proposals skill"
git push
Everyone who pulls the repo gets the skill, and changes go through normal code review. This is the right default for engineering skills tied to one codebase.
Option B — upload to claude.ai (non-technical colleagues). Zip the folder so the skill folder is the root of the archive, not its contents:
cd ~/.claude/skills
zip -r writing-proposals.zip writing-proposals
unzip -l writing-proposals.zip # every path must start with writing-proposals/
Then upload it in claude.ai and enable it under Customize → Skills. On Team and Enterprise plans, administrators can provision skills for the whole organization instead of asking each person to upload them.
Option C — a plugin marketplace (Claude Code, the whole team, versioned). Wrap one or more skills into a plugin and publish it from a Git repository your team can reach. The layout:
acme-claude-plugins/
├── .claude-plugin/
│ └── marketplace.json
└── plugins/
└── sales-kit/
├── .claude-plugin/
│ └── plugin.json
└── skills/
└── writing-proposals/
├── SKILL.md
├── references/
├── assets/
└── scripts/
plugins/sales-kit/.claude-plugin/plugin.json:
{
"name": "sales-kit",
"description": "Proposal, quote and follow-up skills for the sales team",
"version": "1.0.0"
}
.claude-plugin/marketplace.json at the repository root:
{
"name": "acme-claude-plugins",
"description": "Internal Claude Code plugins for Acme",
"owner": { "name": "Acme Operations" },
"plugins": [
{
"name": "sales-kit",
"source": "./plugins/sales-kit",
"description": "Proposal, quote and follow-up skills for the sales team"
}
]
}
Validate, then install it yourself before anyone else does:
claude plugin validate ./acme-claude-plugins
claude plugin marketplace add ./acme-claude-plugins
claude plugin install sales-kit@acme-claude-plugins
claude plugin list
Once it is pushed (for example to acme/acme-claude-plugins on GitHub), teammates run claude plugin marketplace add acme/acme-claude-plugins and the same install command. Note that plugin skills are namespaced: the skill is invoked as /sales-kit:writing-proposals. Keep the plugin name in plugin.json identical to its entry name in marketplace.json — a mismatch is the most common cause of "plugin not found" errors. To make the marketplace and plugin appear automatically for everyone working in a repo, add them to the project's .claude/settings.json:
{
"extraKnownMarketplaces": {
"acme-claude-plugins": {
"source": { "source": "github", "repo": "acme/acme-claude-plugins" }
}
},
"enabledPlugins": {
"sales-kit@acme-claude-plugins": true
}
}
Option D — the Claude API (your own product or agent). Custom skills can be uploaded through the Skills API (/v1/skills) and attached to requests via the code execution tool's container; uploaded skills are shared across the API workspace. Remember the sandbox has no network access, so the script rules from Step 6 matter even more.
Governance for a team library. Once more than a handful of people write skills, agree on four things: one naming pattern, one owner per skill, a changelog line per change (bump version in plugin.json), and an eval file that must pass before a change merges. Rolling skills out is as much a change-management task as a technical one — the habits that make it stick are the same ones in how to introduce AI tools to your team.
Security: treat a skill like installed software
A skill can instruct the assistant to run code and use tools, which means a malicious or careless skill can do damage. Before installing or shipping one:
SKILL SECURITY REVIEW
[ ] Only skills you wrote or from a trusted source; third-party skills
audited file by file (SKILL.md, every script, every reference).
[ ] Scripts do only what the description promises: no unexpected
network calls, no reads outside the working directory.
[ ] No secrets, API keys or customer data inside the skill folder.
[ ] No instructions to fetch and follow content from external URLs
(fetched text can carry prompt injection, and URLs change owners).
[ ] Skills with side effects (deploy, send, publish, delete) use
disable-model-invocation: true so only a human can start them.
[ ] allowed-tools is as narrow as the task: Bash(python3 *), not Bash.
[ ] Reference files contain only material everyone who has the skill
may see; sensitive data stays behind an MCP server with per-user auth.
[ ] An owner is named and the eval file passes on the current version.
The point about sensitive data deserves emphasis: everything in a skill folder is visible to everyone who has the skill. Price lists and templates belong in a skill; salary data and customer records belong behind a properly secured MCP server that checks who is asking.
FAQ
What is an agent skill? An agent skill is a folder containing a SKILL.md file with a name and description in YAML frontmatter, plus Markdown instructions and optional reference files and scripts. The assistant sees only the name and description until a request matches, then loads the instructions and any files it needs. It packages repeatable know-how so you stop pasting the same instructions into every chat.
What is the difference between a skill and an MCP server? A skill provides know-how: procedures, rules, templates and local scripts. An MCP server provides access: a live, authenticated connection to a system such as a CRM, shop or database. Use a skill when the assistant keeps forgetting how you do something, an MCP server when it cannot reach the data, and both when it needs data plus your way of using it.
How long should a SKILL.md file be? Keep the body under 500 lines, and most good skills are far shorter, often 50 to 150 lines. Put long material such as price lists, schemas, style manuals and examples into separate reference files linked directly from SKILL.md, because those cost nothing until they are read.
Why is my skill not triggering? Almost always the description. It must say what the skill does and when to use it, in the third person, using the words people actually type, with the key use case in the first 200 characters. Also check that the file is named SKILL.md, the frontmatter starts on the first line and the folder sits directly inside the skills directory.
Do skills work in ChatGPT, Cursor or other assistants? SKILL.md has been published as an open standard, and a growing number of agents and coding tools read it. Claude supports skills in Claude Code, claude.ai and the API. Optional fields like allowed-tools are product-specific, so keep the core of the skill in plain name, description and Markdown for maximum portability.
Can a skill include code? Yes. Put scripts in a scripts folder and tell the assistant to run them. Only the script output enters the context, so scripts are an efficient and reliable way to handle validation, calculations and file conversions. On the Claude API and some claude.ai configurations there is no network access or package installation, so prefer the standard library.
How do I share a skill with my team? For one codebase, commit it to .claude/skills in the repository. For non-technical colleagues on claude.ai, upload it as a zip or have an administrator provision it for the organization. For a versioned library across many projects, publish it as a Claude Code plugin from a Git-based marketplace. Skills do not sync between these surfaces, so plan one channel per surface.
Are third-party skills safe to install? Only if you trust the source and have read every file. A skill can tell the assistant to run code and use tools, so treat it like installing software: audit the scripts, look for unexpected network calls or file access, and never install a skill that fetches instructions from external URLs.
Where to go from here
A good skill library grows the same way a good MCP server does: one well-tested skill at a time, driven by the tasks your team repeats most. After proposals, the same pattern extends to recurring reports, reviews against your checklists and release procedures — each one a description that triggers precisely, a short body, references loaded on demand, a validator and an eval file. Pair them with MCP servers where the work needs live data, and with smart workflows where it needs to run on a schedule without anyone asking.
Copy & paste
Do it: the full prompt
Copy this prompt into any LLM or coding agent (Claude, ChatGPT, Cursor …) to apply this guide to your own project.
Guide: https://blackcard.dev/guides/how-to-create-a-skill Markdown version (fetch this for the full method): https://blackcard.dev/guides/how-to-create-a-skill.md Act as my implementation partner and build a production-ready agent skill following the method from the guide "How to Create a Skill" (blackcard.dev). My situation: - Task to package: [e.g. writing client proposals / weekly client status report / PR review against our checklist] - What the assistant gets wrong today without help: [list 3-5 concrete failures] - Material I have: [e.g. price list, template, 2 past examples, banned phrases] - Where it runs: [Claude Code / claude.ai / Claude API] - Who needs it: [just me / one repository / the whole team] Steps: 1. Propose a name (lowercase, hyphens, max 64 characters, no "claude" or "anthropic", folder name identical) and a third-person description that says what it does AND when to use it, with trigger words in the first 200 characters. 2. Create the folder: SKILL.md, references/, assets/, scripts/. Give me the exact mkdir commands for my target location. 3. Write SKILL.md: frontmatter, a facts-to-collect section, a numbered workflow with a copyable checklist, hard rules near the top, one concrete input/output example, and explicit "read X when Y" pointers to every reference file (one level deep only). Keep it under 150 lines. 4. Write the reference and asset files from my material. 5. Write a standard-library-only validation script for every deterministic rule (structure, length, numbers, forbidden words, placeholders), with error messages that tell the assistant how to fix each problem, and a workflow step that loops until it passes. Give me a bad and a good test input and the commands to verify the script. 6. Write a trigger test (3 prompts that should fire, 2 that should not) and an eval file with 3-5 cases including one that tempts the model to break a rule. 7. Run the security review: no secrets or sensitive data in the folder, narrow allowed-tools, disable-model-invocation for anything with side effects. 8. Give me the distribution steps for my target: repo commit, claude.ai zip (folder as zip root), or a plugin plus marketplace.json and the .claude/settings.json snippet for auto-enabling. Deliver every file in full, then wait for my trigger-test and eval results before refining. If my task is too broad for one skill, push back and split it.
Building one skill is an afternoon. Building a skill library your whole team trusts — with descriptions that trigger precisely, validators for the rules that matter, MCP servers for the data behind them, evals that catch regressions and a rollout people actually adopt — is the work we do at BlackCard. We have built and debugged enough of them to skip the misfires, and we leave you with the files, the eval suite and the documentation, so the library stays yours. If you want that done right the first time, book a free call and bring the task your team explains to its AI assistant most often. You can read more about how we work on our Practical AI Tools and Consulting pages.





