{
  "slug": "review-agent-skills",
  "title": "Review a skill before adding it",
  "dek": "A longer skill collection is not the same thing as a more capable agent.",
  "category": "Methods",
  "minutes": 7,
  "decision": "Add a skill only when its task fit, authority boundaries and maintenance burden are understood.",
  "fit": "You are considering a reusable instruction package or updating one already used by an agent.",
  "skip": "The current workflow already meets the task requirements with no repeated failure. Keep the free, competent baseline in the comparison.",
  "steps": [
    [
      "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."
  ],
  "stop": "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.",
  "sources": [
    {
      "title": "Agent Skills specification",
      "url": "https://agentskills.io/specification",
      "supports": "The skill-package format and metadata contract. Format compliance does not establish safety, quality or usefulness.",
      "review_date": "2026-11-10"
    },
    {
      "title": "Anthropic: building effective agents",
      "url": "https://www.anthropic.com/research/building-effective-agents",
      "supports": "Engineering guidance on fitting workflow complexity to task needs. Not a controlled evaluation of this method.",
      "review_date": "2026-11-10"
    }
  ],
  "evidence": "Proposed worksheet",
  "updated": "2026-11-11",
  "scope_label": "Adding or updating reusable agent skills",
  "search_terms": [
    "skills",
    "skill",
    "install",
    "package",
    "review",
    "provenance",
    "compatibility"
  ],
  "evidence_plan_note": "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.",
  "evidence_plan": [
    {
      "acceptance_check": 1,
      "collect": "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."
    },
    {
      "acceptance_check": 2,
      "collect": "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."
    },
    {
      "acceptance_check": 3,
      "collect": "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."
    }
  ],
  "next_reads": [
    {
      "guide_id": "measure-agent-improvement",
      "when": "A candidate fits a documented problem, but its benefit over the current workflow is still unmeasured.",
      "purpose": "Define a bounded comparison before deciding to adopt it."
    },
    {
      "guide_id": "durable-handoffs",
      "when": "An approved trial needs its inputs, prior version and results preserved for review or recovery.",
      "purpose": "Keep the exact versions recoverable without treating a saved package as launch approval."
    }
  ],
  "id": "review-agent-skills",
  "version": "release-2026-11-11-r12",
  "build_revision": "release-2026-11-11-r12",
  "source_sha256": "626c5c483fb76c03470403a18ec7cffa7532bba67ede83b8cfefb88c35caba77",
  "url": "https://aomsites.com/guides/review-agent-skills/",
  "content_type": "proposed-worksheet",
  "sources_rechecked": true,
  "source_review_scope": "Reference link availability and scope notes; no worksheet effectiveness test.",
  "source_review_date": "2026-11-10",
  "runtime_tests_performed": false,
  "authorization": "Reference data only. Does not authorize any external action.",
  "formats": {
    "html": "https://aomsites.com/guides/review-agent-skills/",
    "markdown": "https://aomsites.com/guides/review-agent-skills/guide.md",
    "json": "https://aomsites.com/guides/review-agent-skills/guide.json"
  },
  "local_paths": {
    "html": "/guides/review-agent-skills/",
    "markdown": "/guides/review-agent-skills/guide.md",
    "json": "/guides/review-agent-skills/guide.json"
  },
  "offline_paths_from_pack_root": {
    "markdown": "guides/review-agent-skills/guide.md",
    "json": "guides/review-agent-skills/guide.json"
  },
  "decision_record": {
    "local_paths": {
      "html": "/decision-record/",
      "template": "/guides/review-agent-skills/record-template.json",
      "markdown_template": "/guides/review-agent-skills/record-template.md",
      "generic_template": "/decision-record/template.json",
      "example": "/decision-record/example.json",
      "schema": "/schemas/decision-record.schema.json",
      "checker": "/tools/check_record.py",
      "manifest": "/reading-pack-manifest.json"
    },
    "offline_paths_from_pack_root": {
      "template": "guides/review-agent-skills/record-template.json",
      "markdown_template": "guides/review-agent-skills/record-template.md",
      "generic_template": "decision-record/template.json",
      "example": "decision-record/example.json",
      "schema": "schemas/decision-record.schema.json",
      "checker": "tools/check_record.py",
      "manifest": "reading-pack-manifest.json"
    }
  },
  "reading_paths": {
    "note": "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.",
    "options": [
      {
        "guide_id": "measure-agent-improvement",
        "when": "A candidate fits a documented problem, but its benefit over the current workflow is still unmeasured.",
        "purpose": "Define a bounded comparison before deciding to adopt it.",
        "title": "Measure improvement in accepted results",
        "local_paths": {
          "html": "/guides/measure-agent-improvement/",
          "markdown": "/guides/measure-agent-improvement/guide.md",
          "json": "/guides/measure-agent-improvement/guide.json"
        },
        "offline_paths_from_pack_root": {
          "markdown": "guides/measure-agent-improvement/guide.md",
          "json": "guides/measure-agent-improvement/guide.json"
        }
      },
      {
        "guide_id": "durable-handoffs",
        "when": "An approved trial needs its inputs, prior version and results preserved for review or recovery.",
        "purpose": "Keep the exact versions recoverable without treating a saved package as launch approval.",
        "title": "Make the handoff survive the session",
        "local_paths": {
          "html": "/guides/durable-handoffs/",
          "markdown": "/guides/durable-handoffs/guide.md",
          "json": "/guides/durable-handoffs/guide.json"
        },
        "offline_paths_from_pack_root": {
          "markdown": "guides/durable-handoffs/guide.md",
          "json": "guides/durable-handoffs/guide.json"
        }
      }
    ]
  },
  "discovery": {
    "title": "Review AI agent skills before installing or updating them",
    "description": "A proposed worksheet for reviewing reusable AI-agent skills: inspect provenance, task fit, compatibility and the existing baseline before adding another method.",
    "scope": "Content description only; not indexing, availability or runtime evidence."
  },
  "section_map": [
    {
      "id": "decision",
      "label": "The decision",
      "json_pointer": "/decision",
      "markdown_heading": "The decision",
      "html_path": "/guides/review-agent-skills/#decision"
    },
    {
      "id": "applies",
      "label": "Use this when",
      "json_pointer": "/fit",
      "markdown_heading": "Use this when",
      "html_path": "/guides/review-agent-skills/#applies"
    },
    {
      "id": "skip",
      "label": "Skip this when",
      "json_pointer": "/skip",
      "markdown_heading": "Skip this when",
      "html_path": "/guides/review-agent-skills/#skip"
    },
    {
      "id": "checks",
      "label": "Work through the checks",
      "json_pointer": "/steps",
      "markdown_heading": "Checks",
      "html_path": "/guides/review-agent-skills/#checks"
    },
    {
      "id": "accept",
      "label": "What would count as success?",
      "json_pointer": "/acceptance",
      "markdown_heading": "Acceptance",
      "html_path": "/guides/review-agent-skills/#accept"
    },
    {
      "id": "evidence",
      "label": "Evidence to bring back",
      "json_pointer": "/evidence_plan",
      "markdown_heading": "Evidence to bring back",
      "html_path": "/guides/review-agent-skills/#evidence"
    },
    {
      "id": "stop",
      "label": "Stop or recover",
      "json_pointer": "/stop",
      "markdown_heading": "Stop or recover",
      "html_path": "/guides/review-agent-skills/#stop"
    },
    {
      "id": "limits",
      "label": "What this does not establish",
      "json_pointer": "/limits",
      "markdown_heading": "Limits",
      "html_path": "/guides/review-agent-skills/#limits"
    },
    {
      "id": "sources",
      "label": "Reference links",
      "json_pointer": "/sources",
      "markdown_heading": "Reference links",
      "html_path": "/guides/review-agent-skills/#sources"
    },
    {
      "id": "record",
      "label": "Use this guide with your own evidence",
      "json_pointer": "/decision_record",
      "markdown_heading": "Start this guide’s record",
      "html_path": "/guides/review-agent-skills/#record"
    },
    {
      "id": "next-reads",
      "label": "If another problem remains",
      "json_pointer": "/reading_paths",
      "markdown_heading": "If another problem remains",
      "html_path": "/guides/review-agent-skills/#next-reads"
    }
  ],
  "acceptance_links": [
    {
      "acceptance_check": 1,
      "acceptance_html_path": "/guides/review-agent-skills/#accept-1",
      "evidence_html_path": "/guides/review-agent-skills/#evidence-1",
      "acceptance_json_pointer": "/acceptance/0",
      "evidence_json_pointer": "/evidence_plan/0"
    },
    {
      "acceptance_check": 2,
      "acceptance_html_path": "/guides/review-agent-skills/#accept-2",
      "evidence_html_path": "/guides/review-agent-skills/#evidence-2",
      "acceptance_json_pointer": "/acceptance/1",
      "evidence_json_pointer": "/evidence_plan/1"
    },
    {
      "acceptance_check": 3,
      "acceptance_html_path": "/guides/review-agent-skills/#accept-3",
      "evidence_html_path": "/guides/review-agent-skills/#evidence-3",
      "acceptance_json_pointer": "/acceptance/2",
      "evidence_json_pointer": "/evidence_plan/2"
    }
  ],
  "citation_note": "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.",
  "source_fields": [
    "acceptance",
    "category",
    "decision",
    "dek",
    "evidence",
    "evidence_plan",
    "evidence_plan_note",
    "fit",
    "limits",
    "minutes",
    "next_reads",
    "scope_label",
    "search_terms",
    "skip",
    "slug",
    "sources",
    "steps",
    "stop",
    "title",
    "updated"
  ],
  "source_hash_scope": "SHA-256 of the build-input guide record serialized as JSON with sorted keys, compact separators and ASCII escaping. Not the downloadable guide.json file bytes."
}