skill Plugin

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.

Registration

import { Agent, Workspace } from "@downcity/agent";
import { SkillPlugin } from "@downcity/plugins/skill";

const agent = new Agent({
  id: "skill-helper",
  workspace: new Workspace({ path: "/path/to/project" }),
  plugins: [new SkillPlugin()],
});

By default, the plugin scans only .agents/skills in the current project.

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 agent.plugins.run_action({
  plugin: "skill",
  action: "list",
  payload: {},
});

Read a skill:

const result = await agent.plugins.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 agent.plugins.run_action({
  plugin: "skill",
  action: "find",
  payload: {
    query: "web access",
  },
});

Call install to get installation instructions:

const install_instructions = await agent.plugins.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