Skill Authoring

Skills are the lightest way to teach Anyy a reusable workflow. Write a skill when the capability can be expressed as instructions, examples, existing tools, and optional helper files. Write a tool only when you need new runtime code, a custom API integration, streaming behavior, or a new approval boundary.

This page is for authoring skill files. For installation and runtime operations, see Skill Management.

Directory Structure

A managed skill is one directory whose basename matches the name in SKILL.md:

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

Anyy recognizes four supporting directories:

Directory	Use
references/	Additional docs, examples, API notes, and longer procedures.
templates/	Output templates or reusable text snippets.
scripts/	Helper scripts the assistant can run through normal tool policy.
assets/	Images, fixtures, or other supplementary files.

Other files may exist, but skill_view and managed file writes expose only SKILL.md and files under those four directories.

Front Matter

SKILL.md must begin with YAML front matter:

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

Required fields:

Field	Rule
name	Lowercase letters, numbers, and hyphens; maximum 64 characters.
description	Required; maximum 1024 characters; must not contain XML-like tags.

Important optional fields:

Field	Stored as
version	Skill version.
author, license	Skill metadata.
tags	Metadata tags.
platforms	Platform filter matched against Go runtime.GOOS, such as linux or darwin.
metadata	Generic metadata nested under metadata.
anyy.metadata	Anyy-specific metadata copied into the skill metadata map.
anyy.commands	Explicit slash command descriptors for the skill.

Do not put Anyy-specific fields under a nested metadata.anyy block. Anyy reads its namespace from the top-level anyy block.

Writing Instructions

A useful SKILL.md should make the activation conditions and operating procedure obvious to the assistant:

# Release Checklist

## When To Use

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

## Procedure

1. Inspect repository status and recent commits.
2. Run the documented verification commands.
3. Summarize release blockers before drafting the checklist.

## Pitfalls

- Do not invent release artifacts that are not present in the repository.
- Do not skip verification failures; include them as blockers.

## Verification

Confirm the checklist names the commands that were run and the exact result of
each command.

Keep the main file focused on the common path. Move long reference material, examples, and generated templates into supporting files, then tell the assistant when to load them with skill_view(name, "references/file.md").

Explicit Commands

Every visible skill already gets a synthetic /skill-name command on TUI, CLI, and API surfaces. Use anyy.commands when you need a different command name, a channel-visible command, argument metadata, or automatic supporting files:

anyy:
  commands:
    - name: /release-plan
      summary: Build a release plan from repository status.
      surfaces: [tui, cli, api, channel]
      load_files:
        - references/release-policy.md

Rules:

• name and summary are required.
• Omitted surfaces default to tui and cli.
• A command name that conflicts with a built-in command is skipped.
• load_files must point to supporting files inside the skill directory.

Supporting Files

Reference supporting files from the main instructions:

For the full release policy, load `references/release-policy.md` with
`skill_view("release-checklist", "references/release-policy.md")`.

Anyy normalizes supporting paths and rejects path escapes, absolute paths, and backslash-separated paths. Symlinks are ignored in listings and rejected for managed writes.

For agent-managed writes:

• patch may update SKILL.md or a supporting file.
• write_file and remove_file may update only references/, templates/, scripts/, or assets/.
• Full SKILL.md content for create and edit is capped at 100,000 bytes.
• Supporting file writes are capped at 1 MiB.

Platform Filters

Use platforms only when the skill truly depends on an operating system:

platforms: [darwin]

The filter compares against Go's runtime.GOOS, not marketing names. For macOS, use darwin; for Linux, use linux; for Windows, use windows. A skill without platforms is visible everywhere.

Authoring Checklist

Before installing or committing a skill, check:

• SKILL.md starts with --- at the first line and closes the front matter.
• name matches the directory name for managed or system skills.
• name uses only lowercase letters, numbers, and hyphens.
• description starts with a trigger-oriented phrase such as "Use when...".
• The body says when to use the skill, what procedure to follow, known pitfalls, and how to verify the result.
• Long references live under references/, templates/, scripts/, or assets/.
• Channel-visible commands are explicitly declared with the needed surface.
• The skill does not ask the assistant to bypass approval, audit, provider, toolset, or ChangePlan policy.

Test A Skill

Install a local skill:

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

If the gateway is running and you need the skill immediately:

anyy skills install --now ./release-checklist

Then invoke it from the TUI or another surface where the command is visible:

/release-checklist review the current repository state

If the skill is not visible, check:

• the active --home or profile,
• skills.disabled and skills.disabled_by_surface,
• platforms,
• command surface declarations,
• duplicate names in earlier roots,
• load warnings from the skills RPC.