/plugin-porting

name: plugin-porting
description: Turn an external plugin — a Codex or Claude Code plugin, a skills repository, a folder in a GitHub repository — into a PenguinHarness plugin package, its skills and its MCP servers, and install it on the server's plugin market with `penguin plugin install <folder>`; the package format, the mapping rules and the review duties.
version: 2026.10.11.2

Plugin Porting

A PenguinHarness plugin is an npm package installed on the server and shared by every Project: the Plugins page shows its card, and anyone installs it on an Agent from there ("Manage installs"), which writes its skills and adds its MCP servers to that Agent's tools. This skill turns a plugin written for another tool into that package: fetch the source at a pinned commit, recognise its layout, build the package in a scratch folder by the rules below, review it, install it with the CLI, verify. To put a few skills into this Agent alone instead, use the `skill-porting` skill.

Before you start

• If the message only names this skill, ask for the source: a GitHub link (a repository, a folder, or a file inside the plugin's folder), a Codex or Claude Code plugin name, or a local folder.
• Installing puts the package on the whole server with the administrator's authority that the CLI's local token carries. Its skills become standing instructions for every Agent that installs it, so the review below is not optional.
• Work in a scratch folder (`mktemp -d`). Never write into the server's data root by hand: `penguin plugin install` is the only way in.
• Keep the conversation small: list trees with `find`, read files with `sed -n '1,120p'`, and never `cat` a whole tree.

The package format

<folder>/
├── package.json             # the manifest (below)
├── README.md                # optional; the plugin's detail dialog shows it
├── icon.svg                 # optional; the card's icon
└── skills/<name>/SKILL.md   # one directory per skill, with the text files it refers to

{
  "name": "@ported/<name>",
  "version": "1.0.0",
  "description": "English one-line description.",
  "keywords": ["penguin-plugin", "ported"],
  "author": "Upstream author",
  "homepage": "https://…",
  "repository": { "type": "git", "url": "https://github.com/<owner>/<repo>", "directory": "<path>" },
  "license": "MIT",
  "penguin": {
    "title": "Display Name",
    "short_description": "One short line for the card.",
    "category": "software-development",
    "icon": "icon.svg",
    "quick_start": { "prompt": "A first request that shows the plugin working." },
    "mcp_servers": [
      {
        "name": "cloudflare-api",
        "config": {
          "transport": "http",
          "url": "https://mcp.cloudflare.com/mcp",
          "headers": { "Authorization": "Bearer ${CLOUDFLARE_API_TOKEN}" },
          "oauth": {}
        },
        "setup": [{ "key": "CLOUDFLARE_API_TOKEN", "label": "Cloudflare API token" }]
      }
    ]
  }
}

• `name` (npm name; the part after the scope is the plugin name, `[a-z0-9_-]`) and `version` (semver) are required: without them the package is refused. Everything else is optional, and a missing field is shown as missing (no description, the puzzle-piece icon, the Other group); never invent one.
• Product fields live in the `penguin` block: `title` / `title_zh`, `description_zh`, `short_description` / `short_description_zh`, `category` (`office-productivity`, `software-development` or `ai-app-development`), `icon` (an `.svg` path in the package; a plain SVG — no script, event handlers, links or external references — at most 64 KiB), `quick_start` (`prompt`, optional `prompt_zh`, `skills`, `goal`), `hooks`.
• A skill's `SKILL.md` frontmatter is exactly three single-line keys: `name` (= its directory), `description` (one line, English), `version` (`YYYY.MM.DD.N`, the UTC date and a sequence number). The parser reads only single-line `key: value` pairs: YAML lists and block scalars (`|`, `>`) break it. Files beside SKILL.md must be text; images are not installed.
• `hooks/` is PenguinHarness's own hook protocol (Node scripts at the stop, pre_tool_use and user_prompt points, with `penguin.hooks.version`). Another tool's hooks are never carried over.
• `penguin.mcp_servers` lists the plugin's MCP servers, each `{ name, config, setup }`; `config` is exactly an Agent's `tools.mcpServers` entry (`transport` `http`, `sse` or `stdio`; `url` and `headers`, or `command`, `args`, `env` and `cwd`). A value the user must supply — a token, a client secret, an API key — is never in the package: write `${KEY}` where it goes and list the key in `setup` (with a `label`, and a `help` link where one says how to get it); the Agent's vault fills it in when the server connects, and until then the server waits as "needs setup". `${PLUGIN_ROOT}` is the package's own directory on the server, for a stdio server's files. `config.oauth` (`scopes`, `client_id`, `client_secret`) marks a server that signs in with OAuth, which this version cannot do yet: it is installed and waits as "sign-in required" unless an `Authorization` header gives it a token. A package may consist of MCP servers alone, with no `skills/`.

1. Fetch the source at a pinned commit

Read a GitHub link as `https://github.com/<owner>/<repo>/(tree|blob)/<ref>/<path>`. A `blob` link names a file: its plugin is the nearest folder above it that holds `.codex-plugin/`, `.claude-plugin/` or `skills/` (for `…/plugins/<name>/README.md` that is `plugins/<name>`). Resolve the ref to a commit, then download one tarball and extract only that folder:

WORK="$(mktemp -d)"
SHA="$(curl -s --max-time 30 "https://api.github.com/repos/<owner>/<repo>/commits/<ref>" \
  | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>console.log(JSON.parse(s).sha))')"
curl -sL --max-time 300 "https://codeload.github.com/<owner>/<repo>/tar.gz/$SHA" -o "$WORK/src.tgz"
TOP="$(tar -tzf "$WORK/src.tgz" | head -1 | cut -d/ -f1)"
tar -xzf "$WO