Entities and kinds

An entity is one item palm installs: a skill, an agent (subagent), an instruction, a hook or an MCP server. Its kind decides which file each harness gets. Every entity is named within its source.

$ palm install anthropics/claude-plugins-official
i 5 notes from indexing anthropics/claude-plugins-official (see: palm describe source anthropics/claude-plugins-official)
anthropics/claude-plugins-official  main (bc94689)   3 plugins, 2 skills, 1 agent, 1 hook, 3 MCP servers
  plugin  agent-sdk-dev           2 skills, 1 agent, 1 hook   (also hook agent-sdk-dev: name it plugin:agent-sdk-dev)
  plugin  github                  1 MCP server   (also mcp github: name it plugin:github)
  plugin  context7                2 MCP servers   (also mcp context7: name it plugin:context7)
  skill   sdk-helper              Helps with Agent SDK questions.
  skill   new-sdk-app             Create and setup a new Claude Agent SDK application
  agent   agent-sdk-verifier-py   Use this agent to verify a Python Agent SDK app. Examples: <example>C…
  hook    agent-sdk-dev           claude: PreToolUse -> python3 hooks/guard.py   (a program; asks before installing)   (also plugin agent-sdk-dev: name it hook:agent-sdk-dev)
  mcp     github                  http: https://api.githubcopilot.com/mcp/   (also plugin github: name it mcp:github)
  mcp     context7                http: https://mcp.context7.com/mcp   (also plugin context7: name it mcp:context7)
  mcp     fs                      stdio: npx -y @modelcontextprotocol/server-filesystem .   (a program; asks before installing)
Nothing written. Install some:
    palm install anthropics/claude-plugins-official sdk-helper new-sdk-app
    palm install anthropics/claude-plugins-official --all

Listing a source shows every entity it offers, one row per entity, with the kind first. Hooks and stdio MCP servers carry the note (a program; asks before installing). The warnings name what palm found and will not install.

Five kinds

Kind	What it is	A harness reads it as
`skill`	A folder with a `SKILL.md`, plus optional `scripts/`, `references/` and `assets/`. The harness loads it on demand.	a skill folder
`agent`	An agent (subagent). One file holds a system prompt, a delegation description, tools and a model.	an agent file in the harness’s format
`instruction`	Markdown context that is always on, scoped to paths, or loaded on request. It advises the model and enforces nothing.	a rule file, or a managed block in `AGENTS.md` or `GEMINI.md`
`hook`	Lifecycle events, matchers and shell commands. It runs programs on your machine.	entries merged into the harness’s settings or hooks file
`mcp`	An MCP server connection, either a command that starts it (stdio) or a URL (HTTP).	an entry merged into the harness’s MCP config

The targets matrix lists the exact path per kind and harness. A hook takes the name of the folder that holds its hooks.json, and a hook at the source root takes the source’s name in palm.yaml, as the scan rules show.

Plugins select, they do not install

A plugin is a set of entities that a source groups together, usually with a plugin.json. In palm a plugin is a selector over a source’s entities, never something that lands in a harness as a unit.

palm install obra/superpowers plugin:superpowers

That command installs every member of the plugin and records plugins: [superpowers] in palm.yaml. Each member gets its own lock entry with via: plugin:superpowers. To drop one member for the whole team, exclude it.

sources:
  obra/superpowers:
    ref: ^4.0
    plugins:
      - name: superpowers
        exclude: [skill:brainstorming]

A plugin’s hook is a member like any other and asks for consent on its own. Install plugins and marketplaces shows the full flow.

Commands install as skills

Claude Code and Cursor merged slash commands into skills, and Codex and Copilot deprecate prompt files. palm has no command kind. A commands/*.md, commands/*.toml or prompts/*.prompt.md file in a source is indexed as a skill of the same name and installed to the skill paths, with a note.

$ARGUMENTS keeps working in Claude Code and Cursor. When a skill and a command in one source share a name, the skill wins and palm warns.

The conversion has a cost, and the install note names it. A harness without skill commands loses the /name call: OpenCode, for example, no longer offers /inbound. Where a harness does not expand $ARGUMENTS, the text stays literal. A command without a description gets its first body line as the skill’s description, so the model can still pick it.

Instructions and activation

An instruction keeps its activation from the source: always on, scoped to paths, on request, or manual. Claude Code and OpenCode have no on-request or manual rule, so palm 0.2 installs such a rule always-on there. palm prints one notice per widened rule, such as ! rule x: on-request in the source, always-on for claude until 0.3. palm describe <name> shows the activation. palm 0.3 maps those rules to skills instead.

Naming an entity

After the source, you name entities, optionally with a kind prefix.

palm install mattpocock/skills tdd grill-me
palm install anthropics/claude-plugins-official mcp:context7
palm remove anthropics/claude-plugins-official mcp:context7

The prefix is needed only when one name means two kinds in that source, such as a plugin and an MCP server both called context7. The listing marks such names. On a terminal palm asks which one you mean, and without one it stops with E_AMBIGUOUS and lists the kind:name forms. --all takes every entity except those that run a program.

One scope holds one entity per kind and name. Installing an entity whose kind and name another source already installed stops with E_CONFLICT. The message names the owner and the palm remove <source> <kind:name> command that frees the name. --force does not apply.

An entity name is one path segment of letters, digits, ., _ and -, starting with a letter or a digit. A skill takes the name in its SKILL.md, else its folder name. An agent takes its file name without .md or .agent.md. The scan rules list the source of every other name.

Agents name, palm does not chase

An agent file may list the skills and MCP servers it uses. palm installs the agent and prints one line with the command for the rest.

i agent agent-sdk-verifier-py names sdk-helper, context7: palm install anthropics/claude-plugins-official sdk-helper mcp:context7

palm never installs dependencies you did not name, so a removal never takes something another entry needs. When an agent’s skills: names a skill that is not installed, palm check warns with the install command. palm update and palm remove print the same notice when such a skill appears or leaves.