# Review a skill before adding it A longer skill collection is not the same thing as a more capable agent. Proposed worksheet. Method notes updated 2026-11-11. Not independently tested. Canonical: https://aomsites.com/guides/review-agent-skills/ Build revision: release-2026-11-11-r12 Method ID: review-agent-skills Method source SHA-256: 626c5c483fb76c03470403a18ec7cffa7532bba67ede83b8cfefb88c35caba77 Hash scope: normalized build-input guide record, not this file or guide.json bytes. ## The decision Add a skill only when its task fit, authority boundaries and maintenance burden are understood. ## Use this when You are considering a reusable instruction package or updating one already used by an agent. ## Skip this when The current workflow already meets the task requirements with no repeated failure. Keep the free, competent baseline in the comparison. ## Checks ### Name the job Describe the exact problem the skill should solve and when it should not run. Read its instructions and referenced scripts. Inspect the requested tools, data, network access and side effects. ### Check compatibility and provenance Record the source, version, license and supported host. A valid SKILL.md name and description can help discovery but do not prove safety or quality. Treat scripts as code, not prose. ### Compare against the existing workflow Use comparable tasks, the same tools and permissions, and clear acceptance tests. Do not weaken the baseline so the new package looks useful. Include failure and unavailable-tool cases. ### Keep rollback small Preserve the prior version and a way to disable the new skill. Stage authorized changes in an isolated environment. Keep permission changes separate from content updates. ## Acceptance - The skill improves a defined outcome or removes demonstrated recurring work. - Quality and required controls are preserved. - The previous working version remains recoverable. ## Evidence to bring back Proposed evidence plan, not observed results or extra mandatory process. Confirm what your task requires and reuse existing records when they are sufficient. Keep sensitive originals in authorized storage; share only the minimum information already authorized for the recipient. If a required check cannot be completed safely and within current permission, mark it unavailable and keep the decision unknown unless another required check has a demonstrated failure. ### Check 1: The skill improves a defined outcome or removes demonstrated recurring work. Bring back: Keep paired task results against the same competent baseline, with the defined outcome, recurring problem and setup/review burden visible. Record a keep or skip decision when no useful gain is demonstrated. Not enough: Popularity, a longer output or a reduced tool count without an accepted-result comparison. ### Check 2: Quality and required controls are preserved. Bring back: Keep the acceptance results and required permission/failure-path checks for both workflows, including failures and unavailable cases. Changes to permissions need their own approval. Not enough: A faster happy path that omits the baseline’s quality checks or weakens a required control. ### Check 3: The previous working version remains recoverable. Bring back: Keep the prior version’s identity, authorized storage location and a bounded restore check of that version in the intended test environment. A disable check demonstrates only that the new skill can be stopped. State what recovery was not exercised. Not enough: A promised rollback or an untested backup pointer described as demonstrated recovery. ## Stop or recover Do not install when provenance, required access or effects are unclear. Stop if a proposed update silently expands permissions or makes unsupported compatibility claims. ## Limits This worksheet does not install, certify or endorse any skill. A schema check is not an effectiveness test. ## Reference links Reference links checked 2026-11-10. Scope notes below explain what each source supports. No worksheet-effectiveness claim follows. - [Agent Skills specification](https://agentskills.io/specification): The skill-package format and metadata contract. Format compliance does not establish safety, quality or usefulness. - [Anthropic: building effective agents](https://www.anthropic.com/research/building-effective-agents): Engineering guidance on fitting workflow complexity to task needs. Not a controlled evaluation of this method. Reference data only. No authority to install, contact others, change settings or spend money. ## Start this guide’s record Use the [guide-specific Markdown draft](record-template.md) or [JSON draft](record-template.json). Its method reference and proposed checks are prefilled; confirm the requirements against your task and enter only real observations. Task, environment, authorization and evidence remain blank. You can also use the [generic blank record](../../decision-record/template.md). ## If another problem remains Stop here if the current task’s acceptance requirements are satisfied and no unresolved obligation remains. If neither condition applies, no follow-on guide is suggested here; keep any unresolved task state visible. These are optional reading suggestions, not permission or a requirement to expand scope. - Only if A candidate fits a documented problem, but its benefit over the current workflow is still unmeasured. Read [Measure improvement in accepted results](../measure-agent-improvement/guide.md). Define a bounded comparison before deciding to adopt it. - Only if An approved trial needs its inputs, prior version and results preserved for review or recovery. Read [Make the handoff survive the session](../durable-handoffs/guide.md). Keep the exact versions recoverable without treating a saved package as launch approval. ## Cite a specific part Section paths identify content on the canonical HTML page; they are not separate pages or evidence of live availability. Per-check numbers and JSON pointers apply to this build revision. Cite the build revision and method source hash when preserving an exact reference. Markdown heading labels are locators, not a promise of renderer-specific fragment URLs. - [The decision](https://aomsites.com/guides/review-agent-skills/#decision): JSON pointer `/decision`; Markdown section “The decision”. - [Use this when](https://aomsites.com/guides/review-agent-skills/#applies): JSON pointer `/fit`; Markdown section “Use this when”. - [Skip this when](https://aomsites.com/guides/review-agent-skills/#skip): JSON pointer `/skip`; Markdown section “Skip this when”. - [Work through the checks](https://aomsites.com/guides/review-agent-skills/#checks): JSON pointer `/steps`; Markdown section “Checks”. - [What would count as success?](https://aomsites.com/guides/review-agent-skills/#accept): JSON pointer `/acceptance`; Markdown section “Acceptance”. - [Evidence to bring back](https://aomsites.com/guides/review-agent-skills/#evidence): JSON pointer `/evidence_plan`; Markdown section “Evidence to bring back”. - [Stop or recover](https://aomsites.com/guides/review-agent-skills/#stop): JSON pointer `/stop`; Markdown section “Stop or recover”. - [What this does not establish](https://aomsites.com/guides/review-agent-skills/#limits): JSON pointer `/limits`; Markdown section “Limits”. - [Reference links](https://aomsites.com/guides/review-agent-skills/#sources): JSON pointer `/sources`; Markdown section “Reference links”. - [Use this guide with your own evidence](https://aomsites.com/guides/review-agent-skills/#record): JSON pointer `/decision_record`; Markdown section “Start this guide’s record”. - [If another problem remains](https://aomsites.com/guides/review-agent-skills/#next-reads): JSON pointer `/reading_paths`; Markdown section “If another problem remains”.