Notes on makingskills that work.
What breaks, what it costs, and how to tell the difference. Written from the failures, because those are the part nobody publishes.
SEOThe trailing slash that kept our pages out of GoogleOur canonicals said /skills/x, the server answered at /skills/x/, and Google indexed neither. How to spot the mismatch and the one function that fixes it.SEOrobots.txt for AI crawlers: invite them by name, and mind the wildcard trapGPTBot, ClaudeBot, PerplexityBot and Google-Extended each read their own group. How to allow them, and the rule that silently opens pages the wildcard closed.SEOWhat llms.txt is, what it is not, and how to write onellms.txt is a markdown summary of your site for language models to read in one go. What belongs in it, what to leave out, and why ours has no prices in it.SEOIndexNow: tell Bing a page changed instead of waiting for a crawlIndexNow pushes changed URLs to Bing and other engines in one request. How the key file works, what Google does instead, and a script to run after deploy.AnalyticsHow to see which visitors came from ChatGPT, Claude or PerplexityAssistant traffic often arrives with no referrer at all. How to detect the visits you can identify, and how to report the rest honestly instead of guessing.AnalyticsMixpanel HTTP API: the CORS error that looks like an outagePosting JSON to Mixpanel's /track endpoint from a browser fails with a CORS error beside a healthy 200. The fix is one content type, plus two properties.SellingSelling digital downloads from a static site, with no backend of your ownA static site, a merchant of record and a payment link make a complete shop for a digital product. What each part does, and three places it still goes wrong.SellingLicence-key gated downloads: one route, no database, no secretPaste a licence key, get the file. How we built on-site downloads with one edge function, a public key check and files no URL reaches without a key.ShippingHow to install a Claude Code skill, for you or for your whole teamA skill is a folder. Where to put it so it works in every project, where to put it so the whole team gets it, and how to check Claude has actually picked it up.TriggersHow to write a Claude skill description that gets it usedThe description is the only part of a skill Claude reads before choosing to use it. A structure that works, the length limit, and a before and after to copy.SEOGoogle Search Console for a brand-new site: what to do on day oneVerify by DNS, submit one sitemap, inspect a few pages, then wait. What each report means in the first week, and the one early error worth fixing at once.SEOA sitemap for a static site: generated, honest and shortGenerate the sitemap from the same data as the pages, list only URLs that return 200 and should be indexed, and leave out every page that says noindex.AnalyticsAn event plan for a landing page: seven events, not seventyMost landing pages need seven events. Which ones, what each carries, and the delegated click listener that tracks them without touching every component.AnalyticsKeep licence keys and emails out of your analyticsPayment providers put the buyer's email and licence key in the return URL, and analytics records full URLs by default. Where it leaks, and the fix.SellingTest-mode checkout pitfalls: how a shop takes no money without an errorA test-mode checkout takes only test cards, so a live page linked to it fails real buyers silently. How it happens, and a build guard that makes it impossible.ShippingSharing Claude Code skills with a team through the repositoryCommit skills to .claude/skills/ and everyone who clones the repo gets them. How to lay that out, review skill changes and stop two skills fighting.TriggersBuild a trigger test set for a Claude skill in twenty minutesTwenty prompts, half that should use the skill and half that should not, tell you whether a description works. How to write them so the test means something.TriggersWhen a Claude skill fires too often, and how to narrow itA skill that jumps in on every loosely related request has a description that is too broad. How to spot it and narrow it without losing real matches.ContextThe references folder: keep a skill small until it needs to be bigSKILL.md is read whenever a skill is active; files in references/ only when needed. How to split a skill that way so most turns cost little context.ShippingClaude Code skill folder structure: what goes whereA skill is a folder: SKILL.md at the top, references for long material, optional scripts, a README for people. The layout, the frontmatter and naming rules.TriggersWhen two Claude skills want the same promptTwo skills with overlapping descriptions make it hard to predict which one runs. How to find the overlap and give each a job the other does not claim.TriggersNaming a Claude skill: what the name does and what it does notA skill's name identifies it and lets you ask for it directly; the description decides when it is picked. How to choose a name that helps and never hurts.TriggersMatch the words people actually type, not the words you would writePeople ask for outcomes in loose, lowercase, half-finished sentences. How to collect the phrasings your users really use and fold them into a skill description.TriggersAdding 'when not to use' to a skill description, sparinglyA short line saying when a skill does not apply can stop a stubborn near-miss. Used everywhere it bloats the description and blurs the job. When one line helps.TriggersDo Claude skills trigger when you prompt in another language?If your team writes prompts in Hindi, Spanish or a mix, test whether an English description still matches them. What to check, and what to add when it does not.TriggersHow to measure a skill's trigger accuracy, before and afterTrigger accuracy is two numbers from one prompt set: how often it fires when it should, and how rarely when it should not. How to measure and report both.ContextHow long should SKILL.md be?SKILL.md is loaded whenever the skill is in use, so every line costs context. A practical length, what to keep in it, and what to move to references.ContextWhen to split a large skill into two, and when not toA skill that does two jobs triggers vaguely and loads rules for both on every use. How to tell when a skill has become two, and how to split it without overlap.ContextScripts or instructions: what a skill should do in codeSome steps work better as a script Claude runs than as prose it interprets. Which ones, how to call them from SKILL.md, and what scripts cost elsewhere.ContextWhat happens when you install too many Claude skillsEvery installed skill's name and description is visible to Claude up front. With dozens installed, overlaps multiply. How to keep your set of skills lean.TestingA Docker harness for testing Claude skills from scratchA throwaway container with a fresh Claude Code install is the cheapest clean machine there is. A minimal Dockerfile, what to mount, and what to look for.TestingTesting Claude skills in CI on every changeStructural checks are free and belong on every commit; trigger runs cost tokens and suit a nightly job. How to split skill testing across CI sensibly.TestingClaude updated and my skill changed: regression testing skillsA skill that worked last month can behave differently after Claude or the model updates. How to notice early, confirm the cause, and fix the rules.TestingGolden outputs for a skill whose output is never identical twiceModel output varies run to run, so exact-match snapshots fail. Check what must hold instead: structure, required elements, banned patterns, token use.TestingTesting the scripts inside a skillA skill's scripts run on the buyer's machine with whatever is installed there. Unit-test them, keep dependencies minimal, and fail loudly when one is missing.TestingMaking a Claude skill work on Windows, macOS and LinuxInstructions travel well; scripts and paths do not. The usual cross-platform breakages in skills, and how to write steps that work whichever OS the buyer is on.TestingWriting prompts that should not fire your skillThe half of a trigger test people skip: near-miss prompts that must leave the skill alone. How to write them so they actually catch over-triggering.TestingA rubric for judging what a skill producedSome qualities cannot be checked by a script: does the screen look designed, is the copy specific. A five-line rubric makes that judgement repeatable.TestingWhy the same skill gives different results, and what to doRun the same prompt twice and a skill may fire once and not the next time, or follow a rule differently. Where the variation comes from and how to reduce it.TestingA preflight script: fail once, with every missing thing listedA skill that fails on one missing tool, then the next, then the next, wastes an afternoon. A preflight check lists every missing requirement at once.ContextWhen CLAUDE.md gets too long, and what to move out of itCLAUDE.md is read at the start of every session, so everything in it costs context every time. What belongs there, and where the rest should live instead.ContextLoading documentation on demand instead of up frontPasting whole docs into context works once and costs every turn after. How to let Claude open the right document only when a task needs it.ContextWhat MCP tools cost you in context before you call themEach connected MCP server adds its tool names, descriptions and schemas to context. How that adds up, and how to keep only the servers a project needs.ContextExamples in a skill: fewer, shorter and realOne tight, real example teaches Claude more than five long invented ones. How many examples a skill needs, how long each should be, and where they belong.Contextreferences/ or assets/: where a skill's extra files belongSome files in a skill are for Claude to read; others are for Claude to copy into the user's project. Keeping the two apart makes a skill clearer and cheaper.ShippingVersioning a Claude skill so people know what changedA skill changes behaviour for everyone who uses it, so changes need a version and a note. A simple scheme, where to record it, and when a change is breaking.ShippingPackaging a Claude skill as a ZIP that installs cleanlyA skill ZIP should unzip to exactly one folder with SKILL.md at its top. How to build one that way, keep junk files out, and validate it before it ships.ShippingPlugin marketplace or plain skill folder: how to distribute a skillA skill can ship as a folder people copy or as a plugin installed from a marketplace. What each gives you, and which suits a free tool or a paid product.ShippingChoosing a licence for a Claude skill you publish or sellA skill is plain text anyone can copy, so the licence is about permission, not protection. How we think about open and commercial terms for skills.ShippingWhat people actually pay for when they buy a Claude skillThe files are copyable, so people are not paying for text. They pay for a skill that works first time, keeps working as Claude changes, and has support.ShippingKeeping skills working as Claude changesSkills sit on a system that keeps changing. A small routine: when to recheck, what to rerun, and how to tell users what changed and why.ShippingClaude skills for agencies: one standard across many client projectsAgencies juggle many codebases with different styles. How skills let a team carry its own standards into every project while respecting each client's system.ShippingOnboarding a new developer with skills instead of a wikiA new starter learns a codebase's conventions by getting them wrong. Skills in the repo mean their first pull requests already follow them.ShippingSkills vs subagents in Claude Code: which one you needA skill adds knowledge to the current conversation; a subagent runs a task in its own separate context. How to tell which a job needs, with examples.ShippingSkills vs slash commands: automatic or on requestA slash command runs when you type it; a skill is picked when a request matches. How to decide which fits a workflow, and when to have both.ShippingSkills vs hooks: guidance or guaranteesA skill guides what Claude does; a hook runs a command at a fixed point every time. When a rule needs a guarantee rather than a good chance of being followed.ShippingCrediting open source inside a skill you shipIf a skill ships someone else's code, their licence and credit go with it, visibly. How to do that properly, and when recommending a tool beats bundling it.AnalyticsGA4 event names: the rules that silently drop your eventsGA4 ignores events whose names break its rules, often without an error. The limits, a naming style that stays consistent, and a normaliser to enforce it.AnalyticsFirst-touch attribution with UTM parameters on a static siteUTM tags exist only on the first page someone lands on. Store the first touch once, and a sale three pages later can still be credited to the right channel.AnalyticsHonouring Global Privacy Control in your analyticsBrowsers can send a Global Privacy Control signal meaning do not track or sell my data. How to detect it, and why honouring it everywhere is the simple choice.DesignWhy AI-generated interfaces all look the same, and how to make yours notAsk any model for a landing page and you get the same purple gradient, three cards and rounded everything. Where that look comes from, and what stops it.DesignGive Claude Code your design system as a skill, not a paragraph in a promptA design system Claude can follow is four files: rules, tokens, component recipes and what is off limits. What goes in each, and the description that loads it.DesignUsing ui-ux-pro-max with your own design skill: who decides whatui-ux-pro-max is strong on usability and broad on style. Run it beside a design skill and you get both, if you decide in advance which one owns the look.TriggersWhy your Claude Code skill does not fire, and how to tellA skill that works when you name it and ignores you otherwise has a description problem, not a logic problem. How to find out which, in about ten minutes.ContextWhat a skill costs you in context, every single turnAn active skill is re-read on every turn. Here is how to find what yours is costing, and how to split it so the reference material loads only when it is needed.TestingTest a Claude skill on a clean machine before you trust itA skill works on the machine it was written on, which tells you almost nothing. A container, a fresh install and twenty minutes shows what a new user will hit.ShippingSkills, CLAUDE.md and MCP: what belongs in whichThree ways to give Claude Code context, and putting a thing in the wrong one is why it gets ignored. A short guide to which is which and when to reach for each.
Reading about itis the slow way.
The skills in the catalogue already do what these posts describe. Pay once, and download straight away with your licence key.