Skip to content
palmpalmpalm

Set up a new project

You start a service and want your agents to test first, review Python Agent SDK code and read your internal docs. Four commands give Claude Code and Codex the same setup, and one commit gives it to everyone else.

When you finish, these files exist and all of them are committed:

  • Folder.agents/
    • Folderskills/
      • Foldergrill-me/
        • Folderagents/
          • openai.yaml
        • SKILL.md
      • Foldertdd/
        • Folderagents/
          • openai.yaml
        • Folderreferences/
          • mocking.md
        • SKILL.md
  • Folder.claude/
    • Folderagents/
      • agent-sdk-verifier-py.md
    • Folderskills/
      • Foldergrill-me/
        • SKILL.md
      • Foldertdd/
        • Folderreferences/
          • mocking.md
        • SKILL.md
  • Folder.codex/
    • Folderagents/
      • agent-sdk-verifier-py.toml
    • config.toml
  • .gitignore
  • .mcp.json
  • palm.lock.yaml
  • palm.yaml

Before you start

Section titled “Before you start”
  • palm is installed, and the project is a git repository.
  • You know which harnesses the team uses. This guide uses Claude Code and Codex.

Steps

Section titled “Steps”

  1. Declare the targets.

    Terminal window
    palm init --target claude,codex

    Committing targets: means every clone installs for the same harnesses, whatever each laptop has.

  2. Install two skills from one repository.

    Terminal window
    palm install mattpocock/skills tdd grill-me

    Name as many entities as you want after the source. Not sure what a repository offers? Run palm install mattpocock/skills first. It lists everything and writes nothing.

  3. Install an agent from another repository.

    Terminal window
    palm install anthropics/claude-plugins-official agent-sdk-verifier-py

    The agent names a skill and an MCP server it likes to use. palm prints the command for them and installs only what you named.

  4. Add the docs MCP server.

    Terminal window
    palm install mcp docs --url https://docs.example.com/mcp --header 'Authorization=Bearer ${DOCS_TOKEN}'

    The token stays in your environment. Each harness gets its own spelling of the reference.

    ~/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 tdd grill-me
    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)
    + skill  grill-me   .agents/skills/grill-me/, .claude/skills/grill-me/   3 files   from mattpocock/skills v1.2.3
    2 installed. Commit palm.yaml, palm.lock.yaml, .agents/ and .claude/ together.
    $ 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   2 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)
    1 installed. Commit palm.yaml, palm.lock.yaml and .codex/ together.
    $ palm install mcp docs --url https://docs.example.com/mcp --header 'Authorization=Bearer ${DOCS_TOKEN}'
    + mcp  docs   .mcp.json, .codex/config.toml   merged   (needs DOCS_TOKEN in the environment)
    1 installed. Commit palm.yaml, palm.lock.yaml and .mcp.json together.

  5. Commit and check.

    Terminal window
    git add -A
    git commit -m "Add the agent setup"
    palm check

    Commit first: palm check warns about generated files git does not track yet.

Check the result

Section titled “Check the result”
~/project
$ cat palm.yaml
targets: [claude, codex]
sources:
  mattpocock/skills:
    ref: ^1.2
    skills: [tdd, grill-me]
  anthropics/claude-plugins-official:
    ref: main
    agents: [agent-sdk-verifier-py]
mcp:
  docs:
    url: https://docs.example.com/mcp
    headers: {Authorization: "Bearer ${DOCS_TOKEN}"}
$ 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
! 1 server needs variables that are not 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
! 1 agent preloads what is not installed
✓ instruction files are within harness limits


! mcp docs: needs DOCS_TOKEN, which is not set; fix: export DOCS_TOKEN=…
! agent agent-sdk-verifier-py preloads skill sdk-helper, mcp context7, not installed; fix: palm install anthropics/claude-plugins-official sdk-helper mcp:context7

palm.yaml reads like a dependency list: two sources with their ranges, what you took from each, and one hand-declared server. palm check passes with two warnings. DOCS_TOKEN is not set in this shell: export it before you start Claude Code or Codex. The agent preloads a skill and a server the project does not install: the warning prints the palm install line for them, if you want them.

Next steps

Section titled “Next steps”