Skip to main content

2.2 Build Your First Skill

In 2.1 Extending Agents with Skills, you learned what skills are and how they fit into the agent extension ecosystem. Now you'll build one.

The skill you'll create — refining-ideas — is the step you run before starting SDD. When the work shifts from fixing defined issues (this module) to designing new features from rough ideas (Module 3), you need a way to turn a vague notion into a well-formed input for /sdd. Build it now, carry it into that work.

When to Create a Skill​

The decision has a simple heuristic: the third paste rule — when you've pasted the same checklist, procedure, or set of instructions into chat three times, that content should be a skill.

Reinforcing signals:

  • You're repeating the same multi-step workflow across different conversations
  • A CLAUDE.md section has grown into a procedure rather than a fact (the 2.1 routing map applies)
  • The task is consistent enough to have a success criterion — which means you can write an eval for it
  • The task needs deterministic execution, or you keep reminding the agent how to correctly invoke a specific script or command

One important principle: run the task once without a skill first. If you observe a real gap — inconsistency, omitted steps, wrong triggering — that's the signal to build. Don't build in anticipation of a problem you haven't seen.

Two Failure Modes to Know​

Practitioners run into two reliability issues with skills:

Undertriggering — the skill is installed but doesn't fire when it should. Vercel's skill evaluations found skills went un-invoked in more than half of relevant cases when descriptions were too broad or generic. The remedy: write descriptions that are specific, trigger-rich, and "pushy" — describe exactly what situation calls for the skill.

Skill bloat — too many competing skills add noise and create ambiguity about which one applies. Keep your enabled skill set focused; approximately 20–50 active skills is a practical ceiling for most workflows.

The Skills Ecosystem​

Skills are distributed through marketplaces. The primary one you've been using is skills.sh, built by Vercel and accessed via the npx skills CLI from 1.4.

Useful commands beyond npx skills add:

npx skills list              # List installed skills
npx skills find              # Discover skills on the marketplace

Install skill-creator​

skill-creator is Anthropic's meta-skill for building, evaluating, and improving skills. It runs a Create → Eval → Improve → Benchmark loop, letting you iterate on a skill until it reliably triggers and executes correctly.

Install it via the Claude Code plugin system:

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

If the plugin system prompts for a reload:

/reload-plugins
note

Plugin commands and registry paths evolve as the ecosystem matures. If these commands don't work, run /plugin marketplace list to browse available plugins or check the Anthropic documentation for the current install path.

Exercise: Build refining-ideas​

refining-ideas is a skill that interrogates a rough idea into a well-formed task — the pre-SDD-1 step you'll lean on in Module 3 when you're designing original features rather than fixing defined issues.

The target behavior — a multi-agent refinement pipeline:

  1. Research — on receiving the rough idea, extract key technologies and domain terms, then dispatch parallel research sub-agents: Sonnet agents paired with Context7 for up-to-date library and API docs, and Sonnet web-research agents for current patterns and best practices. Synthesize findings before engaging the user.
  2. Q&A — ask clarifying questions one at a time (prefer multiple-choice), informed by what the research surfaced
  3. Propose approaches — present 2–3 concrete options with a recommendation grounded in research findings
  4. Adversarial critique — draft the design summary, then dispatch it to an Opus sub-agent primed to adversarially critique the plan; if real issues surface, return targeted follow-up questions and loop back before proceeding
  5. Approval gate — present the refined summary; on approval the output is ready for /sdd

Step 1: Create the skill with skill-creator​

Don't hand-author the SKILL.md from scratch — that's exactly what skill-creator is for. In a Claude Code session:

/skill-creator create refining-ideas

Feed it the target behavior above and let its Create → Eval → Improve loop scaffold the directory, draft a trigger-rich description, and write the SKILL.md body that spells out the five phases. Then review its output — two things matter most for reliability:

  • The description — it's the primary trigger. Make sure it's specific about when to activate (before /sdd, starting from a vague concept), not a vague "helps refine ideas" that will undertrigger.
  • The body — confirm it describes the full pipeline (research → Q&A → propose → critique → approval), not just "ask clarifying questions."

The "Authoring Best Practices" section below covers what "good" looks like for both — use it as your review checklist. If your org has a house format for design summaries, add it as a references/ file so it loads on demand.

Step 2: Validate​

Validate the SKILL.md against the open standard spec using the agentskills.io reference validator:

