How plugin skills reach agents today:
services/apireads each enabled plugin's skills from the local skills store and serves them fromGET /api/v1/skills(CLI installs) andGET /api/v1/skills?target=agent(services/agent-runner, which re-fetches every 30 seconds and writes them to the conversation's sandbox next to the bundled defaults and the agent's own skills). The sections below marked historical describe the earlierservices/ai-agentdesign (HTTP fetch ofbaseUrl, per-conversation); the end result — install/enable/disable takes effect on a following conversation — is preserved. See default-skills.md for the remaining gaps (no per-trigger-type skills, no keyword-triggered selection).
Paca agents are meant to support plugin-contributed Agent Skills. Each installed Paca plugin can ship one or more SKILL.md files (the same AgentSkills format used by Paca's own bundled default skills — see default-skills.md) as part of its install artifact. When an agent conversation starts, the agent execution service is meant to fetch the skill content for every enabled plugin that declares a skills section in its manifest and merge it into that conversation's skill list.
From the model's perspective, plugin skills are meant to appear alongside the agent's own configured skills and Paca's bundled defaults — no visible distinction beyond the name.
Unlike MCP tools, which are loaded by a separate Node.js process (apps/mcp) that dynamically imports executable code, plugin skills are meant to be inert markdown text, consumed directly by the agent execution service — no code execution, no separate loader process.
Plugin install (marketplace or direct)
│
│ skills_tar_gz_url artifact
▼
services/api Installer
│
└── extract to {SkillsDir}/{pluginId}/{skillName}/SKILL.md
served statically at /plugins-skills/{pluginId}/{skillName}/SKILL.md
Conversation start (services/ai-agent, historically; agent-runner now gets the same result via GET /api/v1/skills?target=agent)
│
├── SELECT name, manifest FROM plugins WHERE enabled = true
│ │
│ └── For each plugin with manifest.skills:
│ resolve baseUrl against GATEWAY_BASE_URL (SSRF-checked)
│ GET {baseUrl}/{skillName}/SKILL.md for each declared name
│ parse frontmatter + body → openhands.sdk.context.Skill
│
└── merge_skills_by_name(agent's own skills,
merge_skills_by_name(plugin skills, bundled defaults))
| Component | Location | Purpose |
|---|---|---|
SkillsManifest |
services/api/internal/domain/plugin/entity.go |
Parses the manifest's skills section — still live, services/api-owned |
Installer |
services/api/internal/platform/plugin/installer.go |
Extracts the skills tarball to the local skills store — still live, services/api-owned |
list_enabled_plugin_skills |
(removed) services/ai-agent/src/repositories/agent_repository.py |
Queried enabled plugins and resolved each skill's URL |
resolve_plugin_base_url |
(removed) services/ai-agent/src/repositories/agent_repository.py |
SSRF guard, mirrored apps/mcp/src/plugin-loader.ts's resolveImportUrl |
load_plugin_skills |
(removed) services/ai-agent/src/agent/builder.py |
Fetched each SKILL.md and parsed it into an SDK Skill |
Add a skills section to your plugin.json:
{
"id": "com.example.my-plugin",
"displayName": "My Plugin",
"version": "1.0.0",
"skills": {
"baseUrl": "/plugins-skills/com.example.my-plugin",
"names": ["paca-pr-review", "paca-changelog"]
}
}-
baseUrlis the root URL of your extracted skills bundle. Likemcp.remoteEntryUrl, it may be relative (resolved against the gateway) or absolute. -
nameslists the skill directory names available underbaseUrl— declared explicitly because the static file server does not support directory listing. Each name must exist as{baseUrl}/{name}/SKILL.mdin your artifact and follow the AgentSkills naming convention (lowercase alphanumeric segments joined by single hyphens, e.g.paca-pr-review). -
All skill names must start with
paca-— this is the naming convention every skill in the Paca ecosystem follows (the bundled defaults arepaca-do,paca-doc, etc.), so a plugin's contributed skills read as clearly Paca-related wherever they surface — in<available_skills>, and as slash commands once installed viainstall-paca-skills.sh. This is a separate convention from MCP tool naming (which prefixes with your own plugin name, e.g.checklist_,bdd_— see mcp-plugin-system.md) since tools need to avoid colliding with other plugins, while skills all share onepaca-namespace by design. -
Names may not start with
paca-trigger-— that prefix is reserved for Paca's own fixed per-conversation scaffolding skills. -
routes(optional) tells the corepacarouter skill when to send the user to one of your skills. Each entry has askill(one of yournames) and awhenthat completes "If the user wants to…":"skills": { "baseUrl": "/plugins-skills/com.example.my-plugin", "names": ["paca-pr-review"], "routes": [ { "skill": "paca-pr-review", "when": "Review a pull request against a task's acceptance criteria" } ] }
Each route becomes one row in the router's "Route to a specialized skill" table (
/paca-pr-reviewfor CLI installs), directly after the bundled rows. Rows appear only while the plugin is installed and enabled and its skill is actually served, so the router never mentions a skill that is not there.whenmust be a single line of at most 200 characters, without|or backticks; a route for a skill not innames, an emptywhen, or two routes for one skill are rejected at install time. The row is written in each flavor's own routing syntax — a slash command for CLI installs (GET /api/v1/skills),load_skill(name: "…")for the in-product agent (?target=agent).services/agent-runnerre-fetches that set every 30 seconds rather than once per process, so installing, enabling or disabling a plugin shows up in the router on a following conversation.
Your plugin's install artifacts can include a skills_tar_gz_url tarball (alongside backend_tar_gz_url / frontend_tar_gz_url / mcp_tar_gz_url) containing one directory per skill:
skills/
paca-pr-review/
SKILL.md
paca-changelog/
SKILL.md
Each SKILL.md follows the standard AgentSkills format — YAML frontmatter plus a markdown body:
---
name: paca-pr-review
description: Reviews a pull request against the project's coding conventions.
triggers:
- /paca-pr-review
---
# PR Review Skill
You are reviewing a pull request...name in the frontmatter must match the directory name (and the names entry in your manifest). triggers is optional — omit it for an always-active skill (its content is injected into every conversation's system prompt); declare it for a model-selectable skill invoked on demand (progressive disclosure), the same distinction Paca's own default skills make (see default-skills.md).
The installer extracts this tarball into the plugin store (PLUGINS_STORE) and the gateway serves it at /plugins-skills/{pluginId}/:
local(default):{PLUGINS_SKILLS_DIR}/{pluginId}/, served by the gateway straight from that folder.s3:{PLUGINS_S3_PREFIX}/{pluginId}/skills/in the storage bucket, streamed by the API (/api/v1/plugin-assets/skills/...) through the gateway.
When a skill name collides across sources, precedence is meant to be: agent-configured skills > plugin skills > bundled defaults. A user's own skill for their agent always wins; a plugin skill only fills in where the agent hasn't defined one; Paca's bundled defaults are the fallback. Paca's reserved paca-trigger-* scaffolding skills (see default-skills.md) are meant to sit outside this precedence entirely — no skill from any source may use that name prefix. The name-prefix rejection is enforced at plugin-install validation time in services/api (Go). On agent-runner the bundled and plugin skills arrive as one list ahead of the agent's own skills, so the by-name precedence above is not enforced there beyond the API's own rejection of plugin names that collide with bundled ones.
- On every conversation start, the agent execution service queried
SELECT name, manifest FROM plugins WHERE enabled = true— no caching, so an install/enable/disable took effect on the next conversation. - Plugins without a
skillssection in their manifest were skipped. baseUrlwas resolved againstGATEWAY_BASE_URLand checked against the same SSRF allowlistapps/mcp's MCP loader already applies toremoteEntryUrl:https://allowed unless the hostname resolves to a private/internal IP;http://allowed only for localhost or the configured gateway host.- Each declared skill was fetched individually. A fetch or parse failure for one skill was logged and that skill skipped — it didn't affect any other skill or fail the conversation.
- A plugin manifest is admin-installed but still treated as untrusted input for URL resolution purposes — the SSRF guard existed because a malicious or misconfigured
baseUrlcould otherwise have made the fetching service reach an internal service (e.g. a cloud metadata endpoint) and inject the response into every conversation as skill content. On the current pathservices/apireads skill files from its own local store rather than fetchingbaseUrl, so this guard is not needed there. - Skill content itself is not sandboxed — it becomes part of the model's context exactly like any other skill. Only install plugins from trusted sources.
| Aspect | MCP (mcp.remoteEntryUrl) |
Skills (skills.baseUrl) |
|---|---|---|
| Content | Executable ESM module | Static markdown (SKILL.md) |
| Loader | Separate Node.js process (apps/mcp), per conversation |
services/api serves the files from its local skills store; agent-runner re-fetches the set every 30 seconds (historically an in-process Python fetch in services/ai-agent, per conversation) |
| Manifest shape | Single URL | Base URL + explicit list of names |
| Consumed via | import(url) |
Plain HTTP GET |
| Failure isolation | Whole plugin's tools unavailable | Per-skill — other skills from the same plugin still load |