> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/talus-docs-v2.1.0/guides/agent-usage/register-skill-package.md). # Register a Skill Package {% hint style="info" %} **Audience:** Nexus adopters and integrators. **Goal:** Register a Talus Agent Package (TAP) skill package and verify the Agent-to-DAG binding, authority, and durable revision that execution will use. {% endhint %} Publication and registration are separate boundaries. A TAP publication may publish a Move package and DAG and produce a *publish artifact*; a registry-only path may create the artifact from an already published DAG. Neither path creates a `SkillRecord`. The Skill becomes discoverable only after `nexus tap bind` or `nexus tap register-skill` succeeds. This guide begins with the artifact produced by [Define an Agent Package](/talus-docs-v2.1.0/guides/agent-usage/build-agent-package.md) or the TAP publication guides and performs that registration boundary. ### Prerequisites * A Bash/POSIX-compatible shell plus `jq`, `curl`, and coreutils-compatible `sha256sum`, `stat`, and `mktemp` for the documented checks. Node.js 18 or later is needed only for the hosted Nexus API tutorial or its React example. * Verify the shell tools with the [Developer Setup](/talus-docs-v2.1.0/guides/getting-started/setup.md) check before using the commands below. * A validated skill config — run `nexus tap validate-skill --config …` first (see [Define an agent package](/talus-docs-v2.1.0/guides/agent-usage/build-agent-package.md)). * Complete [Developer Setup's protected-signer gate](/talus-docs-v2.1.0/guides/getting-started/setup.md) before this mutation path. Without provider-approved protected import and `nexus conf set --help` verification, stop at query-only SDK/Explorer/API inspection and do not run publishing or registration commands. * After that gate is complete, use a configured Nexus environment (`nexus conf`) and signer SUI address balance verified with `nexus gas balance` and funded with `nexus gas deposit` for publishing and registration. Use an owned gas coin only for an explicit gas-coin flag; use AgentPaymentVault only when the skill is agent-funded. * Every fixed tool referenced by the config already registered (see [Build an off-chain tool](/talus-docs-v2.1.0/guides/tool-development/build-offchain-tool.md) or [Build an on-chain tool](/talus-docs-v2.1.0/guides/tool-development/build-onchain-tool.md)). #### What "publish" and "register" mean Two on-chain surfaces are involved: * **The tool registry** indexes each shared Tool record by FQN and Tool ID. Your skill's fixed-tool FQNs must already be registered here, while the Tool owner capabilities remain separately transferred custody. * **The agent registry** holds agents and their skills. Registering a skill writes a `SkillRequirement` — payment policy, schedule policy, fixed tools, input commitment — against an agent and allocates the skill a monotonically increasing *skill id* local to that agent. Publishing is the step that publishes the DAG and packages the config plus the fetched DAG data into a *publish artifact* — a self-contained JSON that the register step consumes. Every skill also carries an *interface revision* so that a later `update-skill` can supersede an earlier registration without breaking callers who pinned the old revision. The artifact is the user-facing package of the skill contract: DAG binding, interface revision, payment policy, schedule policy, input commitment, and fixed-tool requirements. On-chain, `SkillRequirement` stores those requirements, and registration checks each fixed-tool FQN against the ToolRegistry; it does not by itself prove the stored registry ID or DAG membership matches, so read back the requirement, selected DAG vertices, Tool IDs, and schemas before relying on the dependency.
Create an owned Agent record from inspected inputs

Phase 1: Create an owned Agent identity. Keyed fact: create-agent writes the Agent identity to AgentRegistry; published DAG ID binding enters the independent Skill artifact phase.

Assemble payment, fixed Tool, and Skill artifact inputs

Phase 2: Assemble payment, fixed Tool, and Skill artifact inputs.

Register the artifact and persist its SkillRecord

Phase 3: Register the artifact and persist its SkillRecord.

