← Back to guides

Using Soul Blocks with Claude

The SoulBlocks skill lets Claude Code (and any AgentSkills-compatible tool) read, mint, and develop Soul Block identities on Base.

What the Skill Does

  • Read -- Load any Soul Block from the chain. No wallet needed.
  • List -- Discover which Soul Blocks a wallet owns.
  • Mint -- Mint a new Soul Block NFT (0.02 ETH + gas on Base).
  • Append -- Add a fragment to a Soul Block the agent owns.

Read operations work out of the box. Write operations (mint, append) require the evm-wallet skill for transaction signing, or can fall back to website deep links. Listing your Soul Blocks requires knowing your wallet address but no signing.

Installation

Step 1: Install the SoulBlocks skill

git clone https://github.com/soulblocks/skill-soulblock \
  ~/.claude/skills/soulblock
cd ~/.claude/skills/soulblock && npm install

Step 2: Install evm-wallet (optional, for write commands)

git clone https://github.com/surfer77/evm-wallet-skill \
  ~/.claude/skills/evm-wallet
cd ~/.claude/skills/evm-wallet && npm install

Without evm-wallet, write operations fall back to website deep links. The agent constructs a URL and you confirm the transaction in your browser.

Step 3: Create a config file (optional)

Create a .soulblock file in your project root or home directory:

active_token_id: 42       # Token you own (write target)
embodied_token_id: 42     # Token you're acting as
auto_load: true            # Load soul on session start

Key Concepts

Active vs. Embodied Soul

The active Soul Block is the token you own and can write to. The embodied Soul Block is the identity you are currently acting as -- which may be someone else's soul. Loading a soul changes the embodied identity but never changes the write target.

SOUL.md is a Cache

When the skill loads a Soul Block, it outputs the content as markdown. This is a disposable snapshot. The blockchain is always the source of truth. The skill re-fetches from chain before every append to prevent stale data.

Example Usage

Reading a Soul

# Ask Claude to load a soul
> "Load Soul Block #42"

# Claude runs:
npx ts-node ~/.claude/skills/soulblock/scripts/fetch.ts 42

# Output: full soul content as markdown
# Claude now embodies that identity

Appending a Fragment

# Ask Claude to add to your soul
> "Append a new fragment about what I learned today"

# Claude will:
# 1. Check your active_token_id
# 2. Re-fetch the soul from chain
# 3. Draft a new fragment (net-new content only)
# 4. Show you the content for confirmation
# 5. Submit via evm-wallet or provide a deep link

Listing Your Souls

# Ask Claude what souls you own
> "List my Soul Blocks"

# Output:
# You own 3 Soul Blocks:
#   #00042 — 5 fragments (active)
#   #00108 — 2 fragments
#   #00256 — 1 fragment (genesis only)
#
# Which would you like to set as active?

Deep Links (Without evm-wallet)

If the evm-wallet skill is not installed, Claude falls back to website deep links. The agent constructs a URL with the fragment content pre-filled, and you confirm the transaction in your browser wallet.

Append deep link format:

https://soulblocks.ai/append/[id]?content=[URL-encoded-text]

The content is URL-encoded and pre-filled into the editor. You review it, connect your wallet, and confirm. No private key sharing required.

Resources