Skills System

Skills are reusable instruction documents that Anyy can load when a task needs a specific procedure. They are procedural memory: use them for "how to do this workflow", while persistent memory is for durable facts and preferences.

Anyy does not treat skills as code plugins. A skill is a SKILL.md file, plus optional supporting files, that guides the existing agent, tools, approvals, and runtime policy. Loading a skill never bypasses tool governance, ChangePlans, approval policy, audit logging, provider boundaries, or enabled toolsets.

See also:

• Skill Management for installing, removing, reloading, and disabling skills.
• Skill Authoring for writing valid SKILL.md files.
• Working with Skills for day-to-day usage.
• Tools Reference for skills_list, skill_view, and skill_manage.

How Skills Are Found

At runtime, Anyy builds one catalog from several roots:

Root	Source	Writable by managed skill operations
<home>/skills	Profile-local installed and agent-created skills	Yes
skills.external_roots[]	Extra configured directories	No; scanned as external roots
~/.agents/skills	Portable user skill root, if it exists	No; scanned as an external root
<home>/system/skills	Bundled system skills materialized by Anyy	No

Dashboard source tabs use product-level categories: System for bundled skills, User Installed for skills the user connected or installed, and Agent Created for skills created by Anyy's self-improvement flow. Disabled is an availability state shown on each skill, not a source category.

The active home defaults to /root/.anyy when no --home, ANYY_HOME, or profile selection overrides it. Normal user installs often use ~/.anyy through the selected profile or explicit --home.

If two roots contain the same skill name, the first root wins. That means a skill in <home>/skills shadows an external or system skill with the same name.

Missing or malformed roots do not stop the entire catalog from loading. The runtime keeps valid skills and reports load warnings through the skills RPC.

Using Skills

List available skills:

anyy skills list

Inside the TUI or a runtime client that exposes gateway commands, use:

/skills

View one skill:

anyy skills view my-skill
anyy skills view my-skill references/workflow.md

In a model turn, the skills toolset exposes the same read path as skills_list and skill_view. The assistant is instructed to call skill_view(name) only when the task materially matches a listed skill and the full instructions would change how it should proceed.

Dynamic Slash Commands

Every visible skill gets a synthetic slash command named after the skill:

/my-skill explain this repository's release flow

Synthetic skill commands are exposed on TUI, CLI, and API surfaces. Messaging adapters only see commands that are available for their channel surface. If a skill needs a channel command, declare it explicitly in anyy.commands and include a matching surface such as channel or weixin.

When a user invokes a dynamic skill command, Anyy loads that skill's full SKILL.md for the current turn and sends the remaining text as the user's task.

Progressive Disclosure

Skills are loaded in layers so the model does not carry every full skill body in every turn:

Level	Mechanism	What loads
Catalog	Prompt index, /skills, skills_list	Compact metadata such as name, description, scope, commands, and metadata.
Main file	/skill, anyy skills view, skill_view(name)	Full SKILL.md content and supporting file list.
Supporting file	skill_view(name, "references/file.md")	One file under the skill directory.
Command load files	anyy.commands[].load_files	Selected supporting files loaded automatically with that explicit skill command.

This keeps ordinary sessions small while still allowing a skill to carry reference material, scripts, templates, or assets.

SKILL.md Format

Every skill is a directory with a required SKILL.md:

<home>/skills/
  release-checklist/
    SKILL.md
    references/
      workflow.md
    templates/
      release-notes.md
    scripts/
      collect-status.sh
    assets/
      diagram.png

The front matter must start at the top of SKILL.md, be closed with ---, and include name and description:

---
name: release-checklist
description: Use when preparing an Anyy release checklist from repository state.
version: 1.0.0
author: Anyy Team
license: MIT
tags: [release, docs]
platforms: [linux, darwin]
anyy:
  metadata:
    category: release
  commands:
    - name: /release-checklist
      summary: Load release-checklist instructions.
      surfaces: [tui, cli, api]
      load_files:
        - references/workflow.md
---
# Release Checklist

## When To Use

Use this skill when...

## Procedure

1. Inspect repository status.
2. Build the checklist.

## Verification

Confirm...

Required validation rules:

Field	Rule
name	Lowercase letters, numbers, and hyphens; maximum 64 characters.
description	Required; maximum 1024 characters; must not contain XML-like tags.
Directory name	For managed and system skills, the directory name must equal name.
Reserved names	Skill names must not contain provider-reserved words rejected by the validator.

Supported optional fields include version, author, license, tags, platforms, top-level metadata, and the Anyy-specific anyy.metadata and anyy.commands blocks.

platforms filters the skill by Go runtime platform. Use linux, darwin, or other exact runtime.GOOS values. If omitted, the skill is visible on every platform.

Explicit Skill Commands

anyy.commands declares named commands for a skill:

Field	Required	Meaning
name	Yes	Slash command name, usually beginning with /.
summary	Yes	Description shown in command catalogs.
surfaces	No	Surfaces where the command appears. Omitted defaults to TUI and CLI.
args_schema	No	JSON-schema-like argument metadata for command clients.
load_files	No	Supporting files to load with the skill when this command is invoked.

Available surface names are tui, cli, api, channel, weixin, and cron. A command that conflicts with a built-in command is skipped.

Supporting Files

The skill viewer and manager recognize supporting files under:

Directory	Use
references/	Extra documentation and examples the assistant can load on demand.
templates/	Output templates or reusable snippets.
scripts/	Helper scripts the assistant may run through normal tools if policy allows.
assets/	Images, fixtures, or other supplementary files.

Supporting paths must be relative, use forward slashes, and stay inside the skill directory. Symlinks and non-regular files are ignored or rejected.

Configuration

Skills runtime configuration lives under skills in config.yaml:

skills:
  external_roots:
    - ~/.agents/skills
    - ${TEAM_SKILLS_ROOT}
  disabled:
    - skill_user_abc123
  disabled_by_surface:
    tui:
      - experimental-skill
    api:
      - /internal-command

Field	Meaning
external_roots	Additional directories scanned after <home>/skills and before system skills. Supports ~, $VAR, and ${VAR} expansion. Missing environment variables cause that root to be skipped.
disabled	Global hidden list. Entries may be a skill ID, skill name, or skill command name.
disabled_by_surface	Per-surface hidden list using the same entry forms as disabled.

The gateway can also toggle a non-system skill by exact skill ID through the skills.toggle RPC. That writes skills.disabled and reloads the catalog for the active scope.

Safety Model

Skill reads are low-risk runtime reads. Skill mutations are high-risk configuration changes and are audited as skill changes.

Managed installs and agent writes include guardrails:

• HTTPS skill URLs must use https, must not contain credentials, and must not target private or internal network hosts.
• A single remote SKILL.md URL requires --name and must be self-contained.
• GitHub installs fetch committed files through the GitHub API, reject symlinks and unsupported tree entries, limit file counts and bytes, scan the staged directory, and record provenance in <home>/skills/.manifest.json.
• Dangerous scan findings block install. Caution findings require --force.
• Managed edits refuse symlinked skills and only write SKILL.md or files under references/, templates/, scripts/, or assets/.

Skills can tell the assistant what to do, but they do not grant new tool access. The active toolsets, tool governance, approval policies, and provider/runtime boundaries still decide what can actually run.