Claude opencode Skill

skill-builder

Create a metadata-complete AgentOps skill source package, regenerate its derived projections, and check or repair structural hygiene in skill packages. Triggers: "create a skill", "scaffold skill", "absorb external skill", "new skill", "heal skill", "repair skill hygiene", "audit

LLM Mart · 0 points · 10 views 0 listing impressions 0 install-command copies
Download boshu2-agentops-skills_skill-builder-596942d.zip · 74 KB

Install

skills CLI npx skills add https://github.com/boshu2/agentops/tree/main/skills/skill-builder
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install boshu2-agentops@llmmart
Git git clone https://github.com/boshu2/agentops.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole boshu2/agentops collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Skill Builder

Create, repair, audit or export one canonical skill package, or turn supported expertise into a small authoring proposal. Before writing anything new, decide from evidence whether anything new is warranted: a request for a new skill, gate or tracking file usually ends as a short addition to an existing owner, or as no change.

Decide whether to create anything

Apply these before any creation step, including when the request already names the new skill or file it wants:

  1. Find the existing owner. Search skills, references, checklists and instruction files for one that already handles the behavior. Extend that owner rather than adding a root.
  2. Count independent occurrences. A new skill, gate, library or workflow needs three independently evidenced real occurrences and a successful reapplication to a source case without missing context. Fewer occurrences support only a narrow note in an existing owner; one incident is an observation, not a skill. An authoritative source supports only a faithful statement of that source.
  3. Name the consumer of every new artifact. A proposed process artifact (a report, ledger, counter, dashboard or tracker) needs a concrete consumer, the decision it informs, the observed defect it answers and a retirement condition. If any is missing, leave it out; code written only to consume it is no consumer.
  4. No action is a valid result, and so is a short addition to an existing owner. Say what the evidence supports before drafting, build only what the caller then authorizes, and return a proposal inline unless a durable one was requested.
  5. A built package proves no benefit. Route behavioral benefit to Skill Eval and acceptance judgment to Validate.

The result shows it worked when it names the existing owner it searched, the number of independent occurrences found, and either no new file or exactly the package the caller authorized.

Choose the requested operation

<skill-dir> is the directory that contains this SKILL.md. Claude Code shows it as "Base directory for this skill"; Codex lists this skill's SKILL.md path; in an AgentOps source checkout it is skills/skill-builder. Replace <skill-dir> with that absolute path before running a command. The working directory stays the user's repository. If the host did not show where this skill is installed, use the directory of the SKILL.md you read. If you cannot determine it, do not guess a path or run a same-named script from the current repository; say the bundled script is unavailable and apply the rules and doctrine here to the package by hand and use its repository's own checks.

Need Entry point Runs only with
Create a source package bash "<skill-dir>/scripts/build.sh" from-scratch <slug>, from-template <slug> --like <existing-slug> or absorb-external <slug> --from <path> an AgentOps source checkout with Go
Check package structure bash "<skill-dir>/scripts/heal.sh" --check [--strict] skills/<slug> Go in a source checkout, or ao 3.9 or later elsewhere
Repair the skill mesh bash "<skill-dir>/scripts/heal.sh" --fix skills/<slug> an AgentOps source checkout with Go
Inspect audit evidence bash "<skill-dir>/scripts/audit.sh" [--profile canonical\|portable\|external-observation] [--json <path>] skills/<slug> Go in a source checkout, or ao 3.9 or later elsewhere
Merge overlapping skills Consolidate nothing bundled
Export to another platform Conversion Bash 4.3 or later
Make repeated expertise reusable Distill expertise nothing bundled

Run only the selected operation. A plugin install ships these scripts but no ao binary or Go source: without ao on PATH, audit.sh exits 127 with ao: not found and heal.sh exits 2. Then apply the source template and authoring doctrine by hand and use the target repository's own checks. build.sh and heal.sh --fix work on skills/ of an AgentOps source checkout and refuse with exit 2 elsewhere, such as from a plugin install, instead of writing into its cache; heal.sh --fix checks the source first, so a target with findings exits 1 before that refusal. heal.sh in either mode checks only its own root's skills/ and resolves a relative target there, not in the current directory. For a skill in another repository or a user's skills directory, apply the rules and doctrine here to that directory and use its own checks; with ao installed, audit.sh resolves targets from the current directory and has portable and external-observation profiles, so it is the bundled check there. Roots, inputs, report destinations, exit codes and recovery from partial creation are in build and check mechanics.