skills-ref validate ./refining-ideas/SKILL.md
tip

skills-ref is the official validator from the agentskills.io spec toolchain (separate from the Vercel skills CLI). Install it with npm install -g skills-ref if it isn't available.

Then test on a real scenario — take a rough Pet Clinic improvement idea and see if the skill interrogates it into a useful design summary:

I want to add something to let clinic staff track which pets need follow-up calls.

Evaluate: did it ask the right clarifying questions? Did it propose concrete approaches? Would the output be a useful input to /sdd?

Step 3: Audit before using​

Before you use any skill — including one you just built — audit it. See Security: Skills Are an Attack Vector below.

You'll Need This in Module 3

In Module 3 you move from fixing defined issues to designing original features. The refining-ideas skill is the bridge from "I have a rough idea" to "I have a well-formed spec input." Having it ready means every new feature starts with a structured refinement pass before SDD begins.

Authoring Best Practices​

Conciseness is correctness​

The context window is a public good. Every instruction you add is one the model has to track alongside your actual task. Fewer, well-chosen instructions outperform a long list of detailed rules — this is the same logic behind progressive disclosure in 2.1.

OpenAI's empirical finding from their skill evals: "the smallest prompt that passes your evals is usually the best prompt." For lists of rules, 4–6 items tend to perform better than 10–15.

One skill, one job​

A skill should do one thing clearly. When a skill grows past ~500 lines, it's usually trying to do multiple jobs. Split it: move shared knowledge into references/ files and link to them, or split the skill entirely. The progressive disclosure structure exists to make this clean.

Name with gerunds​

Name skills with gerund phrases that describe what they do: refining-ideas, deploy-staging, post-mortem-writing. This makes them self-explanatory in /skills lists and helps the model recognize when they apply.

Write trigger-rich descriptions​

The description field is the trigger. Vague descriptions cause undertriggering; overlapping descriptions cause confusion. Write to answer: "in exactly what situation should this skill activate?" Verbose descriptions cause a subtler version of the same problem — models tend toward wordy, repetitive phrasing, and a bloated description buries the actual trigger condition. After drafting, review it for a snappier phrasing that keeps the same meaning.

Explain why, not just what​

Instead of ALL-CAPS mandates ("ALWAYS do X"), explain the reasoning: "Ask one question at a time because users answer better when they're not overwhelmed by a list." The model follows intent when it understands the rationale — and it applies judgment in edge cases you didn't anticipate.

Build evals first​

The Create → Eval loop in skill-creator is deliberate. Write your test cases before finalizing the skill: what does "working correctly" look like? What inputs should trigger it? What outputs are acceptable? The eval keeps iteration honest.

A useful authoring pattern: Claude A writes, Claude B uses. Have one session author the skill, then test it in a fresh session with no knowledge of how the skill was written. If Claude B triggers and executes it correctly without hints, the skill works.

Treat skills as software artifacts​

A skill is executable software that runs at operator privilege (see Security below) — so treat it like any other artifact you ship, not a throwaway text file. This matters most for organizational skills shared across a team, where one skill's behavior changing silently affects everyone.

  • Version it — keep skills in source control with explicit versions and a changelog. A shared skill whose behavior shifts under users without notice is a real hazard, not a convenience.
  • Give it a CI/CD pipeline — run the eval suite and benchmarks automatically on every change, and gate merges on the evals passing. A change should have to prove it doesn't regress the skill before it ships. This is the skill-creator Create → Eval → Improve → Benchmark loop promoted from manual to automated.
  • Plan rollout and rollback — decide how a new version reaches the org (staged rollout, a canary group), how you roll back a bad one, and how you know an update is actually an improvement. Benchmark the new version against the old with variance analysis — ship on evidence, not on vibes.

Use scripts for determinism​

Anything that needs to be explicitly repeatable, or that requires a specific input/output format, belongs in scripts/ — not prose instructions the model re-executes from memory each time (see Scripts: The Deterministic, Context-Saving Layer in 2.1). A script produces the same output every time; a paragraph of instructions is a probabilistic re-derivation.

Iterate like a prompt​

A skill is a prompt with structure, not a fire-and-forget artifact. One that triggers and executes correctly for the phrasing you tested can still misfire on a slightly different wording or invocation of the same task. Expect several rounds of real usage — trigger it, watch where it breaks, tighten the description or body — before trusting it in the wild. Early in a skill's life, usage and refinement cycles matter as much as the initial draft.

