Skills

Skills

Skills package reusable procedures and supporting resources. Holaryn reads the open Agent Skills
SKILL.md format and preserves vendor assets. A portable file format does not guarantee that a
different host's tools, shell commands or permission model will work here. See the
Skills 2.0 implementation and compatibility record for the current scope.

What a skill is

A skill is a folder: a SKILL.md file (YAML frontmatter with the name, description, and requirements, followed by markdown instructions) plus optional scripts/, references/, and assets/ directories.

The agent uses progressive disclosure to keep its context small: sessions carry only each skill's id and description until a skill is triggered. Then the agent loads the full instructions with its skill_activate tool, reads bundled files with skill_read_reference (read-only, confined to the skill's own directory — a skill can never read outside its folder through that window), and, if the skill ships a scripts/ folder, runs its scripts through a per-skill script tool.

Where skills live

Skills are discovered from ordered roots; a later root shadows an earlier one for the same skill id (recorded as a visible diagnostic, never silently):

1. Explicit compatibility roots from HOLARYN_SKILL_COMPATIBILITY_ROOTS.
2. ~/.agents/skills/, then ~/.holaryn/skills/ (the existing installation destination).
3. .agents/skills/, then .holaryn/skills/ at each Git-checkout ancestor, from outermost to
   the current workspace. Without a detected checkout, only the current project is scanned.
4. Skills bundled inside enabled plugins, appended by runtime composition.

New project .agents skills and compatibility roots require exact content review before model
disclosure. Legacy native project skills retain their previous content eligibility. Compatibility
roots are environment-only and separated with ; on Windows or : on Linux/macOS. Discovery is
bounded; unsafe links and ambiguous duplicate names are refused with diagnostics.

Installing and managing skills

To inspect remote content without installing it, use holaryn skill source-preview URL --kind https
or a supported Git/index adapter. The source preview reference
documents exact selection, supported formats, scan findings and network limits. It never changes
installed skills or grants trust. Reviewed import/update remains under development; the legacy
installation commands below are separate and do not share those acquisition guarantees.

Use holaryn skill portability-check PATH for a bounded offline directory/archive round trip, or
holaryn skill export ID --version VERSION --sha256 DIGEST --output FILE to create a host-neutral
archive from an exact published library ref. The
interoperability contract explains the byte-preservation
evidence and live-host limits.

From the CLI:

holaryn skill list                       # discovered skills, source, trust state
holaryn skill inspect <skill-id>
holaryn skill inspect <skill-id> --json   # exact, read-only inspection report
holaryn skill explain <skill-id> --selector model
holaryn skill install <folder-or-git-url>   # confirmation prompt; --yes to skip
holaryn skill remove <skill-id>
holaryn skill enable|disable <skill-id>
holaryn skill trust|untrust <skill-id>
holaryn skill search [keywords...]       # search the curated skill index

