The problem: your docs have a reader problem
When a developer asks their assistant to “add cost tracking per user”, the assistant writes the integration from what it remembers. For a young SDK that means invented method names, deprecated options, and prices from a previous era, delivered fluently. The developer does not know it is wrong, they just know your product “didn’t work”. The fix is not better docs for humans, it is docs the assistant loads at the moment of the task, which is precisely what a skill is.
What we shipped
One plugin in the same public repo as the SDKs, four skills: weckr-integration (the two line pattern, errors, provider quirks), weckr-model-pricing (current per token prices), weckr-cost-estimator (forecast a feature before shipping), and weckr-margin-audit (which plans go underwater). Each is a folder:
skills/weckr-integration/
SKILL.md # frontmatter: name + when it applies
# body: the method, the patterns, what NOT to do
reference.md # full API surface, loaded only when needed
.claude-plugin/
marketplace.json # makes the repo an installable marketplace
plugin.json # plugin metadataTwo decisions did the heavy lifting. Every code sample was copied from the shipped SDK, never retyped, so the skill cannot teach syntax that does not exist. And each skill has an explicit what not to do section, because the assistant failure mode is confident overreach: computing cost client side, logging prompt content, passing undeclared plans.
The test: prove the knowledge came from the skill
Installed skills are only worth something if they trigger on natural questions. So: fresh session, empty directory, no mention of any skill, four plain questions. The discriminator was pricing, current model prices postdate every training cutoff, so a correct exact answer can only come from the skill:
> what does gpt-5.4-mini cost per million tokens?
"gpt-5.4-mini: $0.75/1M input and $4.50/1M output (cached input
$0.075). Snapshot verified 2026-07-22, confirm at OpenAI's
pricing page before billing on it."Exact table values, plus the verification caveat we wrote. The integration question produced the real two line pattern with flush() advice, and the margin question produced the full audit shown in the Claude margin audit transcript. Four for four, all traceable to skill content.
The design decision that matters: plan for drift
A skill is frozen text describing a moving world, and the honest question is what happens in month three. Our answer has three layers. Volatile facts point at a live source first: the pricing skills fetch the live LLM pricing feed and treat their embedded tables as dated fallback. Every frozen number carries its verification date. And a weekly watcher diffs all price tables against published rates, opening a reviewed pull request when providers move, which caught OpenAI’s 80 percent Luna cut on its first live run. Ship a skill without a staleness plan and you have shipped a liability with your logo on it.
Should your product do this?
Three questions decide it:
- Do developers integrate you, and would an assistant plausibly get it wrong? Then yes.
- Do you have facts that move faster than training cutoffs, prices, models, limits? Then especially yes, with a live feed behind them.
- Is the useful thing your user’s own live data rather than know-how? Then you want the other artifact, see MCP server vs Claude Skill, or both.
The ecosystem context, marketplaces, auditing, what else to install, is in Claude Code plugins for SaaS builders.
FAQ
Why should an SDK ship a Claude Skill?
Because assistants now write most integration code, and without your input they guess. A skill puts your real syntax, your real concepts, and your current numbers into the assistant at exactly the moment a developer asks for your product. It is the difference between Claude inventing a plausible API for your SDK and Claude writing the two lines that actually ship.
What does a Claude Skill consist of?
A folder with a SKILL.md: YAML frontmatter holding a name and a description of when the skill applies, then a markdown body with the instructions. Optionally a reference.md with the full API surface, loaded only when needed. Distribution is a small plugin manifest in the same repo, which makes it installable with two commands. No servers, no build step.
How do you know the skill actually works and gets used?
Test it the way a stranger hits it: install the plugin, open a fresh session in an empty directory, and ask natural questions without naming the skill. Our discriminator was pricing, since current model prices postdate every training cutoff, so when Claude answered $0.75 and $4.50 per million for gpt-5.4-mini, the exact table values, the knowledge provably came from the skill.
How do you keep a skill from going stale?
Design for drift on day one. Facts that move, prices in our case, point at a live feed the skill fetches first, with the embedded table as a dated fallback. Then automate the diff: our weekly watcher compares every price table against published provider rates and opens a reviewed pull request when something changes. A skill that hardcodes volatile facts is wrong within a month.
How long does building a good skill take?
Ours was roughly a day for four skills, and most of it was editorial, deciding what the assistant should refuse to do, which caveats are mandatory, and pulling every code sample from the shipped SDK instead of writing them fresh. The mechanical parts, frontmatter, manifest, marketplace, are an hour. Budget the day for correctness, not for plumbing.
Keep reading
Try the result, then steal the pattern
The four skills are free, open source, and readable in one sitting on the Claude Skills page, install commands included. The product they teach is on the live demo, and the wider cost playbook is the AI cost and margin guide. And genuinely: if you ship an SDK, copy this pattern, the water is warm.