Build reliable agent skills

Build Reliable Agent Skills

Help a Builder decide what deserves a Skill, define one verifiable result, and improve the Skill through concrete failures. Treat the Builder and domain owner as the authority for success criteria and unacceptable risk. Treat the Agent as an evidence organizer and implementation partner.

Choose the route

Use only the route needed for the current request.

Current need	Route	Required result
A prompt, SOP, or repeated task may become a Skill	Charter	A go/no-go decision and a narrow Skill charter
A Skill exists but its boundary is vague	Boundary	One observable definition of done
A concrete failure occurred	Diagnose	Failure class, evidence, and correct-layer patch
A Skill needs systematic improvement	Failure loop	Retest plan and one useful metric
A new Skill is being built end to end	Full workflow	Charter → minimum version → real run → patch → retest

Read references/method-cards.md for the matching card and template. Do not load unrelated cards unless the user asks for the full workflow.

Route 1: Decide whether the task deserves a Skill

Answer three questions with evidence:

1. Repeated task: Which specific job recurs?
2. Unique gap: What does the Agent lack that is specific to this team, system, or workflow?
3. Proof: Which observable state or artifact proves the job was done correctly?

Recommend build, do not build, or collect evidence first.

Build only when the task recurs, the gap adds information or executable capability beyond generic advice, and success can be checked. Do not turn one-off preferences or obvious best practices into permanent context.

For build, produce this minimum charter:

Skill job:
Trigger situation:
Expected result:
One real gotcha:
Success evidence:
Unacceptable risk / human decision:
Owner:

Keep the first version small: one clear job, one trigger, one real gotcha, and one success check. A Skill is a folder, not merely a longer prompt. Put detailed references, reusable scripts, templates, and guardrails in the appropriate files and load them progressively.

Route 2: Define a verifiable boundary

1. Rewrite the requested capability as one result that can be observed.
2. Separate surface signals from authoritative state.
3. Identify the system, record, assertion, artifact, or human confirmation that proves success.
4. State failure conditions and risks that require a human decision.

Do not accept “the command ran,” “the API returned 200,” “the page says success,” or “the Agent reviewed its work” as sufficient proof unless the domain owner confirms that signal is authoritative.

Route 3: Diagnose one concrete failure

Require a specific failure record: intended result, observed result, available evidence, and the current Skill files. If evidence is missing, label the diagnosis provisional.

Classify the failure before proposing a change:

Failure class	Typical symptom	Patch location
Trigger	The Skill should have run but was not selected	Skill name and frontmatter description
Knowledge	The Agent lacks a real domain-specific fact or gotcha	references/, examples, or a concise Gotchas section
Tool	The Agent repeatedly reconstructs the same deterministic action	scripts/, helpers, templates, or assets
Verification	The Agent completed an action but not the intended result	Assertions, state checks, test drivers, or evidence capture
Guardrail	A dangerous or forbidden action remains possible	Hook, deny rule, scoped permission, or human confirmation

Patch the smallest correct layer. Do not append every lesson to the end of SKILL.md.

For every proposed patch, provide:

• the failure evidence;
• the selected class and why competing classes were rejected;
• the exact file or mechanism to change;
• the proposed change;
• a retest using the same failure class;
• a regression risk or reasonable behavior that must remain possible.

Route 4: Run the failure-refill loop

1. Run the Skill on a real task, not only a happy-path demo.
2. Record one concrete failure without generalizing beyond the evidence.
3. Classify it as trigger, knowledge, tool, verification, or guardrail.
4. Patch the correct layer.
5. Rerun the same class of task and check the authoritative success evidence.
6. Observe one metric: trigger rate, verification pass rate, manual rework, or another domain-relevant measure.

Before making a failure permanent, check whether it is likely to recur, belongs inside this Skill's job, and can be fixed without blocking other valid approaches.

Deliver the result

Lead with the decision artifact, not a framework lecture. Include only the sections relevant to the selected route:

1. Decision or diagnosis
2. Evidence
3. Skill charter or layer patch
4. Retest and success proof
5. One metric
6. Human decisions still required

Distinguish facts supplied by the user, direct observations, source-derived guidance, and Agent hypotheses. Say insufficient evidence when the available material does not support a conclusion.

Boundaries

• Never invent team-specific gotchas, system behavior, user evidence, or success records.
• Never claim that a Skill works because its instructions look complete.
• Never treat a surface success signal as authoritative without checking the real state.
• Never automate an unacceptable-risk decision that belongs to the Builder or domain owner.
• Never overload one Skill with unrelated jobs merely because they share a topic.
• Preserve adaptation room; add guardrails where harm is unacceptable, not rigid instructions everywhere.

Source and attribution

This workflow was developed for episode 03 of the Chinese AI Builders 解读 series from Thariq Shihipar's first-party article, Lessons from building Claude Code: How we use skills, published by Claude. The source supports folder-based Skills, progressive disclosure, real gotchas, product verification, trigger descriptions, reusable scripts, on-demand hooks, and usage measurement.

Skill 立项三问 and 失败回填循环 are editorial tools created by AI Builders 解读; do not attribute those names or exact templates to Shihipar, Anthropic, or Claude. This Skill is not an official Anthropic product or endorsement.