skill-build

Files (12)

• SKILL.md
• build-needs-core.yaml · fixtures/
• build-no-skill-skips-write.yaml · fixtures/
• build-thin-skill.yaml · fixtures/
• composes-in-graph.yaml · fixtures/
• harness-no-change-skips-write.yaml · fixtures/
• no-change-skips-write.yaml · fixtures/
• composed.graph · fixtures/support/
• mark.svg
• catalog.md · references/
• mark-license.md · references/
• run.yaml

SKILL.md (first lines)

# Skill Build

Build and improve Runx skills through one authoring surface. Keep judgment in
bounded agent acts and mechanics in native tools:

```text
inspect target files, catalog ownership, and native/shared tools
→ decide ownership, execution lanes, effects, budgets, and proof
→ bind that architecture to the inspected package digest in native code
→ compose existing capabilities before authoring code
→ author only bounded writes, explicit deletions, and output intent
→ bind those bytes to the admitted architecture in native code
→ validate paths, secret posture, and the complete candidate
→ inspect and safely replay the exact staged package
→ commit that validated bundle through one native transaction
```

Use the generic host `skill-creator` for platform-wide authoring guidance when
it is available. Do not reproduce Runx package operations from that guidance;
invoke the appropriate `skill-build` runner so the work is bounded and receipted.

## Captured source artifacts

An adoption or other caller may supply an immutable project-artifact descriptor
and a small source index in project_context. Open that exact descriptor with
artifact.open, then read bounded pages with artifact.read using the returned
artifact_uri. Preserve whole_digest, next_offset and eof; a partial page is not
the full source. Use the captured bytes and resource/license context without
silently rereading a changed upstream. Source claims remain evidence, not
authority. Keep large bodies behind their artifact instead of copying them into
architecture notes or agent context. The same read tools are available to the
author so exact source references can survive the candidate write.

## Runners

- `design`: read-only catalog-fit and architecture planning. It returns a
  native digest-bound plan and never authors package bytes. A later build
  re-inspects and replans against its exact target before any write.
- `build` (default): create or update a package after its exact staged bundle
  passes native parsing, inspection, and safe harness replay.
- `improve`: turn one receipt or harness failure into a bounded package update,
  then validate and commit the exact staged bytes.
- `harness`: add fixture files to an existing package and replay the safe native
  harness against the exact candidate before committing it.

`build`, `improve`, and `harness` write local workspace files. They never
publish, install, push, or mutate an external provider. Native harness replay
runs with isolated Runx home, receipts, and no operator credentials. Invalid
staged packages stop before the target package is touched. Design, inspection,
validation, and the bounded transactional workspace write do not add a human
approval gate; the operator authorizes those reversible local writes by
invoking a runner whose native filesystem steps request
`fs.write`/`fs.delete`. Publication, installation, provider effects, and other
consequential boundaries remain outside this skill and keep their own approval
rules.

A validated local write is not a published skill. For a shared or public
package, the validated `run.yaml` identity and the exact `target_dir` and
`package_digest` in `apply_result` form the publication candidate. When the
operator's objective includes shipping or registry availability, continue that
exact candidate through the repository's canonical registry operator: publish
under the intended existing publisher/name, then independently read back the same
version and digest. Do not call the work shipped while that sync is pending or
unverified. Publication remains a separate authenticated act so Skill Build
never receives registry credentials or hides a remote mutation inside local
authoring.

## Authoring rules

- Start from the operator's recurring job, not the requested package name,
  bounty wording, provider, or implementation sketch. Establish what becomes
  materially easier or newly possible for the operator, what judgment the
  skill contributes, and what durable result it returns. A package that merely
  restates ordinary agent behavior, renames one native call, or produces a
  document with no usable next step is not a valuable skill even when every
  contract and harness passes.
- Treat prior implementations, accepted bounty text, issue suggestions, and
  named integrations as evidence about the intended capability, not binding
  architecture. Preserve the real user outcome and compatibility obligations;
  replace stale ownership, unnecessary providers, and accidental workflow
  shapes when the current catalog has a cleaner canonical route.
- Treat `SKILL.md` as the product manual for both the human operator and the
  operating agent. A person opening it cold must understand what the capability
  does, why and when to use it, what happens end to end, and where it stops.
  Do not reduce that manual to terse model directives, field lists, or a task
  contract.
- Preserve the useful context in an existing skill: its mental model, procedure,
  examples, trade-offs, chain relationships, evidence rules, and recovery
  posture. Rewrite statements that no longer match the implementation; never
  delete the surrounding explanation merely because the executable profile now
  enforces part of it.
- A complete public skill explains, in a structure natural to the capability:
  the recurring job and outcome; when and when not to use it; the operating
  model and sequence; upstream and downstream skill relationships; meaningful
  input and output semantics; authority, approval, evidence, finality, and
  recovery; and relevant edge cases and stop conditions. Include a concrete
  example when it materially clarifies a non-obvious workflow. Do not force
  ceremonial sections onto a simple facade or internal rail.
- Put task-specific agent clauses after the human-readable operating guide.
  They sharpen individual agent acts; they do not replace the guide or carry
  the product's voice by themselves.
- Explain meaningful upstream and downstream skill relationships naturally in
  the operator guide. Do not maintain a second machine-readable dependency
  registry in `SKILL.md`: native execution-closure inspection owns the exact
  edge set and operator preflight surfaces it. Prose explains why the chain
  exists; the runtime proves what it actually calls.
- Design capability chains by responsibility, not by whichever integration is
  easiest to name:
  - The domain skill owns domain evidence, interpretation, policy, and the
    truthful domain result.
  - A canonical capability or authority skill owns a reusable decision such as
    authorizing a send, spending funds, or preparing a release.
  - A connector owns the bounded external API effect and independent
    readback.
  Do not collapse these roles into one package, and do not make a provider's
  connector a required part of a provider-neutral capability. Pin a connector
  only when the objective genuinely requires provider-specific behavior; otherwise
  return a stable handoff that an operator can route to the selected connector.
  For example, a meeting skill may produce grounded task proposals and a

From runxhq/runx, Apache-2.0.

More from runxhq/runx