holaryn skill search browses a curated public index of community skills and prints a ready-to-paste install command for each match; an empty query browses everything. The index location can be overridden with --index-url or HOLARYN_SKILL_INDEX_URL (an https URL, file:// URL, or local path for air-gapped mirrors). Browsing never executes anything.

In the web UI, Settings → Plugins & Skills lists installed skills (with enable/disable and trust controls) and installs new ones. Installed skills also appear as /skill:<id> slash commands so you can activate one by name from the composer.

inspect also explains disabled skills. explain previews activation without loading instructions
into a conversation or running code; reports show exact revisions, policy decisions, dependencies and
estimated prompt cost. CLI reports describe the current management inventory, not an existing chat's
profile. The authenticated chat inspection API reads that chat's captured runtime. See the
inspection contract for inputs and limits.
Changed or newly enabled skills become available in a new runtime; an existing run keeps its original
capture, and current revocations still apply.

Skills can declare path, context-kind and text hints in their sidecar. Holaryn presents matching
skills as bounded suggestions for the current turn. Suggestions do not load a procedure or grant
permissions: the model still uses skill_activate through the usual checks. An explicit slash command
does not depend on these hints. See catalog and candidates.

Trust and security

Skills carry executable code and inject instructions, so they are treated as two attack surfaces:

• Newly installed skills are untrusted by default: their scripts resolve to ask-first under the approval policy, so nothing a skill ships runs without your yes.
• holaryn skill trust <skill-id> moves a legacy skill's scripts to run-with-notification instead of ask-first; untrust reverses it. Typed entries always require their own fresh approval.
• Consequential actions a skill instructs the agent to take still pass the normal approval gate — trusting a skill does not bypass the posture.
• Trust now binds the exact source directory and every package file's digest. Changed files and
  shadowing packages cannot inherit it. Earlier path-only trust records need review again; no
  files are moved or automatically trusted during migration.
• Activation and reference reads use the package snapshot captured for the runtime. Source edits
  take effect in a new runtime. Legacy script dispatch refuses changed source. A package with a
  holaryn.skill.yaml sidecar requires governed typed execution and cannot use a legacy shortcut.

Managed publication and signed marketplace inspection use a
shared bounded security scan, including supported archives
inside the skill. Findings help review; they do not prove safety, activate a skill, or authorize
its tools and scripts. Publication errors block the operation without changing the draft.

Authoring and validation

Profiles can require approval separately for explicit and model-selected activation. A skill-policy
approval shows the exact revision and requested capabilities, without copying private task or
argument values. It approves the procedure only; subsequent tools and scripts retain their own
permission checks. Decisions stay with the current runtime and are not restored after restart.
Resuming a saved run asks again when current policy requires approval, using the original captured
skills. Denied or previously withheld content is not restored by that approval.
Reference reads can request a separate approval for the exact package path and read limit.
Legacy script-specific skill-policy ask rules still refuse. Typed entries have a separate
attended decision when their isolated adapter is enabled.
See skill policy for these boundaries.

Portable frontmatter supports full safe YAML, including multiline descriptions. Unknown metadata
is retained without granting authority. Names and descriptions follow the Agent Skills contract;
malformed YAML, duplicate keys, oversized packages, traversal and unsafe links are refused.
Existing Holaryn formats use an explicit compatibility adapter with migration warnings.

Holaryn-specific requests belong in the optional, versioned holaryn.skill.yaml sidecar. Its
schema describes typed arguments, dependencies,
entry points, resource limits, evaluation references and composition. A declaration requests a
capability; it cannot grant one. The full Skills 2.0 lifecycle and Studio are still being implemented.

Copy a legacy script into a typed package

Keep the current installed skill unchanged while preparing its replacement. Convert the selected
scripts yourself to read JSON from stdin and emit schema-valid JSON, then write a complete proposed
holaryn.skill.yaml outside the skill directory. Preview and create a separate package copy:

holaryn skill migration-preview SKILL_ID SIDECAR_FILE NEW_PARENT/SKILL_ID
holaryn skill migration-create SKILL_ID SIDECAR_FILE NEW_PARENT/SKILL_ID --preview-sha256 SHA256

Preview reports the source label and resolved-identity digest, exact content digests, and requested
environment, secret, network and capability names. It does not run a probe. Create repeats exact
validation and asks before reserving a new absent destination. Local user/project/ancestor sources,
environment-configured compatibility roots, currently enabled plugin skills and the exact active,
content-reviewed managed-library revision are supported. Switching a plugin/local shadow,
compatibility root or byte-identical managed-library version invalidates the preview. A managed
preview shows its exact reference, must remain active through copying and must use a destination
outside library storage. The original package, ask-first behavior, plugin state and digest-bound
trust remain unchanged; the copy receives no library provenance, publication, review or activation
state and is not installed, activated or trusted. Inspect and test the copy before using the normal
reviewed installation flow. See
legacy script migration.

Typed entry execution preview

Operators may opt into skill_execute by setting HOLARYN_SKILL_EXECUTION_IMAGE to a reviewed,
preinstalled Linux Docker image's immutable local sha256: ID. The setting is environment-only
and disabled by default. If a profile restricts executable tools, it must explicitly allow
skill_execute. The entry must be declared in the captured skill's sidecar and activated first.

Each execution asks for a fresh exact approval. It receives JSON input, sees only declared captured
package files, and can write only bounded disposable scratch. It receives no ambient host
environment or workspace mount. Invalid output, timeouts and output floods fail safely.
Missing isolation refuses execution without disabling ordinary content use.

This is an implementation checkpoint. Exact public hostname requests can use the environment-only
operator destination maximum and an isolated HTTPS CONNECT proxy; empty configuration still means
no network. Exact profile credential references can use fresh, expiring, one-use leases delivered
only through protected input. Delegated children inherit ceilings that can only narrow and require
new approvals and leases. Startup and shutdown reconcile verified owned containers, proxy/network
resources and staging after a host crash; they never replay a skill. The protected in-container
supervisor independently enforces the reviewed time/output limits after host loss. Full combined
network/secret-exfiltration, native Linux/macOS and live Node/direct-executable acceptance remains
pending.
There is no new public run command or execution API yet. See the
execution contract, setup requirements and limitations.

Inspect dependencies without activating a skill or running its code:

holaryn skill readiness <skill-id> <entry-name>

This uses the configured reviewed image and returns a JSON readiness report. Required missing or
unverified dependencies block execution; optional failures remain visible. Host dependencies also
appear in inspect/explain reports. Authors can mark binary/runtime/config dependencies with
scope: execution so missing image programs do not prevent safe use of the written procedure.
Reports provide operator remediation, never automatic installers or credentials. Readiness does
not grant execution permission. See dependency readiness.

The capability registry

Skills declare what they need as capability names — plain string contracts in frontmatter, not code imports. The agent's skill runtime is a capability registry: it checks whether every declared requirement is present before surfacing the skill. Core capabilities every standalone install has: fs, llm, memory, shell.

A skill that requires a capability your install does not have (for example, one provided only by a connected Holaryn Space workspace) simply does not surface in sessions — it degrades gracefully instead of erroring, and the agent never has to import Platform code to know about it. Connected services register their capabilities at runtime, at which point those skills light up.

The agent can learn skills

Use Teach / Workshop in a chat, or holaryn skill teach, to select a reusable procedure
explicitly. Observation alone never creates a proposal. The current flow accepts pasted steps
and selected UTF-8 Markdown/text files, checks ownership and license, redacts common sensitive
content, and stores a quarantined proposal.

Inspect the full sanitized sources, candidate, diff and static checks. Attended approval creates
only an inactive, unpublished, untrusted library draft. It does not activate a skill or grant
tool, execution or credential authority. Publication, trust and activation remain separate.
See the Workshop workflow for exact review and command contracts.

When state encryption is configured, Workshop content and library files use authenticated
envelopes. Existing plaintext requires an explicit migration; routing metadata and portable
exports remain visible. The UI reports storage protection before Teach is available. See
skill-state encryption. Facts and preferences belong in
memory; identity and communication style belong in Persona.

Related pages

• slash-commands.md — /skill:<id> activation from the composer
• autonomy-and-approvals.md — how skill scripts are gated
• tools-and-mcp.md — the tool layer skills build on
• settings.md — the Plugins & Skills page

Importing and updating reviewed sources

Use holaryn skill source-import URL --kind https --decision create to review source files
and create an inactive draft. Existing drafts require an explicit replace or merge decision;
local edits and prior source bytes are retained. No skill is published, activated or trusted by
this command. See reviewed source imports for exact version/base
selection, supported adapters, private review, conflicts, encrypted receipts and current limits.

Signed registry packages use --kind registry --registry-id ID --package-id ID --version VERSION;
a plugin also needs its declared --subdirectory. Registry imports
verify exact configured signing roots, retain original signed artifacts and show permission changes.
They never enable parent plugin tools, policy or schedules.