Import Persona from Paperclip
Convert a Paperclip agent directory into a WoterClip persona. Maps Paperclip's agent structure (SOUL.md, AGENTS.md, HEARTBEAT.md, TOOLS.md) to WoterClip's persona structure (SOUL.md, TOOLS.md, config.yaml).
Prerequisites
.woterclip/config.yaml must exist (run /woterclip-init first)
- User must provide the path to the Paperclip agent directory
File Mapping
| Paperclip File |
WoterClip Target |
What to Import |
SOUL.md |
SOUL.md |
Copy as-is — identity, posture, voice |
HEARTBEAT.md |
Append to SOUL.md |
Only the role-specific responsibilities section (bottom). Skip the generic heartbeat procedure (top) — replaced by the plugin's heartbeat skill |
AGENTS.md |
config.yaml + SOUL.md |
Safety rules → append to SOUL.md Boundaries section. Workspace paths → drop. Memory refs → drop |
TOOLS.md |
TOOLS.md |
Copy, replacing Paperclip API references with Linear MCP equivalents |
life/, memory/ |
Skip |
Claude Code has built-in memory |
Import Procedure
Step 1: Read Source
Ask the user for the Paperclip agent directory path. Read all files present:
SOUL.md (required)
AGENTS.md (optional)
HEARTBEAT.md (optional)
TOOLS.md (optional)
If SOUL.md doesn't exist, stop — this is not a valid Paperclip agent directory.
Step 2: Ask for Persona Details
Ask the user:
- Persona name — e.g., "Backend Engineer" (pre-fill from SOUL.md if obvious)
- Linear label — e.g.,
backend (must be unique)
- Role type —
engineer, orchestrator, analyst, or custom
- Model —
opus, sonnet, or haiku (suggest based on role)
- Escalates to — default:
ceo
Step 3: Transform SOUL.md
- Start with the Paperclip
SOUL.md content
- From
HEARTBEAT.md: extract the role-specific section (usually the bottom half, after the generic heartbeat steps). Append as a "## Working Style" or "## Role Responsibilities" section
- From
AGENTS.md: extract safety rules and boundaries. Append to the "## Boundaries" section
- Add a WoterClip-specific "## Quality Checklist" section if not present
- Drop any Paperclip-specific references (workspace paths, PARA memory, budget tracking)
Step 4: Transform TOOLS.md
- Start with the Paperclip
TOOLS.md content
- Replace Paperclip API references:
paperclip skill → mcp__claude_ai_Linear__* (Linear MCP tools)
para-memory-files → drop (replaced by Claude Code built-in memory)
- Paperclip API calls (
POST /checkout, PATCH /api/issues) → Linear MCP equivalents
- Add a "## Required" section listing
mcp__claude_ai_Linear and any other tool prefixes
- If AGENTS.md references playbooks, note them for manual migration
Step 5: Generate config.yaml
Create the persona config:
name: <Name>
role: <role>
label: <label>
escalates_to: <escalates_to>
required_tools:
- mcp__claude_ai_Linear
# additional tools based on TOOLS.md
runtime:
model: <model>
thinking_effort: <high for opus, medium otherwise>
max_turns: <300 for opus, 200 for sonnet, 100 for haiku>
enable_chrome: false
timeout: 0
extra_args: []
Step 6: Write Files
- Create
.woterclip/personas/<label>/
- Write
SOUL.md, TOOLS.md, config.yaml
- Update
.woterclip/config.yaml to add the persona to the personas map
- Create the Linear label if it doesn't exist
Step 7: Summary
Imported: <Name> (from <source-path>)
Label: <label>
Model: <model>
Files created:
✓ .woterclip/personas/<label>/SOUL.md
✓ .woterclip/personas/<label>/TOOLS.md
✓ .woterclip/personas/<label>/config.yaml
What was imported:
✓ SOUL.md — identity and posture
✓ HEARTBEAT.md — role responsibilities (appended to SOUL.md)
✓ AGENTS.md — safety rules (appended to Boundaries)
✓ TOOLS.md — tool list (Paperclip refs replaced)
What was NOT imported:
✗ Budget tracking (no WoterClip equivalent)
✗ PARA memory (replaced by Claude Code built-in memory)
✗ Approval workflows (not in v1)
Review SOUL.md and customize for this project's specific needs.
1---2name: persona-import3description: "This skill should be used when the user asks to \"import a paperclip agent\", \"convert paperclip to woterclip\", \"migrate from paperclip\", \"import persona from paperclip\", or wants to convert existing Paperclip agent directories into WoterClip persona format."4metadata:5 source: https://skillmd.com/skills/samin12/persona-import6 version: 0.1.07---89# Import Persona from Paperclip1011Convert a Paperclip agent directory into a WoterClip persona. Maps Paperclip's agent structure (SOUL.md, AGENTS.md, HEARTBEAT.md, TOOLS.md) to WoterClip's persona structure (SOUL.md, TOOLS.md, config.yaml).1213## Prerequisites1415- `.woterclip/config.yaml` must exist (run `/woterclip-init` first)16- User must provide the path to the Paperclip agent directory1718## File Mapping1920| Paperclip File | WoterClip Target | What to Import |21|----------------|-----------------|----------------|22| `SOUL.md` | `SOUL.md` | Copy as-is — identity, posture, voice |23| `HEARTBEAT.md` | Append to `SOUL.md` | Only the role-specific responsibilities section (bottom). Skip the generic heartbeat procedure (top) — replaced by the plugin's heartbeat skill |24| `AGENTS.md` | `config.yaml` + `SOUL.md` | Safety rules → append to SOUL.md Boundaries section. Workspace paths → drop. Memory refs → drop |25| `TOOLS.md` | `TOOLS.md` | Copy, replacing Paperclip API references with Linear MCP equivalents |26| `life/`, `memory/` | Skip | Claude Code has built-in memory |2728## Import Procedure2930### Step 1: Read Source3132Ask the user for the Paperclip agent directory path. Read all files present:33- `SOUL.md` (required)34- `AGENTS.md` (optional)35- `HEARTBEAT.md` (optional)36- `TOOLS.md` (optional)3738If `SOUL.md` doesn't exist, stop — this is not a valid Paperclip agent directory.3940### Step 2: Ask for Persona Details4142Ask the user:431. **Persona name** — e.g., "Backend Engineer" (pre-fill from SOUL.md if obvious)442. **Linear label** — e.g., `backend` (must be unique)453. **Role type** — `engineer`, `orchestrator`, `analyst`, or custom464. **Model** — `opus`, `sonnet`, or `haiku` (suggest based on role)475. **Escalates to** — default: `ceo`4849### Step 3: Transform SOUL.md50511. Start with the Paperclip `SOUL.md` content522. From `HEARTBEAT.md`: extract the role-specific section (usually the bottom half, after the generic heartbeat steps). Append as a "## Working Style" or "## Role Responsibilities" section533. From `AGENTS.md`: extract safety rules and boundaries. Append to the "## Boundaries" section544. Add a WoterClip-specific "## Quality Checklist" section if not present555. Drop any Paperclip-specific references (workspace paths, PARA memory, budget tracking)5657### Step 4: Transform TOOLS.md58591. Start with the Paperclip `TOOLS.md` content602. Replace Paperclip API references:61 - `paperclip` skill → `mcp__claude_ai_Linear__*` (Linear MCP tools)62 - `para-memory-files` → drop (replaced by Claude Code built-in memory)63 - Paperclip API calls (`POST /checkout`, `PATCH /api/issues`) → Linear MCP equivalents643. Add a "## Required" section listing `mcp__claude_ai_Linear` and any other tool prefixes654. If AGENTS.md references playbooks, note them for manual migration6667### Step 5: Generate config.yaml6869Create the persona config:7071```yaml72name: <Name>73role: <role>74label: <label>75escalates_to: <escalates_to>7677required_tools:78 - mcp__claude_ai_Linear79 # additional tools based on TOOLS.md8081runtime:82 model: <model>83 thinking_effort: <high for opus, medium otherwise>84 max_turns: <300 for opus, 200 for sonnet, 100 for haiku>85 enable_chrome: false86 timeout: 087 extra_args: []88```8990### Step 6: Write Files91921. Create `.woterclip/personas/<label>/`932. Write `SOUL.md`, `TOOLS.md`, `config.yaml`943. Update `.woterclip/config.yaml` to add the persona to the `personas` map954. Create the Linear label if it doesn't exist9697### Step 7: Summary9899```100Imported: <Name> (from <source-path>)101 Label: <label>102 Model: <model>103104Files created:105 ✓ .woterclip/personas/<label>/SOUL.md106 ✓ .woterclip/personas/<label>/TOOLS.md107 ✓ .woterclip/personas/<label>/config.yaml108109What was imported:110 ✓ SOUL.md — identity and posture111 ✓ HEARTBEAT.md — role responsibilities (appended to SOUL.md)112 ✓ AGENTS.md — safety rules (appended to Boundaries)113 ✓ TOOLS.md — tool list (Paperclip refs replaced)114115What was NOT imported:116 ✗ Budget tracking (no WoterClip equivalent)117 ✗ PARA memory (replaced by Claude Code built-in memory)118 ✗ Approval workflows (not in v1)119120Review SOUL.md and customize for this project's specific needs.121```