Skip to content
palmpalmpalm

What is palm

palm installs the files that configure AI coding agents. You name a git repository and the skills, subagents, rules, hooks or MCP servers you want from it. palm writes each one where every harness you use reads it.

Terminal window
npm install -g @paliontech/palm
palm install mattpocock/skills tdd

One item, six formats

Section titled “One item, six formats”

Coding agents read the same kinds of files: skills, subagents, instructions, hooks and MCP servers. Each harness expects them in its own place and format. A subagent is a Markdown file in .claude/agents for Claude Code. Codex wants a TOML file in .codex/agents, and Copilot wants an .agent.md file in .github/agents. An MCP server goes into .mcp.json, .codex/config.toml, .vscode/mcp.json, .cursor/mcp.json, .gemini/settings.json or opencode.json, and each spells an environment variable differently.

Copying by hand means one edit per harness for every change, and nothing records where a file came from. palm reads a repository as its author published it, writes each item in each harness’s format, and records the source commit and every file in palm.lock.yaml.

Two commands from zero

Section titled “Two commands from zero”

Nora uses Claude Code and has an empty project with a .claude/ folder.

~/project
$ palm install superpowers
x "superpowers" is not a repository. palm installs from git repositories:
    palm install <owner/repo> [names...]      for example  palm install obra/superpowers
  Not sure which repository? https://github.com/search?q=superpowers+SKILL.md&type=code
$ palm install obra/superpowers
obra/superpowers  v4.0.3 (083545e)   1 plugin, 3 skills, 1 hook
  plugin  superpowers               3 skills, 1 hook   (also hook superpowers: name it plugin:superpowers)
  skill   brainstorming             Use before any creative work: explore intent, requirements and design.
  skill   test-driven-development   Use when implementing any feature or bugfix, before writing implement…
  skill   writing-skills            Use when creating or editing skills.
  hook    superpowers               claude: SessionStart -> hooks/run-hook.cmd session-start   (a program; asks before installing)   (also plugin superpowers: name it hook:superpowers)
Nothing written. Install some:
    palm install obra/superpowers brainstorming test-driven-development
    palm install obra/superpowers --all
$ palm install obra/superpowers --all
i .gitignore: added .palm/local/ and palm.local.yaml
i ref ^4.0 saved to palm.yaml (latest tag v4.0.3); edit ref: to track main
targets: claude   (detected from .claude/; change targets: in palm.yaml)
+ skill  brainstorming             .claude/skills/brainstorming/   1 file
+ skill  test-driven-development   .claude/skills/test-driven-development/   3 files
+ skill  writing-skills            .claude/skills/writing-skills/   2 files
! hook   superpowers               runs a program on your machine; not installed
    see it:      palm install obra/superpowers hook:superpowers --dry-run
    install it:  palm install obra/superpowers hook:superpowers
3 installed. Commit palm.yaml, palm.lock.yaml and .claude/ together.

The first command fails, and its first line is the fix. The second lists what the repository offers and writes nothing. The third installs every skill for the one harness palm detected, and leaves out the hook until Nora looks at it. The hook runs a program, so it needs its own install and a yes. Consent explains that step.

What palm writes

Section titled “What palm writes”

This session installs one agent and one skill for all six harnesses.

~/project
$ palm init --target claude,codex,copilot,cursor,gemini,opencode
+ wrote palm.yaml: targets claude, codex, copilot, cursor, gemini, opencode
+ wrote .gitignore: .palm/local/, palm.local.yaml
next: see what a source offers, for example: palm install mattpocock/skills
$ palm install anthropics/claude-plugins-official agent-sdk-verifier-py
i agent agent-sdk-verifier-py preloads skill sdk-helper, mcp context7, not installed: palm install anthropics/claude-plugins-official sdk-helper mcp:context7
i ref main saved to palm.yaml; edit ref: to pin a tag
+ agent  agent-sdk-verifier-py   .claude/agents/agent-sdk-verifier-py.md, .codex/agents/agent-sdk-verifier-py.toml +4   6 files   from anthropics/claude-plugins-official main
    .codex/agents/agent-sdk-verifier-py.toml: dropped model (sonnet), tools, skills, mcpServers, color (not supported by Codex)
    .github/agents/agent-sdk-verifier-py.agent.md: dropped model (sonnet), tools: Bash(python -m pytest:*) restriction (all of execute), mcpServers, skills, color (not supported by GitHub Copilot)
    .cursor/agents/agent-sdk-verifier-py.md: dropped model (sonnet), tools, skills, mcpServers, color (not supported by Cursor)
    .gemini/agents/agent-sdk-verifier-py.md: dropped model (sonnet), tools: Bash(python -m pytest:*) restriction (all of run_shell_command), skills, color (not supported by Gemini CLI)
    .opencode/agents/agent-sdk-verifier-py.md: dropped model (sonnet), color (green), tools: Bash(python -m pytest:*) restriction (all of bash), skills (not supported by OpenCode)