Test across models​

Skill behavior can vary between model versions. If your skill will be used by a team or published to a marketplace, test it on multiple models before publishing.

Security: Skills Are an Attack Vector​

Skills load at operator privilege and can execute code. That combination makes them a meaningful security surface — more comparable to installing a browser extension than adding a plugin.

A skill's risk doesn't live in one place. It's tempting to say "the danger is a malicious script hidden in scripts/" — but that's one concealment spot, not the shape of the risk. The instructions in SKILL.md are injected straight into the model's context, so a prompt-injection payload can live in the prose itself, no script required. And bundled scripts don't run on their own; they execute only when the skill's instructions convince the agent to invoke them. To reason about skill risk cleanly, sort it into three categories.

Three Kinds of Skill Risk​

Overreaching — the skill has, or openly declares, more capability than it should. This covers the honestly malicious ("this skill exports your secrets to a third party") and the merely over-permissioned (a formatter that requests full desktop control). The danger is disclosed or plainly evident — you catch it by reading what the skill declares and asking whether that scope is justified.

Exploitable — the harm enters through an external channel the skill opens, so the payload lives outside the files you reviewed. This is dangerous regardless of the author's intent: an attacker can hijack a well-meaning skill, or a malicious author can plant the hook on purpose — pointing you at an installer or a remote script on a server they control, where the real payload sits and can change after you audit. Common vectors are indirect prompt injection (untrusted content the skill ingests — a web page, issue, or API response — carries hidden instructions the agent obeys), remote code fetch from a controlled URL, dependency injection via a compromised package, and tool-output poisoning from a connected MCP server. Because the danger is external, auditing the skill's own files isn't enough — you have to weigh what it reaches out to: be wary of skills that fetch remote code or depend on packages and sources you can't vouch for, and grant the rest least privilege.

Deceptive — the skill does things it never told you about. The description says "formats git commits"; the bundled script quietly exfiltrates environment variables. The danger is concealed, so declared behavior can't be trusted — you catch it only by inventorying every file and watching what the skill actually does.

The line between Overreaching and Deceptive is disclosure: both can be author-driven and malicious, but overreaching harm is out in the open while deceptive harm is hidden. Bundled scripts, obfuscated strings, and undisclosed network calls are how Deceptive skills stay hidden — which is exactly why the audit below inventories every file, not just the Markdown.

Security Landscape (2025–2026)

Security researchers have documented a growing threat surface around agent skills and plugins:

  • Snyk (2026) audited nearly 4,000 marketplace skills (ToxicSkills / ClawHavoc research) and found 36% contained prompt injection payloads; 13% had at least one critical security issue. Confirmed attack types included credential stealers (reading local secrets, encoding, and exfiltrating to attacker endpoints), reverse shells, and environment-variable exfiltration. Memory and context poisoning — payloads that persist in agent memory across sessions — is a documented threat category in this space.
  • OWASP Agentic Skills Top 10 (an OWASP candidate project) addresses risks including supply-chain compromise via marketplace skills, unexpected code execution, agent goal hijack via skill content, and memory and context poisoning.

Specific figures in this space change as research evolves. The structural takeaway is stable: skills run code and load instructions at elevated privilege, making them a higher-risk install than a configuration file.

Pre-Install Audit Checklist​

Treat installing a skill like installing software. Before adding any skill to your environment:

  • Read the entire SKILL.md — not just the description; read the full body
  • Inventory every bundled file — list every file in scripts/, references/, and assets/; a Python script in a "git formatter" skill is a red flag
  • Check for obfuscation — look for base64-encoded strings, unusual Unicode, eval() calls, or anything that obscures what code does
  • Search for outbound network calls — curl, requests.get, fetch, unexpected URLs in any script file
  • Scrutinize allowed-tools — does the listed toolset match what the skill claims to do? A documentation skill requesting Bash access warrants scrutiny
  • Prefer trusted sources — skills from verified authors or your own organization carry less risk than anonymous marketplace entries

Run this checklist on the refining-ideas skill you just built. Auditing your own skill builds the habit and often surfaces clarity improvements.

Knowledge Check​

Question 1 of 5

Build Your First Skill Knowledge Check

Q1. You've explained the same five-step API integration process to Claude in three separate conversations. What does the third paste rule say you should do?