Skill builder guide

Skills are reusable procedure packages. Use them for repeatable work patterns, domain-specific output contracts, local or client workflow setup, examples, templates, and company-standard operating routines.

Skills are not authority. A Skill cannot grant a tool, approve a payment, change a Charter, store a secret, or bypass a human confirmation. The Charter, signed permission manifest, and server-side tool guard remain the control plane.

When to add a Skill

Add a Skill when the procedure will be reused by more than one task or run:

• A standard operating procedure such as AP exception review, weekly sync health checks, or support triage.
• A required output contract such as named sections, evidence fields, or review checklist order.
• A local-agent setup pattern that must be installed into Codex, Claude Code, or another client.
• A reusable template, example, or evaluation fixture that helps agents produce consistent work.

Do not add a Skill for authorization, secrets, one-off task context, temporary preferences, or rules that belong in the Charter. Put durable authority, must-escalate boundaries, and tool permissions in the Charter and permission manifest.

Package shape

Every package has a SKILL.md file and may include bounded support files under references/, templates/, examples/, evals/, or scripts/. The frontmatter should define:

• application: a short summary, when to use the Skill, and when not to use it.
• required_tools: tool ids and minimum scope tiers that must exist before an approved assignment can be used safely.
• optional_tools: useful tools that produce warnings when absent but do not block assignment.

Use tool ids from tool.catalog / rost_list_tool_catalog. Required and optional tool entries are dependency declarations only; they never grant access.

Create or import

Use the shared command path from the app, CLI, or tenant-admin MCP:

• Create: skill.create / rost_create_skill with a bounded text package.
• Update a draft: skill.update_draft / rost_update_skill_draft.
• Import public GitHub: skill.import_github / rost_import_github_skill; ROST records source URL, resolved ref, path, and content hash.
• Import uploaded text: skill.import_upload / rost_import_uploaded_skill; MCP accepts structured text packages, not direct binary uploads.

Imported Skills are untrusted until parsed, scanned, validated, and reviewed. Validation warnings should be fixed before publication.

Review and publish

Publishing creates an immutable Skill version. Later edits create a new version; they do not rewrite what a prior agent run used. skill.publish is human-gated. Agent actors may draft or import, but they do not approve publication.

Review before publishing:

• The procedure is reusable and bounded.
• It contains no secrets, keys, private tokens, or raw credential material.
• Required tools are truly required; optional tools are not blockers.
• The output contract does not ask the agent to exceed the Charter.
• Support files are necessary and small enough to load safely.

Assign to a Seat

Assignment pins a published immutable version to a Seat. Run skill.check_dependencies before skill.assign_to_seat.

Dependency results mean:

• ready: required tools meet the Skill's minimum scope tiers.
• blocked: at least one required tool is missing, declined, or under-scoped. Approval is blocked.
• warning: optional tools are missing or under-scoped. Assignment can proceed, but the operator should understand the degraded path.

Fix blockers by updating the Seat's Charter permission manifest through agent.configure_tools and human sign-off. Do not edit the Skill to pretend authorization exists.

ROST catalog and local install

The ROST catalog is first-party, entitlement-filtered, and private-source-safe. Use skill.catalog to list entitled catalog Skills, then skill.enable_catalog to copy an entitled catalog Skill into the company library with human confirmation. Standard tenants do not see private beta catalog entries unless explicitly entitled.

Use skill.install_local for one Skill and skill.sync_local for all approved Skills assigned to a Seat. Local clients receive package files and .rost-skill.json metadata from ROST APIs; private catalog GitHub URLs, signed URLs, and credentials are not returned.