1 installed. Commit palm.yaml, palm.lock.yaml, .claude/, .codex/, .cursor/, .gemini/, .github/ and .opencode/ together.
$ palm install mattpocock/skills tdd
i ref ^1.2 saved to palm.yaml (latest tag v1.2.3); edit ref: to track main
+ skill  tdd   .agents/skills/tdd/, .claude/skills/tdd/   5 files   from mattpocock/skills v1.2.3
    claude gets its own copy in .claude/skills
    cursor reads .claude/skills; no second copy
1 installed. Commit palm.yaml, palm.lock.yaml and .agents/ together.
  • Folder.agents/
    • Folderskills/
      • Foldertdd/
        • …
  • Folder.claude/
    • Folderagents/
      • agent-sdk-verifier-py.md
    • Folderskills/
      • Foldertdd/
        • …
  • Folder.codex/
    • Folderagents/
      • agent-sdk-verifier-py.toml
  • Folder.cursor/
    • Folderagents/
      • agent-sdk-verifier-py.md
  • Folder.gemini/
    • Folderagents/
      • agent-sdk-verifier-py.md
  • Folder.github/
    • Folderagents/
      • agent-sdk-verifier-py.agent.md
  • Folder.opencode/
    • Folderagents/
      • agent-sdk-verifier-py.md
  • .gitignore
  • palm.lock.yaml
  • palm.yaml
  • palm.yaml is the manifest. It lists the targets, each source with its version range, and what you took from it.
  • palm.lock.yaml is the lock. It pins each source to a commit and records one hash per entry and target, plus every file palm wrote.
  • Everything else is a generated file. You commit these too, so a teammate’s clone and your CI hold the same bytes.

When palm helps

Section titled “When palm helps”
Situation What palm does
You use two or more harnesses on one repository One install writes the item for each of them, once per harness.
Your team shares skills, agents and MCP servers The files are committed. A clone works without palm, and palm check proves it matches.
A plugin ships hooks palm shows every command and script before it writes them, and pins your yes by hash.
An MCP server’s README shows a JSON snippet palm install mcp --snippet - reads it and writes it for every harness, with secrets as references.
You keep your own skills in the repository palm create skill <name> writes a template into ./agent-kit and installs it. Edits are live.

Eight verbs

Section titled “Eight verbs”
Verb What it does
palm init Write palm.yaml with the targets for this project.
palm install List a source, install from it, or with no arguments make the disk match palm.yaml and the lock.
palm remove Delete exactly the files and config entries an entity wrote.
palm update Move sources to the newest commit their range allows, after showing a plan.
palm check Read-only CI gate. Fails on any drift between palm.yaml, the lock, the files and in-repo sources.
palm get List what is installed, the sources, or the targets.
palm describe Show one entity, source, target, or the entity that wrote a file.
palm create Write a template skill, agent, instruction or hook into your in-repo source.

palm migrate, palm completion and palm cache clean are utilities. The CLI reference covers all of them.

Map of the docs

Section titled “Map of the docs”
Section Answers Start with
Getting started How to install palm and finish a first install Installation, Quick start
Concepts How palm models what it installs Sources, Entities, palm.yaml and palm.lock.yaml, Consent
Guides How to finish one task, start to end Set up a new project, Share a team baseline, Check the setup in CI
Reference Exact commands, files, paths and terms CLI, palm.yaml, Targets matrix, Glossary
Explanation Why palm works the way it does Why native files, Why sources per project, Security model