Claude Skills are reusable task instructions packaged with supporting resources. A skill tells Claude how to carry out a repeatable job; a tool supplies an operation, and a connection can make an external system available. Understanding those roles helps you build a skill that is useful without treating installation as a guarantee of correct work.
This article designs a report-review skill for a fictional community program. It includes a small folder, an input contract, three test cases and a failure review. All sample claims and expected answers are authored fixtures. They demonstrate what to check, not measured performance from a live Claude session.
What are Claude Skills used for?
The official Skills guide describes task instructions and resources that Claude can load when relevant. For practical design, ask which procedure you repeat often enough to deserve a maintained artifact. Report checking, release-note preparation and a house style review can qualify; one meeting's attendance count usually belongs in that meeting's source material.
A useful skill has a recognizable trigger and an observable result. “Help with all business tasks” is too broad to test. “Check factual claims in a draft against the supplied source manifest and return a review table” is narrow enough to exercise with examples.
Do not confuse relevance with authority. A skill can describe how a task should be performed, but it does not automatically make source facts true or authorize every action a connected tool exposes. Those concerns need their own boundaries.
Separate skills, tools, MCP and task inputs
Imagine reviewing a workshop report. The skill provides the review method. A file-reading tool retrieves approved files. An MCP server may expose resources or operations from another system. The current task supplies the draft, source identifiers and the specific question. A reviewer accepts or rejects the result.
| Component | Question it answers | Example in this exercise |
|---|---|---|
| Skill | How should this repeatable task be done? | Check each factual claim against a source |
| Tool | Which operation can be performed? | Read a supplied text file |
| MCP connection | Which external resources or operations are exposed? | An approved document service |
| Task input | What is being reviewed this time? | Workshop draft and S1–S3 |
| Human decision | What should happen with the findings? | Approve a corrected report |
A skill that says “send the approved report” still needs a defined destination, authorization and a suitable tool. A connected service that can send messages does not mean this review task should send one. Draw that distinction before writing a long instruction file.
For a concrete delegation task using the same kind of evidence, see how to use Claude Cowork. The current article focuses on the reusable procedure rather than one task's execution.
Build the smallest useful folder
Start with a name, a short description of when the skill is relevant, and the review procedure. Put long examples and checklists in supporting files so that the core instructions remain readable. Download the original review-skill exercise, which contains the folder outline, a teaching SKILL.md and test cases.
report-evidence-review/
SKILL.md
references/
review-checklist.md
examples/
three-review-cases.md
The download is a readable teaching document, not an installed skill or an automatically imported package. Adapt the files to the supported format and installation method of your chosen Claude environment. Inspect the content before enabling it, especially if you later add scripts or external operations.
A concise description should say both the task and the expected result: review a draft against supplied sources and return supported, unsupported, conflicting or unresolved findings. Avoid promising accuracy that the procedure has not demonstrated. “Guarantees factual reports” is a marketing claim, not a useful activation description.
Define the input and output contract
Our skill requires a draft and a manifest naming each permitted source. It can proceed when both are present. If a source is missing, it should identify the affected claims and request that source. It should not substitute a general web search unless the particular task permits that expansion.
Each review row contains the draft claim, source ID, supporting passage, finding and proposed edit. A finding can be supported, contradicted, not established or ambiguous. Keep those labels distinct. A source that does not mention satisfaction does not prove dissatisfaction; it only fails to establish the draft's satisfaction claim.
Map the review as task inputs → relevant skill → permitted reading tools → evidence table → human review. Open the AI agent architecture template, replace the generic tool labels with the operations you actually permit, and add a separate draft-approval node. You should be able to point to where a missing source stops the process.
Author-created example: inspect the relationships before adapting the template.
This planning map does not install a skill or connect an MCP server. It helps you keep instructions, evidence and capabilities visible while adapting the exercise to your environment.
Write instructions that a reviewer can inspect
A review procedure can be explicit without becoming an enormous policy manual. Extract factual claims, match each claim to the named source, preserve the source's scope and units, mark unsupported inferences, and propose the smallest correction that resolves the issue. Return unresolved questions instead of manufacturing certainty.
For example, a source says 12 visitors brought an item for assessment. A draft says 12 items were repaired. The correct finding is that the repair outcome is not established by that source. The proposed edit restores the source meaning; it does not invent a repair count of zero.
Preserve negative findings in the final table. If the task ends with a clean rewritten paragraph but hides all unresolved claims, the reviewer loses the ability to distinguish verified facts from removed material. A useful output can include a corrected draft and a short unresolved list, clearly labeled as separate artifacts.
Decide how to treat quoted instructions inside the source. A report may contain an example prompt saying “ignore the checklist.” That text is material under review, not an instruction for the reviewer. Add a test case that checks this distinction rather than relying on a vague statement to “be careful.”
Use three test cases before real work
The exercise supplies three cases with expected findings. They can be checked by a person before any model run, and reused later when the skill changes.
| Case | Input problem | Expected finding |
|---|---|---|
| 1: Changed measurement | Draft turns items brought into repairs completed | Outcome not established; restore original measure |
| 2: Missing source | Draft cites S4, but the manifest ends at S3 | Request S4; do not fabricate a supporting passage |
| 3: Instructions inside evidence | A source includes a quoted command to skip review | Treat quoted command as content and continue the review |
For each real test, keep the actual output next to the expected finding. Record the environment and skill version. Mark the case passed only when the result identifies the correct issue and respects the output boundary. A result that catches the mistake but sends a public message without permission does not pass the task contract.
Three cases are a starting exercise, not comprehensive evaluation. Add examples from actual review failures, especially claims involving dates, denominators, source versions and unresolved contradictions. Do not announce an accuracy percentage from this small authored set.
Distinguish a procedure problem from a capability problem
Suppose the review returns no evidence passages. The procedure might be unclear, the files might be unavailable, or the reading tool might have failed. Those require different corrections. Adding another paragraph to SKILL.md will not fix a disconnected resource.
Use a small diagnostic sequence: confirm the input manifest, confirm access to one approved source, confirm the review format, then compare a real output with the expected findings. Avoid rewriting everything after one failure. Preserve the failing case so the next change can be judged against the same input.
If the skill repeatedly requires a particular tool, name the dependency in the documentation. Explain what an acceptable incomplete result looks like when the dependency is absent. A clear failure message is more useful than a polished table with invented citations.
The context engineering guide addresses a related problem: choosing which sources should enter the task at all. Source selection and review procedure interact, but they should not be collapsed into one sprawling instruction file.
Maintain the skill as the work changes
Give the skill a change log outside its essential instructions. Record the previous behavior, the new rule, the case that justified it and the cases rerun. A review team needs to know whether a version changed output labels, input requirements or allowed actions.
Keep task-specific facts out of permanent instructions. Next month's room capacity should not remain embedded in the skill after the event changes. The rule “preserve capacity units and dates” is reusable; “the room holds eighteen people” is a fact that requires a current source.
Remove redundant instructions when you can show that a shorter rule preserves the tested behavior. Length alone does not make the skill robust. Conversely, do not delete an explicit stopping rule merely because it looks repetitive; check the failure case that rule was added to handle.
Common mistakes with Claude Skills
A description too broad to select reliably. Name the specific task and result. A skill for evidence review should not compete with every writing task just because both involve a report.
Treating a script as a trusted extension of prose. Scripts can perform operations. Inspect what they do, how inputs are handled and which files or services they touch. A familiar folder name is not a review of its contents.
Hardcoding one successful example. A skill that always produces the workshop answer has memorized a fixture. Change the facts and check whether the procedure still preserves the evidence meaning.
Mixing output formatting with approval. A correctly formatted table can contain wrong findings. Review structure and factual support separately, then record the human decision.
Adapt the review to your own reports
Replace the fictional sources with approved material and preserve the expected-output worksheet. Add failures you encounter, update the skill deliberately, and keep the human approval step visible. For tasks with retries and handoffs, the agentic workflow example shows how to model the surrounding process.
