Skill Lab

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

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-lab runner so the work is bounded and receipted.

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 X.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 owner/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 Lab 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 provider adapter owns the bounded external API effect and independent readback. Do not collapse these roles into one package, and do not make a provider adapter a required part of a provider-neutral capability. Pin an adapter only when the objective genuinely requires provider-specific behavior; otherwise return a stable handoff that an operator can route to the selected adapter. For example, a meeting skill may produce grounded task proposals and a follow-up message; communication then goes through send-as, while task creation goes through the operator's selected task adapter. n8n, Zapier, or any other automation provider is optional unless the requested capability is explicitly about that provider.
• Search the catalog by operator outcome and authority owner, not only by words present in the request. Consider every material result independently: a workflow may need different next lanes for a message, task proposal, payment, publication, or unresolved ambiguity. Reuse the canonical capability at each boundary and explain why it owns that decision. Do not hide an unhandled outcome behind a generic "handoff" claim.
• Preserve the context that makes the next operator or skill intelligent. Handoffs carry the bounded evidence, decision rationale, unresolved ambiguity, stable content or proposal, intended audience or target, and effect status needed by the next lane. Do not squash these into a digest, terse status, or provider payload. Digests bind context; they do not replace it. Conversely, do not forward unrelated source material or secrets.
• Make finality explicit at every boundary. Distinguish observed evidence, model interpretation, draft, proposal, authorized action, attempted effect, provider-confirmed effect, and independently read-back effect. A downstream route is not proof it ran; a sealed plan is not approval; an adapter request is not delivery. The public result and operator guide must say what actually happened and what still has to happen.
• A skill declares domain procedure and policy. Runx owns generic input, packet, evidence, approval, request, credential, effect, and receipt mechanics.
• Place the capability in its real owner before choosing an implementation. Reusable skills, end-user and domain-operator commands and UX, local host loops, local queues, and default local-state orchestration belong in Runx OSS or the owning product repository. runx/cloud is not precedent for those concerns: it may provide the hosted control plane, custody provider credentials, resolve authoritative grants, and execute a fixed bounded provider operation. Using Hosted Connect does not move the surrounding skill, procedure, operator decision, or state into Cloud. If that operator surface is missing, return work to OSS or the product owner; never extend a Cloud script or hosted service as a substitute.
• For hosted provider work, compose native provider.read or provider.mutate; declare exact scopes and provider operations, and require provider readback. A scoped provider grant is sufficient by default. When an act genuinely needs a human decision, put one typed approval request in the provider.mutate inputs with a concrete reason and action-specific type. The native provider effect constructs the exact operator summary, binds the request to the plan, and suspends for runx resume; never add an adjacent graph approval for the same action. Use an explicit graph approval only for a consequential decision no native capability owns. One action has one approval owner. Payment effects must also provide the typed amount: {units, unit} input so the exact amount is visible and plan-bound; do not bury it only inside provider-specific payload JSON. Use expected_result to bind the returned resource identity and result_fields to admit only the fields the receipt needs. Secret-adjacent operations must project their result. Pass retry identity through the native idempotency_key input; do not copy it into the provider payload. Never add a package token loader or request client.
• Never model human authority as a caller-supplied approval string, boolean, or reference. A native approval gate must summarize the exact target and effect; its host-attested packet is the only approval input a credentialed provider tool may accept. If a provider API requires its own approval reference, derive the claim- or resource-bound value inside that tool after verifying approved: true, actor: human, the exact gate id, and the action-specific gate type. An agent-authored answers value must fail before provider execution.
• run: approval is a human gate. Agent provenance is rejected by the runtime; use agent-task for model judgment and keep its result distinct from human authority.
• Treat the selected runner's typed execution requirements as the complete permission request. Put opaque scope strings, exact non-secret environment names, the named credential requirement, and runtime metadata on their canonical runner or source fields—never under runx, in prose, or in a package loader. Runx resolves and records those declarations without inventing a scope vocabulary; the native capability or provider that owns a scope enforces it.
• Make every public runner contract recursively complete at the authoring boundary. X.yaml owns nested properties, closed objects, enums, bounds, and complete parser-validated invocation examples; runx skill inspect, MCP, agent tools, and generated exports must project that same declaration. When an identical input declaration is used by multiple runners, define it once with the manifest's exact input-definition reference rather than copy it or invent merge overrides. JavaScript may enforce irreducible relationships between otherwise valid fields, but must not repeat structural validation already owned by the profile.
• Dogfood the result through the real agent-facing surface, not only the package harness. A cold agent must be able to inspect the selected runner, construct a valid call without reading source or fixtures, understand a path-specific rejection, and continue from the resulting context. Exercise every materially different runner; a default-only export cannot certify a multi-runner skill. For an existing target, use authoring_context.target_inspection as the canonical runner-contract and execution-closure evidence. An invalid inspection is repair context, not permission to guess: read the declared target files, correct the owning contract, and validate the complete candidate.
• Design evidence admission around the operator's job, not the first provider implementation. When analysis is useful over local admitted files or artifacts as well as remote sources, support both through their canonical evidence boundaries; do not require HTTPS, Hosted Connect, or another provider merely to analyze evidence already available on the operator's machine. Provider-specific acquisition remains a separate runner or upstream skill when it adds real readback value.
• Make permission claims executable through the existing package harness. Permission-bearing native and provider paths need a realistic admitted case and, where the harness can exercise that owner, a refusal case with the required scope or grant withheld. The harness must call the same catalog, dispatcher, and capability/provider implementation as a real run; never add a mock permission evaluator, scope vocabulary, or parallel verification report. This proves enforcement owned by Runx capabilities and providers. It cannot prove that trusted host code avoided undeclared filesystem, network, or syscall access, so report that boundary as trusted rather than confined.
• Tool fixtures inherit the exact scopes declared by the canonically resolved manifest and pass declared packets through the production packet verifier. Use expect.output.matches_packet only when the whole fixture output is one self-described packet; named artifact packets are already verified from the manifest and should not be asserted through a second fixture path.
• Search the inspected native-tool and skill catalogs before designing files. Prefer an existing core tool or canonical skill over executable package code.
• Make every public runner input constructible from inspection. Use ordinary schema for runner-owned nested values. When an input is exactly one canonical Runx packet, declare type: json plus packet: <packet-id> and let the runtime resolve the catalog-owned schema into inspection, validation, exports, registry bundles, and harnesses. Never copy that packet schema into the consumer. If the canonical schema is too weak to make the input usable, improve the producing packet contract first; a packet reference is not a substitute for a complete schema. Do not mint a packet id for a runner-local nested value, graph intermediate, or one-run implementation detail. A packet exists only for the complete value crossing a named reusable skill, runtime, SDK, provider, receipt, or registry boundary, and it must have one active producer and consumer or an explicit public native owner. Remove the generated artifact when that ownership disappears. Every public runner still needs at least one realistic, copy-valid example unless its inputs are empty.
• A named packet must expose its semantic fields or reference a canonical typed contract. Bare type: object, unconstrained {}, and opaque property bags do not make a runner inspectable and must be repaired at the producing contract, not documented around in prose. Open JSON is admissible only as an explicitly named protocol extension or generic data payload inside an otherwise bounded semantic envelope.
• Apply that rule recursively. Every nested type: object declares meaningful properties or an explicit additionalProperties policy. If the value is intentionally arbitrary JSON, declare type: json; do not make an object declaration imply structure that the contract does not provide.
• Put a producer's nested output shape in that output declaration's schema. Do not hand-maintain the same shape in a packet file, fixture, exporter, or consumer: native parsing, agent context, runtime validation, packet generation, registry packaging, and harness replay all consume the producer's declaration.
• Express orchestration through X.yaml; keep all static agent operating knowledge and task contracts in SKILL.md. Never put model instructions in manifests, fixtures, or duplicated prompt fragments.
• Declare every harness-only support file explicitly in harness.files using a normalized profile-relative path under fixtures/. Runx stages only those declared files into the isolated harness workspace; it never guesses dependencies from arbitrary input strings. Do not turn the declaration into a second source tree or include unconsumed helpers.
• Put every typed output and packet contract on the step that actually produces it. A graph runner is composition and its receipt proves that composition; it must not declare a second runner-level outputs or artifacts contract with ambiguous ownership. Every graph runner declares graph.result_from as the intentional public result boundary. Name the final provider readback or package/finalize step, not every leaf: approvals, evidence gathering, and intermediate writes remain available in operator context and receipts without polluting the result. Multiple producers are valid only for mutually exclusive branches or when their distinct contracts are intentionally returned together; simultaneous producers may not emit the same key. When a graph needs one public result, end it with an explicit package/finalize step and let that producer own the packet schema.
• Add executable code only for irreducible deterministic domain computation. Explain its domain boundary and why native tools plus a declarative graph cannot express it. Do not add code merely to transform Runx contracts.
• For a genuinely separate CLI or protocol tool, keep one canonical manifest.json. It owns source, inputs and defaults, artifact projection, scopes and retry/idempotency. Effect and approval stay with the capability that invokes the tool; never duplicate them in this manifest. Never persist generated runtime, output, runx, hash, or toolkit fields beside that contract. runx tool build validates and reports derived hashes without rewriting the package. The extension SDK may carry the already-materialized JSON request and response across a process boundary; it must not become a second manifest or input-contract owner. The declared entrypoint must execute on the repository's supported runtime without probing for generated files or importing uncompiled TypeScript. A bundled tool lives at tools/<namespace>/<name>/manifest.json, its dotted manifest name must match that path, and aggregate package admission must bind every static local source dependency before the package can run or publish.
• Local CLI tools, process MCP servers, and process adapters are trusted host code. Runx controls their exact invocation, delivered environment and credentials, lifecycle, bounded output, and evidence; it does not turn declared scopes into portable filesystem, network, or syscall confinement. Use this lane only when the operation is genuinely irreducible to native capabilities, provider adapters, declarative composition, or deterministic JavaScript. Never author a sandbox declaration, wrapper, or fallback flag.
• When that computation is JavaScript, use the native type: javascript source. Prefer one cohesive module named for the skill with focused named exports of the form (inputs, context) => JSON; split it only when the computations have genuinely separate ownership. Runx owns input delivery, output serialization, errors, wall limits, and isolation. Do not add fake operation inputs, Node command declarations, per-runner wrapper files, or stdout/environment plumbing. Pure JavaScript receives only its validated in-memory module bundle, JSON input, and a frozen context.environment object containing the exact names declared in the runner's environment.required and environment.optional lists. A missing required name stops before worker execution; an absent optional name is omitted. Values never enter the manifest, agent context, inspection output, or receipts. Environment declarations are for non-secret runtime configuration; credentials stay on the native credential/provider boundary. The worker process itself has an empty ambient environment and no workspace path, filesystem, network, clock, randomness, subprocess, credential, or provider surface. The default wall limit is two seconds; a runner may declare timeout_seconds from 1 through 30 when irreducible computation genuinely needs it. The worker is ECMAScript, not a browser: use the frozen Runx.parseUrl(value) helper for absolute URLs and do not assume Web or Node globals exist.
• Classify volume before authoring. Small typed control values belong in normal runner inputs; runx skill --inputs is only a bounded transport for one complete control object. Large immutable local content belongs behind artifact.admit/bounded pages. Durable history belongs behind data.read_events cursors or a compact projection. A graph must not carry an archive, growing event history, or completed-id array simply because one CLI call can parse it.
• Use deterministic pages only for irreducible record transforms over one admitted JSON-array artifact. The runtime owns artifact admission, page framing, snapshot digest, record boundaries, offsets, retries, and the page loop; the module owns only decoding and domain selection. Treat runx_page.artifact_ref as an opaque, runtime-local read capability that belongs in receipt provenance; never place it in a plan or idempotency digest. Bind deterministic domain output to runx_page.whole_digest, which is stable for identical content. Keep continuation state proportional to the bounded result. Do not add a package file reader, manual byte cursor, hashing loop, high-volume profile, or raised worker limit. If safe framing or bounded state is impossible, choose needs_core or a genuinely separate protocol tool rather than smuggling filesystem authority into JavaScript.
• Prove a volume path at two materially different scales through the production owner. The result must be identical across page sizes, cursors must advance, process count must stay stable where session reuse applies, and failures must remain distinguishable from empty pages. A larger fixture alone is not performance evidence.
• A missing generic primitive is not permission for package code. Return needs_core with no writes and identify either a runtime/security invariant or two independent existing consumers.
• Never add package-local raw RUNX_INPUTS_* parsing, generic packet or evidence hashing, packet wrapping, generic status construction, or provider simulation when a shared Runx boundary can own it. Package code may retain a canonical hash only when that hash is an intrinsic field of an established domain or wire protocol, not as a substitute for receipt or effect integrity. State that exception at the computation boundary.
• Keep packages concise: normally SKILL.md, X.yaml, and focused fixtures; add narrowly scoped references, assets, tools, or domain code only when consumed.
• Judge the whole capability, not proxy metrics. Native reuse, fewer files, shorter code, green harnesses, and low resource ceilings are valuable only when the result remains understandable, useful, truthful, and complete. Keep JavaScript when it performs irreducible domain com