Start from the task, not the skill
The easiest way to overcomplicate a custom skill is to start from the word 'skill' instead of the work you already do.
Most people start by writing a skill.
That is the wrong starting point.
The better move is to run the task with the agent first. Actually do the work. Then extract the pattern from what worked. Most of the leverage in building a good skill is in capturing real procedure, not in inventing abstract capabilities.
Anthropic’s own framing for this is unusually clear: building a skill is like writing an onboarding guide for a new hire. Not a product spec. Not a prompt hack. An onboarding guide. Something that explains the context, the steps, the examples, and what good output looks like.
That framing matters because it makes the scope obvious. A good onboarding guide covers one job well. It does not try to cover an entire role.
The failure mode I see most often is starting too wide.
Someone decides to build a “design assistant” skill or a “research helper” skill. The scope sounds useful, but it is too large to trigger reliably and too vague to produce consistent output.
Narrow skills work better. One workflow. Clear trigger. Specific metadata.
The name and description fields matter more than most people expect, because those are what the agent reads to decide whether to load the skill. A vague description produces unpredictable invocation. A precise one makes the skill feel almost automatic.
Here is the practical loop that works:
- Do the task once properly with the agent.
- Notice the steps that worked and the corrections you had to make.
- Save the input shape and output shape, not just the final answer.
That raw material becomes the skill. The instructions capture what you already know. The examples show the model what success looks like. The guardrails encode the corrections you kept making.
A good skill comes from real work first, formatting second.
Once you have the core working, the rule for adding depth is simple: only add complexity when it earns its keep.
The main SKILL.md file should stay lean. Just the instructions and examples needed for the agent to know when and how to act. Edge cases and reference material go in separate files, loaded only when needed. Scripts are worth adding when the task genuinely needs deterministic execution, not because code makes the skill feel more sophisticated.
This repo uses the same pattern. The LinkedIn pipeline runs as four separate skills. Ingest, research, outline, slides. Each owning one stage and handing off cleanly to the next. No single skill tries to own the whole pipeline. That is why it composes.
The goal is not a skill that covers everything. It is a skill that handles one thing reliably enough to be trusted every time you reach for it.