Skip to content
palmpalmpalm

Quick start

In five minutes you install a skill from mattpocock/skills for Claude Code and Codex, prove the setup is consistent, and remove it again. Every step is one command.

Terminal window
palm init --target claude,codex
palm install mattpocock/skills
palm install mattpocock/skills grill-me
palm check

Before you start

Section titled “Before you start”
  • palm is installed. See Installation.
  • You are inside a git repository.

palm treats the nearest directory with a palm.yaml, or else the nearest .git, as the project root. It refuses to treat your home directory, ~/.palm or a harness home such as ~/.claude as a project, so run these steps inside one.

Steps

Section titled “Steps”

  1. Choose the harnesses for this project.

    Terminal window
    palm init --target claude,codex

    palm writes targets: [claude, codex] to palm.yaml. It adds .palm/local/ and palm.local.yaml to .gitignore, the only palm paths you do not commit. Without --target, palm detects the harnesses from folders such as .claude/ and .cursor/, and prints what it found.

  2. See what the repository offers.

    Terminal window
    palm install mattpocock/skills

    With no names, palm fetches the repository, lists its skills, agents, rules, hooks and MCP servers, and writes nothing. The last lines are commands you can paste.

  3. Install a skill.

    Terminal window
    palm install mattpocock/skills grill-me

    palm declares mattpocock/skills in palm.yaml with a version range, writes the skill for both harnesses and pins the commit in palm.lock.yaml.

  4. Check the result.

    Terminal window
    palm check

    palm check recomputes every generated file from the lock and changes nothing. CI runs the same command.

  5. Commit.

    Terminal window
    git add palm.yaml palm.lock.yaml .gitignore .claude .agents
    git commit -m "Add the grill-me skill"

What happened

Section titled “What happened”

This is a recorded session of steps 1 to 3.

~/project
$ palm init --target claude,codex
+ wrote palm.yaml: targets claude, codex
+ wrote .gitignore: .palm/local/, palm.local.yaml
next: see what a source offers, for example: palm install mattpocock/skills
$ palm install mattpocock/skills
i 1 note from indexing mattpocock/skills (see: palm describe source mattpocock/skills)
mattpocock/skills  v1.2.3 (2c0db90)   1 plugin, 5 skills
  plugin  mattpocock-skills   3 skills
  skill   tdd                 Test-driven development with red-green-refactor.
  skill   grill-me            Interview the user relentlessly about a plan.
  skill   handoff             Write a handoff note for the next session.
  skill   old-thing           An old skill kept for reference.
  skill   git-guardrails      Block dangerous git commands.
Nothing written. Install some:
    palm install mattpocock/skills tdd grill-me
    palm install mattpocock/skills --all
$ palm install mattpocock/skills grill-me
i ref ^1.2 saved to palm.yaml (latest tag v1.2.3); edit ref: to track main
+ skill  grill-me   .agents/skills/grill-me/, .claude/skills/grill-me/   3 files   from mattpocock/skills v1.2.3   (claude gets its own copy in .claude/skills)
1 installed. Commit palm.yaml, palm.lock.yaml, .agents/ and .claude/ together.

The session created these files.

  • Folder.agents/
    • Folderskills/
      • Foldergrill-me/
        • Folderagents/
          • openai.yaml
        • SKILL.md
  • Folder.claude/
    • Folderskills/
      • Foldergrill-me/
        • SKILL.md
  • .gitignore
  • palm.lock.yaml
  • palm.yaml
  • Claude Code reads the copy in .claude/skills/grill-me/.
  • Codex reads the copy in .agents/skills/grill-me/. Copilot, Gemini CLI and OpenCode read that folder too.
  • palm.yaml now declares mattpocock/skills with ref: ^1.2, the newest tag’s minor range, and lists grill-me under it.
  • palm.lock.yaml records the commit, one render hash per harness and every file path.

Start a new Claude Code or Codex session in the project, and the skill is available. palm describe grill-me shows the source, the version and the files per harness.

Remove it again

Section titled “Remove it again”
~/project
$ palm check
✓ manifest and lock agree
✓ palm.yaml targets match the lock
✓ every entry is rendered
✓ every entry is on all its targets
✓ generated files match the lock
✓ no stray file in a folder palm owns
- applied files outside the lock: skipped (global scope only)
✓ in-repo sources match the lock
✓ no generated path lies inside a source
✓ every program palm installed is trusted
✓ no foreign command in the hook files palm manages
✓ no foreign stdio server in the MCP files palm manages
✓ every hook script exists
✓ no literal secret in generated files
✓ every variable the servers need is set
✓ generated files are committed
✓ every source is declared
✓ no link leaves the scope
✓ no hidden Unicode in generated files
✓ no harness loads an entity twice
✓ no two agents or commands share a name in a harness folder
✓ every skill an agent preloads is installed
✓ instruction files are within harness limits
no problems
$ palm remove grill-me
- skill  grill-me   .agents/skills/grill-me/, .claude/skills/grill-me/   3 files
1 removed.
$ palm get
No entities installed in the project scope.
see what a source offers, for example: palm install mattpocock/skills

palm remove deleted the skill’s files and every folder it emptied, and removed the entry from palm.yaml and the lock. The source had nothing left, so palm removed it from palm.yaml too. Only these two files changed.

  • palm.lock.yaml
  • palm.yaml

Next steps

Section titled “Next steps”