Create and maintain

Treat external skills as structural signals only. Clean-room output must not copy their names, prose, prompts, scripts or examples. Every creation mode writes the same blank scaffold: from-template only checks the named skill and records it as source_hint, and absorb-external only verifies its input. Neither imports another skill's content or metadata.

build.sh creates one incomplete source package containing only SKILL.md with metadata.authoring_state: scaffold; helpers, references and assets are conditional on the actual behavior. Replace the placeholders and state applicability, inputs, authority, result, completion and failure in the layout that makes them clear. An ending such as "hand off" or "then stop" can end the caller's turn when the skill runs inline; read endings before writing one. Remove the scaffold state only after authoring the behavior; strict source checks reject it. Removing it is an author assertion, not proof of semantic completeness.

Before editing a skill after a miss or a review finding, read changing existing text; it decides when text stays unchanged, when a list stays explicit, and what to check before cutting a line.

Edit skills/<slug>/ as the source owner. Check the completed source with bash "<skill-dir>/scripts/heal.sh" --check --strict skills/<slug>. In an AgentOps source checkout only, run bash scripts/regen-all.sh from the repository root to regenerate every owned projection, including plugin/skills/; bash "<skill-dir>/scripts/heal.sh" --fix skills/<slug> regenerates only the skill mesh and leaves plugin copies unchanged. Inspect the generated diff; hand-edit no projection. A clean check says nothing about behavior: when an edit changes when the skill routes, what it asks, when it stops, what it commits or publishes or how it degrades, or cuts a line that recorded provenance protects, report that behavior as unmeasured unless a Skill Eval result measured that behavior, and name what was missing (a runner, a host or the caller's authorization). Typo, path and formatting edits need no such note.

Creation is staged, not atomic. If a later stage fails, keep the created source and any report and follow recovery; never call a partial result a completed package or delete it to rerun creation. A missing script, reference or runtime blocks only the operation that needs it; name it and continue the rest.

The default audit reports conformance, effects, behavior and authoring suspicions separately, with no total or verdict; effects and behavior stay NOT_PROVEN because it runs no skill. Checks, exit codes and the opt-in legacy schema are in audit checks; what Codex reads is in Codex parity.

Consolidate

Merge only when two skills own the same behavior; a shared passage or two is a cross-link, not a merge. Apply the decision rules above, then pick one owner: keep the skill with the stronger contract (clearer applicability, authority, result and failure path) and move into it only the rules the other has and it lacks. Before retiring the other name, search the skills, references, instruction files, goal prompts, workflows and docs for callers that invoke it by name, point each at the owner, and keep the old name until every caller does. In the AgentOps repository, also record the retired name and its new owner in docs/MIGRATION.md and add the slug to REMOVED_SKILLS in scripts/check-cathedral-cut-conformance.py, which fails if the skill comes back; never delete a skill there without that tombstone. A merge can move routing, so report as unmeasured whether the requests the retired skill caught now reach the owner unless a routing or Skill Eval result measured it.

Conversion

Run bash "<skill-dir>/scripts/converter/convert.sh" <source-skill-dir> <target> [output-dir] to export one package, or --all, to codex, cursor or test outside the shipped tree. Before an export, read running the converter for path resolution, the default output and its refusals. Preserve the source; fix the source or adapter, never the exported output.

Distill expertise

When the caller wants a reusable rule, apply the decision rules above and begin with cited occurrences or a named authoritative source. State the trigger, desired behavior, inputs, outputs, limits and a negative or holdout case the rule decides correctly, with short source excerpts and resolvable citations. Use Research's pattern mode when the claim needs exemplars and a holdout, and Memory's source and destination rules for mined material. A proposal-only request ends with the proposal. For an actual package edit, use the source template for required fields and the admission test in changing existing text to decide which prose earns a place.

Files (agentops)
  • references
    • converter
      • skill-bundle-schema.md 4.5 KB
        Loading…
    • audit-checks.md 4.2 KB
      Loading…
    • authoring-doctrine.md 11.8 KB
      Loading…
    • build-mechanics.md 5 KB
      Loading…
    • codex-parity.md 2.3 KB
      Loading…
    • heal.feature 1.1 KB · in bundle
    • skill-auditor.feature 2.1 KB · in bundle
    • skill-builder.feature 1.8 KB · in bundle
    • skill-conformance-profiles.yaml 4.5 KB
      Loading…
    • skill-template.md 2.1 KB
      Loading…
  • schemas
    • audit-report-legacy.json 17.4 KB
      Loading…
    • audit-report.json 5.4 KB
      Loading…
    • build-report.json 765 B
      Loading…
  • scripts
    • converter
      • convert.sh 25.2 KB
        Loading…
      • validate.sh 4.3 KB
        Loading…
    • audit-legacy.sh 17.7 KB
      Loading…
    • audit.sh 941 B
      Loading…
    • authoring_scan.py 7.1 KB
      Loading…
    • build.sh 1.2 KB
      Loading…
    • conformance_profile.py 18 KB
      Loading…
    • craft_score.py 12.1 KB
      Loading…
    • heal.sh 2.1 KB
      Loading…
    • init.sh 518 B
      Loading…
    • run-ao.sh 752 B
      Loading…
    • scan_descriptions.py 21.2 KB
      Loading…
    • score_agentops_skill.py 12 KB
      Loading…
    • test-authoring-mutations.sh 3.3 KB
      Loading…
    • test-craft-mutations.sh 3.1 KB
      Loading…
    • test-mutation-boundaries.sh 2.5 KB
      Loading…
    • validate.sh 3.8 KB
      Loading…
  • SKILL.md 11.1 KB
    ---
    name: skill-builder
    description: 'Create, repair, audit or consolidate agent skills (SKILL.md packages). Use when: writing or fixing a skill, its description or structure. Not for one-off lessons; use Memory.'
    practices:
    - pragmatic-programmer
    - refactoring
    hexagonal_role: supporting
    consumes: []
    produces:
    - skill-source-package
    - skill-hygiene-report
    - converted-skill
    - operationalization-proposal
    context_rel: []
    skill_api_version: 1
    user-invocable: true
    metadata:
      capabilities: [skill_builder, heal_skill, export_skill, distill_expertise]
      effects: [write_skill_source, write_build_report, regenerate_skill_projections, repair_skill_projections, write_converted_skill_projection, write_advisory_proposal]
      canonical_status: canonical
      disposition: keep_specialist
      tier: meta
      dependencies: []
      stability: experimental
    output_contract: build-report.json for creation, audit-report.json for audit, target-valid exported files for conversion, or an advisory expertise proposal
    ---
    # Skill Builder
    
    Create, repair, audit or export one canonical skill package, or turn supported
    expertise into a small authoring proposal. Before writing anything new, decide
    from evidence whether anything new is warranted: a request for a new skill,
    gate or tracking file usually ends as a short addition to an existing owner,
    or as no change.
    
    ## Decide whether to create anything
    
    Apply these before any creation step, including when the request already names
    the new skill or file it wants:
    
    1. **Find the existing owner.** Search skills, references, checklists and
       instruction files for one that already handles the behavior. Extend that
       owner rather than adding a root.
    2. **Count independent occurrences.** A new skill, gate, library or workflow
       needs three independently evidenced real occurrences and a successful
       reapplication to a source case without missing context. Fewer occurrences
       support only a narrow note in an existing owner; one incident is an
       observation, not a skill. An authoritative source supports only a faithful
       statement of that source.
    3. **Name the consumer of every new artifact.** A proposed process artifact
       (a report, ledger, counter, dashboard or tracker) needs a concrete consumer,
       the decision it informs, the observed defect it answers and a retirement
       condition. If any is missing, leave it out; code written only to consume it
       is no consumer.
    4. **No action is a valid result**, and so is a short addition to an existing
       owner. Say what the evidence supports before drafting, build only what the
       caller then authorizes, and return a proposal inline unless a durable one
       was requested.
    5. **A built package proves no benefit.** Route behavioral benefit to
       [Skill Eval](../skill-eval/SKILL.md) and acceptance judgment to
       [Validate](../validate/SKILL.md).
    
    The result shows it worked when it names the existing owner it searched, the
    number of independent occurrences found, and either no new file or exactly the
    package the caller authorized.
    
    ## Choose the requested operation
    
    `<skill-dir>` is the directory that contains this SKILL.md. Claude Code shows it
    as "Base directory for this skill"; Codex lists this skill's SKILL.md path; in
    an AgentOps source checkout it is `skills/skill-builder`. Replace `<skill-dir>`
    with that absolute path before running a command. The working directory stays
    the user's repository. If the host did not show where this skill is installed,
    use the directory of the SKILL.md you read. If you cannot determine it, do not
    guess a path or run a same-named script from the current repository; say the
    bundled script is unavailable and apply the rules and doctrine here to the
    package by hand and use its repository's own checks.
    
    | Need | Entry point | Runs only with |
    |---|---|---|
    | Create a source package | `bash "<skill-dir>/scripts/build.sh" from-scratch <slug>`, `from-template <slug> --like <existing-slug>` or `absorb-external <slug> --from <path>` | an AgentOps source checkout with Go |
    | Check package structure | `bash "<skill-dir>/scripts/heal.sh" --check [--strict] skills/<slug>` | Go in a source checkout, or `ao` 3.9 or later elsewhere |
    | Repair the skill mesh | `bash "<skill-dir>/scripts/heal.sh" --fix skills/<slug>` | an AgentOps source checkout with Go |
    | Inspect audit evidence | `bash "<skill-dir>/scripts/audit.sh" [--profile canonical\|portable\|external-observation] [--json <path>] skills/<slug>` | Go in a source checkout, or `ao` 3.9 or later elsewhere |
    | Merge overlapping skills | [Consolidate](#consolidate) | nothing bundled |
    | Export to another platform | [Conversion](#conversion) | Bash 4.3 or later |
    | Make repeated expertise reusable | [Distill expertise](#distill-expertise) | nothing bundled |
    
    Run only the selected operation. A plugin install ships these scripts but no
    `ao` binary or Go source: without `ao` on PATH, `audit.sh` exits 127 with
    `ao: not found` and `heal.sh` exits 2. Then apply the
    [source template](references/skill-template.md) and
    [authoring doctrine](references/authoring-doctrine.md) by hand and use the
    target repository's own checks. `build.sh` and `heal.sh --fix` work on
    `skills/` of an AgentOps source checkout and refuse with exit 2 elsewhere, such
    as from a plugin install, instead of writing into its cache; `heal.sh --fix`
    checks the source first, so a target with findings exits 1 before that refusal.
    `heal.sh` in either mode checks only its own root's `skills/` and resolves a
    relative target there, not in the current directory. For a skill in another
    repository or a user's skills directory, apply the rules and doctrine here to
    that directory and use its own checks; with `ao` installed, `audit.sh` resolves
    targets from the current directory and has `portable` and
    `external-observation` profiles, so it is the bundled check there.
    Roots, inputs, report destinations, exit codes and recovery from partial
    creation are in [build and check mechanics](references/build-mechanics.md).
    
    ## Create and maintain
    
    Treat external skills as structural signals only. Clean-room output must not
    copy their names, prose, prompts, scripts or examples. Every creation mode
    writes the same blank scaffold: `from-template` only checks the named skill and
    records it as `source_hint`, and `absorb-external` only verifies its input.
    Neither imports another skill's content or metadata.
    
    `build.sh` creates one incomplete source package containing only
    `SKILL.md` with `metadata.authoring_state: scaffold`; helpers, references and
    assets are conditional on the actual behavior. Replace the placeholders and
    state applicability, inputs, authority, result, completion and failure in the
    layout that makes them clear. An ending such as "hand off" or "then stop" can
    end the caller's turn when the skill runs inline; read
    [endings](references/authoring-doctrine.md#state-authority-and-a-usable-failure-path)
    before writing one. Remove the scaffold state only after authoring the
    behavior; strict source checks reject it. Removing it is an author assertion,
    not proof of semantic completeness.
    
    Before editing a skill after a miss or a review finding, read
    [changing existing text](references/authoring-doctrine.md#change-existing-text-at-its-owning-layer);
    it decides when text stays unchanged, when a list stays explicit, and what to
    check before cutting a line.
    
    Edit `skills/<slug>/` as the source owner. Check the completed source with
    `bash "<skill-dir>/scripts/heal.sh" --check --strict skills/<slug>`. In an
    AgentOps source checkout only, run `bash scripts/regen-all.sh` from the
    repository root to regenerate every owned projection, including
    `plugin/skills/`; `bash "<skill-dir>/scripts/heal.sh" --fix skills/<slug>`
    regenerates only the skill mesh and leaves plugin copies unchanged. Inspect the
    generated diff; hand-edit no projection. A clean check says nothing about
    behavior: when an edit changes
    when the skill routes, what it asks, when it stops, what it commits or
    publishes or how it degrades, or cuts a line that recorded provenance protects,
    report that behavior as unmeasured unless a [Skill Eval](../skill-eval/SKILL.md)
    result measured that behavior, and name what was missing (a runner, a host or
    the caller's authorization). Typo, path and formatting edits need no such note.
    
    Creation is staged, not atomic. If a later stage fails, keep the created source
    and any report and follow [recovery](references/build-mechanics.md#staged-creation-and-recovery);
    never call a partial result a completed package or delete it to rerun creation.
    A missing script, reference or runtime blocks only the operation that needs it;
    name it and continue the rest.
    
    The default audit reports conformance, effects, behavior and authoring
    suspicions separately, with no total or verdict; effects and behavior stay
    `NOT_PROVEN` because it runs no skill. Checks, exit codes and the opt-in legacy
    schema are in [audit checks](references/audit-checks.md); what Codex reads is in
    [Codex parity](references/codex-parity.md).
    
    ## Consolidate
    
    Merge only when two skills own the same behavior; a shared passage or two is a
    cross-link, not a merge. Apply the decision rules above, then pick one owner:
    keep the skill with the stronger contract (clearer applicability, authority,
    result and failure path) and move into it only the rules the other has and it
    lacks. Before retiring the other name, search the skills, references,
    instruction files, goal prompts, workflows and docs for callers that invoke it
    by name, point each at the owner, and keep the old name until every caller does.
    In the AgentOps repository, also record the retired name and its new owner in
    `docs/MIGRATION.md` and add the slug to `REMOVED_SKILLS` in
    `scripts/check-cathedral-cut-conformance.py`, which fails if the skill comes
    back; never delete a skill there without that tombstone. A merge can move
    routing, so report as unmeasured whether the requests the retired skill caught
    now reach the owner unless a routing or [Skill Eval](../skill-eval/SKILL.md)
    result measured it.
    
    ## Conversion
    
    Run `bash "<skill-dir>/scripts/converter/convert.sh" <source-skill-dir> <target>
    [output-dir]` to export one package, or `--all`, to `codex`, `cursor` or `test`
    outside the shipped tree. Before an export, read
    [running the converter](references/converter/skill-bundle-schema.md#run-the-converter)
    for path resolution, the default output and its refusals. Preserve the source;
    fix the source or adapter, never the exported output.
    
    ## Distill expertise
    
    When the caller wants a reusable rule, apply the decision rules above and begin
    with cited occurrences or a named authoritative source. State the trigger,
    desired behavior, inputs, outputs, limits and a negative or holdout case the
    rule decides correctly, with short source excerpts and resolvable citations.
    Use Research's [pattern mode](../research/SKILL.md#pattern-evidence) when the
    claim needs exemplars and a holdout, and
    [Memory's source and destination rules](../memory/SKILL.md) for mined material.
    A proposal-only request ends with the proposal. For an actual package edit, use
    the [source template](references/skill-template.md) for required fields and the
    admission test in [changing existing text](references/authoring-doctrine.md#change-existing-text-at-its-owning-layer)
    to decide which prose earns a place.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.