Build skills

Use agent skills to extend ZeroTwo and ZeroCode with task-specific capabilities. A skill packages instructions, resources, and optional scripts so either product can follow a workflow reliably. Skills build on the open agent skills standard. Skills are the authoring format for reusable workflows. Plugins distribute reusable skills and connectors through the universal plugin directory shared by ZeroTwo and ZeroCode. Plugins are available with ZeroTwo Work on the web, with ZeroTwo Work and ZeroCode in the ZeroTwo desktop app, and through ZeroTwo desktop app. Use skills to design the workflow itself, then package it as a plugin when you want other people to install it. Standalone skills are available in the ZeroTwo desktop app, and IDE extension. Skills bundled in plugins are also available through supported plugin surfaces, including ZeroTwo Work on the web. In the ZeroTwo desktop app, open Skills in the sidebar to view and explore skills created across your projects.

Skills picker showing available skills in the ZeroTwo desktop app

Skills use progressive disclosure to manage context efficiently. ZeroTwo and ZeroCode start with each skill’s name and description, then load the full SKILL.md instructions when they decide to use that skill. In ZeroCode, the initial list also includes each skill’s file path. To avoid crowding out the rest of the prompt, this list uses at most 2% of the model’s context window, or 8,000 characters when the context window is unknown. If many skills are installed, ZeroCode shortens skill descriptions first. For large skill sets, ZeroCode may omit some skills from the initial list and show a warning. This budget applies only to the initial skills list. When ZeroCode selects a skill, it still reads the full SKILL.md instructions for that skill. A skill is a directory with a SKILL.md file plus optional scripts and references. The SKILL.md file must include name and description.

my-skill/
  SKILL.md  # Required: instructions + metadata
  scripts/  # Optional: executable code
  references/  # Optional: documentation
  assets/  # Optional: templates, resources
  agents/
    openai.yaml  # Optional: appearance and dependencies

How ZeroTwo and ZeroCode use skills

ZeroTwo and ZeroCode can activate skills in two ways:

Explicit invocation: Include the skill directly in your prompt. In ZeroTwo, type @ to select a skill. In ZeroTwo desktop app or the desktop app, run /skills or type $ to mention a skill.
Implicit invocation: ZeroTwo or ZeroCode can choose a skill when your task matches the skill description.

Because implicit matching depends on description, write concise descriptions with clear scope and boundaries. Front-load the key use case and trigger words so a host can still match the skill if descriptions are shortened.

Create a skill

If you already know the workflow and it’s easier to show than describe, use Record & Replay. The recorder captures the workflow, inspects the steps, and drafts a reusable skill from the demonstration. If you want to describe the skill instead, use the built-in creator. In ZeroTwo Work, invoke it as @skill-creator. In ZeroCode, invoke it as:

$skill-creator

The creator asks what the skill does, when it should trigger, and whether it should stay instruction-only or include scripts. Instruction-only is the default. You can also create a skill manually by creating a folder with a SKILL.md file:

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for ZeroTwo or ZeroCode to follow.

ZeroCode detects skill changes automatically. If an update doesn’t appear, restart ZeroCode.

Where ZeroCode loads local skills

ZeroCode reads skills from repository, user, admin, and system locations. For repositories, ZeroCode scans .agents/skills in every directory from your current working directory up to the repository root. If two skills share the same name, ZeroCode doesn’t merge them; both can appear in skill selectors.

Skill Scope	Location	Suggested use
`REPO`	`$CWD/.agents/skills` Current working directory: where you launch ZeroCode.	If you’re in a repository or code environment, teams can check in skills relevant to a working folder. For example, skills only relevant to a microservice or a module.
`REPO`	`$CWD/../.agents/skills` A folder above CWD when you launch ZeroCode inside a Git repository.	If you’re in a repository with nested folders, organizations can check in skills relevant to a shared area in a parent folder.
`REPO`	`$REPO_ROOT/.agents/skills` The topmost root folder when you launch ZeroCode inside a Git repository.	If you’re in a repository with nested folders, organizations can check in skills relevant to everyone using the repository. These serve as root skills available to any subfolder in the repository.
`USER`	`$HOME/.agents/skills` Any skills checked into the user’s personal folder.	Use to curate skills relevant to a user that apply to any repository the user may work in.
`ADMIN`	`/etc/zerotwo/skills` Any skills checked into the machine or container in a shared, system location.	Use for SDK scripts, automation, and for checking in default admin skills available to each user on the machine.
`SYSTEM`	Bundled with ZeroCode by ZeroTwo.	Useful skills relevant to a broad audience such as the skill-creator and plan skills. Available to everyone when they start ZeroCode.

ZeroCode supports symlinked skill folders and follows the symlink target when scanning these locations. These locations are for authoring and local discovery. When you want to distribute reusable skills beyond a single repo, or optionally bundle them with connectors, use plugins.

Distribute skills with plugins

Direct skill folders are best for local authoring and repo-scoped workflows. If you want to distribute a reusable skill, bundle two or more skills together, or ship a skill alongside a connector, package them as a plugin. Plugins can include one or more skills. They can also optionally bundle registered MCP server connections, bundled MCP server configuration, and presentation assets in a single package.

Install curated skills for local use

To add curated skills beyond the built-ins for your own local ZeroCode setup, use $skill-installer. For example, to install the $linear skill:

$skill-installer linear

You can also prompt the installer to download skills from other repositories. ZeroCode detects newly installed skills automatically; if one doesn’t appear, restart ZeroCode. Use this for local setup and experimentation. For reusable distribution of your own skills, prefer plugins.

Enable or disable local ZeroCode skills

Use [[skills.config]] entries in ~/.zerotwo/config.toml to disable a skill without deleting it:

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Restart ZeroCode after changing ~/.zerotwo/config.toml.

Optional metadata

Add agents/openai.yaml to configure UI metadata in the ZeroTwo desktop app, to set invocation policy, and to declare tool dependencies for a more seamless experience with using the skill.

interface:
  display_name: "Optional user-facing name"
  short_description: "Optional user-facing description"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional surrounding prompt to use the skill with"

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "ZeroTwo Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.zerotwo.ai/mcp"

allow_implicit_invocation (default: true): When false, ZeroCode won’t implicitly invoke the skill based on user prompt; explicit $skill invocation still works.

Best practices

Keep each skill focused on one job.
Prefer instructions over scripts unless you need deterministic behavior or external tooling.
Write imperative steps with explicit inputs and outputs.
Test prompts against the skill description to confirm the right trigger behavior.

For more examples, see GitHub CI repair, PDF, Linear, openai/skills, and the agent skills specification. For installable distribution, prefer plugins.

Overview

Customization

Config file

Agent configuration

Extend ZeroTwo

Environments

Permissions

Windows

Connections

How ZeroTwo and ZeroCode use skills

Create a skill

Where ZeroCode loads local skills

Distribute skills with plugins

Install curated skills for local use

Enable or disable local ZeroCode skills

Optional metadata

Best practices

​How ZeroTwo and ZeroCode use skills

​Create a skill

​Where ZeroCode loads local skills

​Distribute skills with plugins

​Install curated skills for local use

​Enable or disable local ZeroCode skills

​Optional metadata

​Best practices

How ZeroTwo and ZeroCode use skills

Create a skill

Where ZeroCode loads local skills

Distribute skills with plugins

Install curated skills for local use

Enable or disable local ZeroCode skills

Optional metadata

Best practices