Skills

skill is the Agent's local skill catalog. It discovers visible skills, reads SKILL.md, and injects the available skills and scan roots into the system prompt.

find and install are instruction-only actions. They use the input and active SkillPlugin scan configuration to return Shell guidance, but they never execute commands, access the network, or change files. The Agent follows the returned prompt with the skills CLI.

Desktop workspace

Skill does not declare Config. It remains visible in the Plugins Catalog for its documentation and also contributes a top-level navigation entry. Opening that entry lists every registered Workspace in a tree matching the Workspace file-tree interaction:

• Workspaces tree makes each Workspace an expandable root. Expanding it reveals its .agents/skills; selecting a root or Skill synchronizes the list or detail in the Mainview.
• Personal manages Skills under ~/.agents/skills.
• Discover searches the public catalog through the official skills CLI and installs into Personal or a selected Workspace.

Workspace selection is independent of the Desktop's current Workspace, and the Mainview does not duplicate it with another Workspace select. Selecting a root shows its Skill list; selecting a Skill opens a dedicated detail page that safely renders SKILL.md. Delete and other row actions live in an Item Menu, and mutations refresh Sidebar and Mainview together. Removing a Skill permanently deletes its directory from the selected scope after confirmation.

Registration

import { Agent } from "@downcity/agent";
import { City } from "@downcity/city";
import { create_builtin_plugin_registrations } from "@downcity/plugins";

const registrations = create_builtin_plugin_registrations();
const city = new City({ plugins: registrations, workspaces: [workspace] });
const agent = new Agent({ id: "skill-helper" });
city.agents.add(agent);

By default, the plugin scans only .agents/skills in the current project. To customize scan roots, construct a SkillPlugin instance and provide it to City, never to Agent.

Constructor options can extend the scan scope:

const skill_plugin = new SkillPlugin({
  use: ["project", "home"],
  paths: [".agents/shared-skills"],
  ignore: ["legacy-skill"],
});

• use: ["project"] scans <project>/.agents/skills
• use: ["home"] scans ~/.agents/skills
• paths adds custom scan directories; relative paths resolve from the project root
• ignore excludes skills by ID, name, regular expression, or predicate

For duplicate IDs, precedence is project > paths > home.

Actions

The Skill Plugin exposes four actions:

List skills:

const result = await city.plugins.scope({ agent_id: agent.id, workspace_id: workspace.id }).run_action({
  plugin: "skill",
  action: "list",
  payload: {},
});

Read a skill:

const result = await city.plugins.scope({ agent_id: agent.id, workspace_id: workspace.id }).run_action({
  plugin: "skill",
  action: "lookup",
  payload: {
    name: "web-access",
  },
});

The model uses the same protocol during a Session:

plugin_call({
  plugin: "skill",
  action: "lookup",
  payload: {
    name: "web-access",
  },
});

Search And Installation

Call find to get search instructions:

const find_instructions = await city.plugins.scope({ agent_id: agent.id, workspace_id: workspace.id }).run_action({
  plugin: "skill",
  action: "find",
  payload: {
    query: "web access",
  },
});

Call install to get installation instructions:

const install_instructions = await city.plugins.scope({ agent_id: agent.id, workspace_id: workspace.id }).run_action({
  plugin: "skill",
  action: "install",
  payload: {
    spec: "owner/repository@web-access",
  },
});

Both actions return instructions in data.prompt only. The system prompt lists the resolved scan roots and directs the Agent to these actions; the install prompt then derives the following from the active use / paths options:

• resolved scan directories and scan order
• the installation method for each scan-root type
• the required post-installation verification

The find prompt directs the Agent to use its available web or browser capability to search these Skill catalogs:

• skills.sh
• LobeHub Skill Community

It also provides the npx skills find command so the Agent can compare catalog and CLI results before choosing an installation spec.

Search for a missing skill through the shell:

npx -y skills find "<query>"

Install into a project scan root:

npx -y skills add "<spec>" -y

Use global installation only when the configuration includes use: ["home"]:

npx -y skills add "<spec>" -g -y

Custom paths do not have a universal skills CLI destination flag. After installing or copying, the final layout must be:

<configured-root>/<skill-id>/SKILL.md

Installation Verification Guidance

The install action does not execute or verify installation in code. Its returned prompt tells the Agent to call the following after the Shell command completes:

plugin_call({
  plugin: "skill",
  action: "list",
  payload: {},
});

If the new skill appears in the list result, the prompt continues by directing the Agent to call lookup. This workflow is prompt-driven rather than an action-level state machine.

The complete workflow is:

1. Call list to check whether the skill already exists locally.
2. If missing, call find, then follow its returned prompt to search through the Shell.
3. After choosing a spec, call install, then follow its returned prompt to select a scan root and install.
4. Call list again to verify discovery.
5. Call lookup to read SKILL.md.

System Prompt

Whenever a Session system prompt is built, the Skill Plugin rescans the configured roots and injects:

• names and descriptions of available skills
• scan roots and their resolved filesystem paths
• the workflow for calling find/install when a skill is missing

Concrete commands and follow-up list guidance are returned by the actions. The install action uses the same scan configuration instead of hard-coding project or global installation.

Related Docs

• Built-in Plugin Overview
• Plugin Actions
• Plugin System