You are reading Nightly documentation for 0.12.4.dev0+g50bde75.

This documentation may describe behavior that differs from Stable.

Open Stable documentation

Documentation version

0.12.4.dev0+g50bde75 · Nightly
Stable Beta Nightly

Skills

Skills

Skills are the agent's packaged, reusable competencies. Holaryn Agent is a host for the open agentskills.io SKILL.md standard, so it is instantly compatible with the existing skill ecosystem — any skill folder that works in other SKILL.md hosts works here, and skills you write for Holaryn stay portable.

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. ~/.holaryn/skills/ — your user-wide skills (where holaryn skill install puts them)
  2. ./.holaryn/skills/ — project-local skills
  3. Skills bundled inside installed plugins

Installing and managing skills

From the CLI:

holaryn skill list                       # discovered skills, source, trust state
holaryn skill inspect <skill-id>
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.

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 skill's scripts to run-with-notification instead of ask-first; untrust reverses it.
  • Consequential actions a skill instructs the agent to take still pass the normal approval gate — trusting a skill does not bypass the posture.

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

The self-improvement loop lets the agent synthesize and refine skills from its own experience — conservatively and always with you in charge:

  1. A repetition analyzer watches for procedures the agent has performed several times across sessions.
  2. When a pattern repeats enough, the agent drafts a skill — but the draft lands in quarantine as a proposal, never in the active skill roots. Proposals are inert: nothing about them can run.
  3. You review proposals in Settings → Plugins & Skills, under Proposals: each shows the drafted SKILL.md, any scripts, its provenance (which sessions and objectives it came from), and a diff when it refines an existing skill.
  4. Approving a proposal is itself an approval-gated, irreversible action; only then is the skill promoted into the active root. Rejecting it records the rejection.

The same loop also deepens the agent's model of recurring entities (people, projects, systems) in memory.

← Previous Settings Next → Slash commands