The first figure shows the owned-agent registration data that becomes the skill contract: a published DAG, payment and schedule policies, and fixed-tool requirements are serialized into one artifact. The next figure shows the separate CLI transaction sequence that creates the Agent, writes the artifact, and stores the resulting `SkillRecord`. ```mermaid %% Declares the registration sequence; see `nexus_registry::agent_registry` for the Move entry points. sequenceDiagram %% `User` is the builder running the Nexus CLI commands. participant User %% `CLI` serializes artifacts and submits Sui transactions. participant CLI as Nexus CLI %% `Registry` is the onchain AgentRegistry shared object. participant Registry as AgentRegistry %% The user first creates an owned agent. User->>CLI: create-agent %% The CLI calls the registry function that creates and records the agent. CLI->>Registry: create_agent %% The user then creates a local artifact bound to a DAG and requirements. User->>CLI: create-skill-artifact %% The CLI writes artifact JSON back to the user or output path. CLI-->>User: artifact JSON %% The user registers that artifact against the created agent ID. User->>CLI: register-skill --artifact --agent-id %% The CLI calls the registry registration path, with fixed tools when present. CLI->>Registry: register_skill with fixed_tools vector %% The registry returns the numeric skill ID used by execution commands. Registry-->>User: skill_id ``` #### Step 1 — Publish the skill Publish the TAP package, its DAG, and the publish artifact in one step: ```bash nexus tap publish-skill --config ./skill.tap.json --out ./artifact.json ``` This publishes the DAG to the active network, then writes the publish artifact to the path you give with `--out`. Keep the artifact — the register step reads it. If you need finer control (for example, to build an artifact from an already-published DAG), assemble it explicitly instead: ```bash nexus tap create-skill-artifact \ --skill-name portfolio-rebalance \ --dag-id \ --interface-revision 1 \ --payment-mode agent-funded \ --agent-funded-max-budget-mist \ --fixed-tool = \ --out ./artifact.json ``` The `--payment-mode` is `user-funded` or `agent-funded`; supply `--agent-funded-max-budget-mist` only for the agent-funded case. Repeat `--fixed-tool` once per pinned tool; the artifact retains the supplied registry ID and FQN, while the pinned on-chain check requires the FQN to be registered at transaction time and the client/operator must verify the ID and DAG vertex separately. `--recurrence-kind`, `--min-interval-ms`, and `--max-occurrences` set the schedule policy (defaulting to a single `once` run). #### Step 2 — Register the skill against an agent You have two paths, matching the ones in [Define an agent package](/talus-docs-v2.1.0/guides/agent-usage/build-agent-package.md): * **New agent, first skill, atomically:** ```bash nexus tap bind --artifact ./artifact.json ``` This creates a Talus agent and registers the skill from the artifact in a single transaction. Note the returned agent id and skill id. * **Existing agent, additional skill:** ```bash nexus tap create-agent # once, if the agent does not exist yet nexus tap register-skill --artifact ./artifact.json --agent-id ``` `register-skill` attaches the skill to an existing agent and allocates the next skill id. Embedded-agent packages use the same agent registry semantics but keep the `Agent` inside their own package state and attach it to the registry from package code rather than through the sender-owned `create-agent` flow. On-chain, `agent_registry::create_agent` creates the `nexus_interface::agent::Agent`, binds it to the registry, and stores the registry-side agent record. The demo TAP package uses `agent_registry::attach_embedded_agent` when an example keeps the `Agent` inside its own state object. For scripts that keep the two operations separate: ```bash nexus tap create-agent --json --sui-gas-budget "$SUM_DEMO_GAS_BUDGET" nexus tap register-skill --json --artifact "$artifact_path" --agent-id "$agent_id" ``` #### Step 3 — Confirm the registration Read the registered skill's live requirements back from the agent registry: ```bash nexus tap requirements --agent-id --skill-id ``` This fetches the on-chain `SkillRequirement` — payment policy, schedule policy, and fixed tools — so you can confirm it matches your config. Inspect the whole agent registry as JSON with: ```bash nexus tap registry show ``` Use this check before execution and scheduling. `update-skill` changes the active skill contract and bumps the revision; callers should know which `(agent_id, skill_id, revision)` they are targeting. For multi-skill demos, inspect each returned skill ID explicitly: ```bash nexus tap requirements --json --agent-id "$agent_id" --skill-id "$skill_1_id" nexus tap requirements --json --agent-id "$agent_id" --skill-id "$skill_2_id" ``` #### Step 4 — Update a skill (later) When you change the DAG or a policy, build a new artifact and update the existing skill in place, bumping the interface revision: ```bash nexus tap update-skill --artifact ./artifact.json --agent-id --skill-id ``` An update replaces the active registry contract and increments the interface revision; it is not blocked solely because an older Task is still open. Existing durable Task or Execution records retain the revision copied into their historical evidence. The registry classifies each immutable Task snapshot as `Current`, `Inactive`, `Stale`, or `Missing`: deactivating a matching contract makes direct admission abort with no durable rejection or Execution, and reactivation of that unchanged contract permits retry; advancing a revision, pinned DAG, or policy produces `Stale`, while removing the Agent or skill record produces `Missing`. `Stale` and `Missing` are permanent for that snapshot, and the explicit rejection path can record `StaleSkillContract`; close an idle Task and create a new Task when work must adopt the new contract, because `Missing` cannot be repaired by reactivation. Record the targeted `(agent_id, skill_id, revision)` rather than assuming an open Task follows the update. This is different from separately registered Tool FQNs such as `@1` and `@2`. #### Step 5 — Fund the vault for agent-funded skills If the skill is agent-funded, deposit into the agent vault before anyone executes it: ```bash nexus tap vault deposit --agent-id --amount nexus tap vault balance --agent-id ``` A user-funded skill needs no vault — the submitting signer supplies the address-funded Task reserve when creating the Task, and the configured `refund_recipient` remains the address-funded return destination. #### Verification checklist Your skill is registered and executable when: * `nexus tap publish-skill …` wrote a publish artifact and published the DAG; * `nexus tap bind …` or `nexus tap register-skill …` returned an agent id and skill id; * `nexus tap requirements --agent-id … --skill-id …` shows the expected payment policy, schedule policy, and fixed tools; * if agent-funded, `nexus tap vault balance …` shows a balance covering the skill's max budget. #### Common failure modes | Symptom | Likely cause and fix | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Publish fails validating the config | The config did not pass `validate-skill`. Fix it (see [Define an agent package](/talus-docs-v2.1.0/guides/agent-usage/build-agent-package.md)) and re-publish. | | Register fails on a fixed tool | The fixed-tool FQN is not registered. Confirm the FQN, registry ID, selected DAG vertex, and immutable schema with `nexus tool inspect --tool-fqn …` and the DAG/requirements readbacks; the registration check itself is FQN-only. | | Wrong skill id | Skill ids are agent-local and allocated in order. Re-read them with `nexus tap registry show` or `nexus tap requirements`. | | Update rejected | The `--skill-id` does not exist on that agent, or the interface revision did not advance. Re-check the artifact's interface revision. | | Agent-funded execution later fails | The vault balance is below the skill's max budget. Top it up with `nexus tap vault deposit`. | #### Next guides * [Execute and settle an agent](/talus-docs-v2.1.0/guides/agent-usage/execute-and-settle-agent.md) — run the registered skill end-to-end and settle payment. * [Schedule an asset-management flow](/talus-docs-v2.1.0/guides/agent-usage/schedule-asset-management-flow.md) — automate recurring runs of this skill. * [Authorization and fixed Tools](/talus-docs-v2.1.0/concepts/09-authorization-and-fixed-tools.md) — understand the grant and fixed-Tool contract for an agent skill. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.talus.network/talus-docs-v2.1.0/guides/agent-usage/register-skill-package.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.