Skip to content
palmpalmpalm

Adopt files you copied by hand

Many projects began by copying an agent (subagent) or a skill from GitHub into .claude/ or .cursor/. Those copies drift from their source, and nobody remembers where they came from. palm takes them over. You name each source once, and the lock tracks the file from then on.

When you finish, palm owns both files. The identical skill needed nothing, and the edited agent is replaced with your version still in git:

~/project
$ 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   .claude/skills/tdd/   2 files   from mattpocock/skills v1.2.3
    cursor reads .claude/skills; no second copy
    adopted 2 files already there (the same content)
1 installed. Commit palm.yaml, palm.lock.yaml and .claude/ together.
$ palm install cursor/plugins/pstack comment-sicko
i ref main saved to palm.yaml; edit ref: to pin a tag
! agent  comment-sicko   .claude/agents/comment-sicko.md   1 file   from cursor/plugins/pstack main   (claude: installed; cursor: failed)
x agent comment-sicko from cursor/plugins/pstack → cursor: refusing to overwrite .cursor/agents/comment-sicko.md
  palm install cursor/plugins/pstack agent:comment-sicko --force
1 partial.
$ palm install cursor/plugins/pstack comment-sicko --force
~ agent  comment-sicko   .claude/agents/comment-sicko.md, .cursor/agents/comment-sicko.md   2 files   from cursor/plugins/pstack main
1 re-rendered.
$ git status --short
 M .cursor/agents/comment-sicko.md
?? .claude/agents/
?? .gitignore
?? palm.lock.yaml
?? palm.yaml

The session ran against palm’s test fixtures, which mirror mattpocock/skills and cursor/plugins.

Before you start

Section titled “Before you start”
  • Commit your current files, so git diff shows what palm changes.
  • Know or find the repository each copy came from.
  • Set the targets with palm init. It detects them from the folders you already have, and prints the evidence for each.

Steps

Section titled “Steps”

  1. Take stock of the harness folders.

    Terminal window
    find .claude .cursor .github .codex .gemini .opencode .agents -type f 2>/dev/null
    Folder Holds files for
    .claude/agents, .claude/skills, .claude/rules Claude Code
    .cursor/agents, .cursor/rules Cursor
    .github/agents, .github/instructions GitHub Copilot
    .codex/agents, .gemini/agents, .opencode/agents Codex, Gemini CLI and OpenCode
    .agents/skills every harness except Claude Code
    .mcp.json, .vscode/mcp.json, .cursor/mcp.json MCP servers

  2. Install each entity from its source over your copy.

    Terminal window
    palm install mattpocock/skills tdd

    A copy that matches what palm would write is adopted. palm records it in the lock and writes nothing. The comparison reads the frontmatter as data and ignores trailing whitespace, so a copy that differs only in quoting or line ends still matches.

  3. Look at each file palm refuses.

    Terminal window
    palm install cursor/plugins/pstack comment-sicko

    palm never overwrites a file it did not write. The error names the file and the command that replaces it. Compare your copy with the source. If your change matters, keep it in your own source under a new name (step 5), since the source’s entity keeps its own name.

  4. Replace the rest with --force.

    Terminal window
    palm install cursor/plugins/pstack comment-sicko --force
    git diff

    --force replaces your copy and records it in the lock. git diff shows exactly what changed.

  5. Move files you wrote yourself into an in-repo source.

    palm has no import command for your own files. git mv does the job and keeps the history.

    Terminal window
    mkdir -p agent-kit/agents
    git mv .claude/agents/release-captain.md agent-kit/agents/
    palm install ./agent-kit release-captain

    palm declares ./agent-kit in palm.yaml and writes the agent back for every target, now as a generated file. From then on you edit agent-kit/agents/release-captain.md, and a bare palm install renders the change.

MCP servers and hooks work the same way. A server or hook entry you wrote by hand that matches palm’s is adopted, never added a second time. One that differs blocks the install until you pass --force, and palm keeps every other entry in the file.

A project with a skills-lock.json or an apm.yml gets one hint from palm init and palm check: palm 0.3 imports those files. Until then, install each entry by name as above.

Check the result

Section titled “Check the result”
Terminal window
palm get --files
palm check

palm get --files lists every file palm now owns with the entity that wrote it. palm describe <path> answers the same question for one file.

Next steps

Section titled “Next steps”