Work With Skills

Skills are reusable procedures that Anyy can load for one task: release checklists, project workflows, troubleshooting playbooks, writing conventions, or tool-specific recipes.

For the full reference, see Skills System. For installation and lifecycle details, see Skill Management.

When To Use A Skill

Use a skill when the work is repeatable and procedural:

• a checklist you run more than once,
• a project-specific release or deploy flow,
• a troubleshooting playbook,
• a writing or review convention,
• a tool recipe with several steps.

Do not use a skill for one-off facts, secrets, temporary TODOs, or raw research links. Put durable facts in memory, keep temporary progress in the session, and store files/artifacts when the user explicitly wants material saved.

Find Skills

List the current catalog:

anyy skills list

Inside the TUI or another runtime client that exposes gateway commands:

/skills

The catalog includes skills from the active home, configured external roots, the portable ~/.agents/skills root if present, and Anyy's system skills. If a skill is missing, first confirm that you are using the expected home:

anyy skills list --home ~/.anyy

View A Skill Before Using It

Open the main instructions:

anyy skills view release-checklist

Open a supporting file when the main skill points to one:

anyy skills view release-checklist references/workflow.md

From a session:

/skill release-checklist

Supporting paths must be relative, use forward slashes, stay inside the skill directory, and point to regular files.

Use A Skill

For visible skills on TUI, CLI, and API surfaces, the simplest path is the synthetic slash command:

/release-checklist review the current repository state

You can also ask naturally:

Use the release-checklist skill to prepare this repository for a docs release.

Anyy gives the model a compact skill index by default. The assistant loads a full skill with skill_view only when it is relevant, then follows the skill under the same tool, approval, audit, and ChangePlan rules as any other turn.

Messaging adapters only expose skill commands that are available for that channel surface. A skill does not automatically become a messaging command just because it exists on disk.

Install A Local Skill

Use a local directory when you are developing or reviewing a skill yourself:

anyy skills install ./release-checklist
anyy skills view release-checklist

The directory must contain a valid SKILL.md. For managed skills, the directory name must match the name field.

If the gateway is already running and you want the new skill available immediately:

anyy skills install --now ./release-checklist

Without --now, the files are installed immediately, but the running gateway keeps its current catalog until reload or restart.

Install From GitHub

Install one skill directory:

anyy skills install github:owner/repo/path@main

Install every candidate skill in a repository only when you intentionally want the whole collection:

anyy skills install --all github:owner/repo
anyy skills install github:owner/repo/*

Use --force only when you intentionally want to replace a skill with the same name:

anyy skills install --force github:owner/repo/path@main

Anyy fetches committed files through the GitHub API, records the ref and commit SHA in the managed manifest, and scans staged content before committing the install. It does not execute third-party setup scripts during managed install.

Install A Single SKILL.md URL

A public HTTPS SKILL.md can be installed when it is self-contained:

anyy skills install --name release-checklist https://example.com/SKILL.md

Use a directory or GitHub source instead when the skill depends on reference files, templates, scripts, or assets. A single-file URL cannot bring those files with it.

Add A Shared Skill Root

If you maintain skills in a shared directory, add it to config.yaml:

skills:
  external_roots:
    - ~/.agents/skills
    - ${TEAM_SKILLS_ROOT}

Then reload the running gateway:

anyy skills reload

External roots are scanned after <home>/skills, so local managed skills shadow shared skills with the same name.

Create A Small Skill

Create a directory:

mkdir -p ~/.anyy/skills/release-checklist

Write ~/.anyy/skills/release-checklist/SKILL.md:

---
name: release-checklist
description: Use when preparing a release checklist from repository state.
version: 1.0.0
tags: [release, checklist]
anyy:
  metadata:
    category: release
---
# Release Checklist

## When To Use

Use this skill when the user asks to prepare, verify, or review a release
checklist.

## Procedure

1. Inspect repository status.
2. Run the required verification commands.
3. Report blockers before drafting the checklist.

## Verification

Confirm the answer names the commands that were run and their results.

If the gateway is running, reload it. Otherwise, start a new session so the catalog is built from disk:

anyy skills reload

/release-checklist review this docs branch

For more structure, move detailed notes into references/ and mention when the assistant should load them.

Keep Skills Healthy

A good skill says:

• when to use it,
• what steps to follow,
• what not to invent,
• which supporting files to load,
• how to verify the result.

When a skill becomes stale, patch the skill instead of adding a second near duplicate. If you ask Anyy to update a managed skill during a session, the skill_manage tool can patch or edit managed skill files and reload the catalog when requested.

Skills do not grant tool access. If a skill tells the assistant to run a command but the relevant toolset is disabled or policy requires approval, the normal runtime rules still apply.

Troubleshooting

Problem	Check
Skill is not listed	Active --home or profile, missing root, malformed front matter, skills.disabled, platforms, duplicate name shadowing.
Slash command does not appear	Command surface, built-in command conflict, or the skill is not visible for that surface.
Installed skill is not active in a running gateway	Run anyy skills reload, restart the gateway, or install/uninstall with --now.
Supporting file cannot be opened	Path must be relative, use forward slashes, stay inside the skill directory, and point to a regular file.
GitHub install is blocked	Review scan findings, file count/size limits, symlinks, path escapes, or unsupported repository layout.
Single URL install fails	Add --name, use HTTPS, and make sure SKILL.md is self-contained.