Step 1: choose one recurring job
Pick a task you can recognize and evaluate. “Help with marketing” is too broad. “Audit a landing page and return prioritized conversion fixes” has a trigger, artifact, and observable output. A narrow first skill is easier to test and more likely to be used correctly.
Step 2: collect representative inputs
Gather at least three examples: a normal case, an incomplete case, and a difficult or risky case. Remove secrets and personal data. Write down what a good result contains and which mistakes would make it unusable.
Step 3: define the output contract
Choose stable headings, fields, or a schema. If the result feeds another system, validate types and required values. If a person reads it, make priorities and missing information obvious. The data-cleaning insight report skill is a useful example of a stable human-readable output.
Step 4: write SKILL.md
Create sections for purpose, use cases, required inputs, workflow, output, safety, and limitations. Use direct verbs. State when to ask a question and when to stop. Keep supporting detail in a referenced file only when it would distract from the core workflow.
Step 5: add job-specific guardrails
Name the real failure modes. A data skill must not invent values or silently transform columns. An outreach skill must not fabricate personalization. An integration skill must not invent endpoints or request excessive permissions. Study the data-cleaning insight skill and API integration architect skill for concrete boundaries.
Step 6: test behavior
Run every representative input and record failures. Test missing fields, contradictory instructions, untrusted text that tries to redirect the agent, unusually large inputs, and requests beyond scope. Confirm approval gates appear before external or destructive actions.
Step 7: revise ambiguous instructions
When output varies, do not simply add “be more consistent.” Identify the decision the model interpreted differently and make the rule observable. Add a small example when prose remains ambiguous. Remove redundant or contradictory language.
Step 8: package and document
Include only required references, templates, and scripts. Explain installation for the actual supported environment. State compatibility honestly. Add a changelog or reviewed date when the task depends on evolving tools, policies, or APIs.
Step 9: run a human review
Have another person use the skill without verbal guidance. If they cannot identify inputs, understand the output, or know when approval is required, revise the documentation. The goal is reusable operational knowledge, not a prompt that only its author understands.
Next, read the full SKILL.md format guide and compare your draft with 13 real Claude skill examples.