Skills

Manage Skills and MCP resources, assign capabilities per Agent, and discover external tools

skill manages Skills and MCP resources in one Power. Each Agent has its own skill directory, which is the authoritative set of skills it can use. The Power discovers those skills, reads SKILL.md, injects the inventory into the system prompt, and exposes tools from MCP servers explicitly assigned to that Agent.

Skills live at ~/.downcity/agents/<agent-id>/skills. Every entry is a directory containing SKILL.md. An entry is either a copy installed into the Agent directory or a symlink pointing at a skill that lives elsewhere.

The directory sits inside the Agent's own data root, so removing the Agent removes its skills with it. Writing into it is granted to the Agent's shell, which means the Agent can install and link skills itself. The root path comes from the container (PowerContext.data_root_path / PowerLifecycleContext.data_root_path), not from a constructor option.

Scope

The Agent's own directory is the default and authoritative source. Two extra sources are readable on demand:

  • project reads <workspace>/.agents/skills
  • home reads ~/.agents/skills
  • all returns the union of the Agent directory, project, and home

When the same skill ID appears in more than one source, the Agent directory wins, then project, then home.

list and lookup accept the same scope argument, and both default to the Agent directory. The system prompt inventory lists the Agent directory only, so every skill name shown to the model is directly usable without a scope argument.

Actions

ActionPayloadPurpose
list{ scope?: "agent" | "project" | "home" | "all" }List skills in the given scope; defaults to the Agent directory
lookup{ name: string, scope?: ... }Read a skill's SKILL.md
servers{}List MCP servers assigned to the calling Agent and their status, including disabled or invalid definitions
tools{ server_id: string }Read tool names and input schemas from an assigned MCP server
call{ server_id: string, tool_name: string, arguments: object }Invoke a tool on an assigned MCP server

lookup returns the skill body as a standard context message, so the content reaches the model on the next step. It does not persist any session state.

There are no find or install actions. Installation and linking happen either through the Agent's own shell or from the Desktop, because the skills CLI cannot install directly into an Agent skill directory and the copy step needs a decision about what lands there.

The Agent installs in two steps: run the skills CLI inside a temporary directory, then copy the resulting skill into its own directory. The system prompt carries the exact commands, including the npm_config_cache override that keeps npx working inside the sandbox.

Reading project or home through scope does not make those skills available. A skill that lives in the user directory or a workspace becomes usable only after it is copied or linked into the Agent directory, and that entry is what list reports by default.

Listing the Agent's skills:

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

Reading a skill:

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

The model uses the same protocol inside a Session:

skill({
  action: "lookup",
  args: {
    name: "web-access",
  },
});

Configuration

The Skill Config panel manages global MCP server definitions. Existing definitions and OAuth credentials remain under ~/.downcity/powers/mcp/; merging the interface does not move them. See MCP configuration for server file formats and connection behavior.

Skill discovery scope is determined by the Agent directory plus the scope argument. Use ignore to filter skills:

const skill_power = new SkillPower({
  ignore: ["legacy-skill", /^internal-/],
});
  • A string matches both the skill ID and its name.
  • A RegExp filters in bulk.
  • A predicate returning true excludes the skill.

Desktop

The Skill Sidebar uses a Skills / MCP capsule in its upper-right corner to switch resource types. The search field stays fixed below the title and capsule, aligned with the resource list. Only the list scrolls. Compact single-line entries display a monochrome type icon and the resource name, with a subtle connection-status dot on the right for MCP servers. A soft background and medium-weight name mark the selection. Hover and keyboard focus use background changes; the search field and resource rows do not draw rings. Long names truncate and reveal their full text on hover. There are no Agent, source, or directory groups. Each type retains its own search and selected resource when switching. Searching and refreshing do not change the current selection.

Select a Skill to see its name and full description at the top of the main area. Long descriptions preserve line breaks. The YAML header of SKILL.md is displayed separately from its body: top-level author, version, and license appear in a compact key-value list, while other fields are in a metadata section that starts collapsed. Its expanded content area uses a subtle background that follows the current theme. Objects and arrays retain their hierarchy, and long values wrap. If YAML cannot be parsed, its source is available in the metadata section. The body area renders only the skill's Markdown body. Source paths and Agent usage are available in a collapsed details section. The independent Skill detail tab opened from Agent Profile uses the same document presentation.

Select an MCP server to inspect connection status, tools, and errors. The initial view prompts you to select a resource. Independent copies with the same ID in different directories remain separate resources. Links resolving to the same directory share one resource and its Agent usage.

In Agent Profile → Skills, add skills from the user catalog, remove assigned skills, and enable MCP servers for that Agent. Click an installed Skill to open its document in a separate tab. The detail reads that Agent’s installed SKILL.md directly. The host manages closing and reusing tabs, and the list retains its filter and scroll position. Skills with the same ID in different Agents open separately. If the installed Skill is unavailable, the detail shows its read error. Read failures offer a Retry action in the same tab. Global server enablement alone does not grant Agent access. Assignments are stored as a JSON array of server IDs at ~/.downcity/agents/<agent-id>/mcp-servers.json; a missing file grants no MCP access.

The host actions skill.mcp.assign and skill.mcp.unassign accept { agent_id, server_id }. These manage assignments through the Power action gateway; they are not model actions. Model calls use skill with servers, tools, and call, and cannot access unassigned servers.

The only linkable source is the user directory. A workspace .agents/skills does not appear in the interface: to give a skill to an Agent, put it in the user directory first.

Removing a linked skill deletes only the symlink. Operations stay inside the Agent directory.