Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add instructions/acnlabs/openpersona/agents-mdgit clone --depth 1 https://github.com/acnlabs/OpenPersonaWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/instructions/acnlabs/openpersona/agents-md)<a href="https://agentmods.dev/instructions/acnlabs/openpersona/agents-md"><img src="https://agentmods.dev/badge/instructions/acnlabs/openpersona/agents-md.svg" alt="Measured on agentmods" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.10383 | $0.10383 |
| Opus 5 | $0.05192 | $0.05192 |
| Sonnet 5 | $0.02077 | $0.02077 |
| Haiku 4.5 | $0.01038 | $0.01038 |
Grade A, and why
OpenPersona AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 3d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 453 lines — stays where its author put it; the contents beside it link to each section on GitHub.
AGENTS.md
Instructions for AI coding agents working on the OpenPersona codebase.
Project Overview
OpenPersona is a persona lifecycle framework: it declares, generates, enforces, and evolves AI agent personas. It uses an open four-layer model (Soul / Body / Faculty / Skill), compiles persona.json into portable SKILL.md skill packs, and works with any agent (Cursor, Claude Code, Codex, ZeroClaw, OpenClaw, and 30+ others via npx skills add). CLI management (install / switch / uninstall) defaults to OpenClaw integration.
Key distinction: This repo is the framework itself, not a persona. The skills/open-persona/SKILL.md is a meta-skill for using the framework; this file guides developing it.
ROADMAP.md is listed in .gitignore and is not part of the published tree — keep a local copy for maintainer planning if you use it.
Setup
npm install # Install dependencies
node --test tests/ # Run all tests — must pass before any PR
- Node.js ≥ 18 required (see
enginesin package.json) - No build step — plain CommonJS, no transpilation
- Dependencies: fs-extra, mustache, commander, inquirer, chalk, adm-zip
Project Structure
bin/cli.js ← CLI entry point (commander-based)
lib/
generator/ ← Core generation pipeline
index.js ← Orchestrator (the heart of the project)
validate.js ← Generate Gate (hard-reject constraint checks)
derived.js ← Derived template variable computation (returns plain object; caller applies via Object.assign)
body.js ← Body layer description builder
social.js ← Social aspect: Agent Card + ACN config + Contact Book seed builders
economy.js ← Economy aspect: load descriptor + write initial state
lifecycle/ ← Persona lifecycle management
installer.js ← Persona installation to ~/.openpersona (with optional OpenClaw sync)
uninstaller.js ← Persona removal
switcher.js ← Active persona switching + handoff generation
forker.js ← Persona fork (derive child from installed parent)
refine.js ← Skill Pack Refinement (behavior-guide bootstrap + compliance scan + skill gate + social auto-sync)
porter.js ← Export / import persona packs
contributor.js ← Persona Harvest (community contribution)
social/ ← Social Contact Book (runtime CRUD for contacts.json / contacts.jsonl)
http.js ← Thin HTTP client (GET/POST, no external deps) used by acn-client.js
contacts.js ← Local contacts CRUD: load / save / add / remove / lookup / list / log
acn-client.js ← ACN read client: fetchAgent / searchAgents / syncContacts / autoDiscover
state/ ← Runtime state management
runner.js ← Persona directory resolution + state-sync delegation
evolution.js ← Evolution governance (evolve-report CLI + promoteToInstinct Soul-Memory Bridge)
registry/ ← Local persona registry (~/.openpersona/persona-registry.json)
index.js ← loadRegistry / saveRegistry / registryAdd / registryRemove / registrySetActive
remote/ ← External service calls (outbound network)
registrar.js ← ACN registration logic (acn-register CLI command); integrates auto-discover hook
downloader.js ← Preset/package downloading from ClawHub
searcher.js ← Persona search on ClawHub
curator.js ← Pack Curator (openpersona curate CLI command; privileged, requires OPENPERSONA_CURATOR_TOKEN)
report/ ← Reporting and visualization
vitality.js ← Vitality score calculation (AgentBooks wrapper)
vitality-report.js ← HTML vitality report rendering
canvas.js ← Living Canvas HTML profile page
helpers.js ← Shared report utilities (readJsonSafe, formatDate, daysBetween, truncate)
publisher/ ← Publish persona to OpenPersona public directory
index.js ← Validate GitHub repo + report to OpenPersona telemetry
utils.js ← Path constants + print helpers + string utilities (no registry logic)
templates/
skill.template.md ← Mustache template → generated SKILL.md (four-layer headings)
soul/ ← Soul layer molds
soul-injection.template.md ← Soul layer injection orchestrator (delegates to partials/)
soul-state.template.json ← Initial state.json mold (seeded from soul config)
partials/ ← Mustache partials for soul-injection (6 files, each ~30–75 lines)
soul-intro.partial.md ← persona intro, selfie, personality
soul-awareness-identity.partial.md ← Self-Awareness > Identity + dormant Capabilities
soul-awareness-body.partial.md ← Self-Awareness > Body (Signal Protocol, runtime, interface)
soul-awareness-growth.partial.md ← Self-Awareness > Growth (pendingCommands, constraints, evolution sources)
soul-how-you-grow.partial.md ← How You Grow (stage criteria, eventLog, self-narrative)
soul-economy.partial.md ← Survival Policy
body/ ← Body layer molds
state-sync.template.js ← scripts/state-sync.js source template (Body nervous system)
lifecycle/ ← Lifecycle molds
handoff.template.md ← Context handoff markdown (used by lib/lifecycle/switcher.js)
reports/ ← Standalone HTML report/tool templates
vitality.template.html ← openpersona vitality report HTML output
canvas.template.html ← Living Canvas HTML profile page
layers/
soul/
constitution.md ← ⚠️ PROTECTED — universal ethical foundation
README.md
faculties/ ← Faculty implementations (voice, avatar, memory)
skills/ ← Local skill definitions (skill.json + SKILL.md per skill; music, selfie, reminder)
body/ ← Body layer definitions
aspects/ ← 5 systemic concept source assets (orthogonal to the 4 layers)
economy/ ← Economy scripts + SKILL.md (AgentBooks wrapper)
evolution/ ← README (state template in templates/soul/, state-sync in templates/body/)
vitality/ ← README (lib/report/vitality.js, templates/reports/vitality.template.html)
social/ ← README (agent-card/acn-config generated inline by generator)
rhythm/ ← README (heartbeat config in persona.json, sync in lib/lifecycle/switcher.js)
schemas/ ← Production specs — organized by 4+5 architecture (documentation-only; runtime enforcement is JS in lib/generator/validate.js)
persona.input.schema.json ← Authoritative input schema (v0.17+ grouped format)
persona.input.spec.md ← Input field reference
persona-skill-pack.spec.md ← Product (skill pack) structure spec
soul/ ← Soul layer schemas (soul-declaration.spec.md, handoff.schema.json)
body/ ← Body layer schemas (body-declaration.spec.md, embodiment.schema.json, signal.schema.json)
faculty/ ← Faculty layer schemas (faculty-declaration.spec.md, faculty.schema.json)
skill/ ← Skill layer schemas (skill-declaration.spec.md)
evolution/ ← Evolution concept schemas (soul-state.schema.json, evolution-event.schema.json, influence-request.schema.json)
social/ ← Social concept schemas (agent-card.schema.json, acn-register.schema.json, contacts.schema.json)
legacy/ ← Deprecated flat-format schemas (pre-v0.17)
presets/ ← Pre-built persona definitions (samantha, ai-girlfriend, etc.)
tests/ ← Node.js native test runner (node:test)
skills/open-persona/ ← Meta-skill for AI agents using the framework
frontend/ ← Next.js web directory (openpersona.co)
app/skills/ ← /skills persona leaderboard page
app/datasets/ ← /datasets HF dataset directory page (+ detail pages)
app/api/datasets/ ← Dataset API routes (publish, sync-metrics, sync-discovery, readme)
lib/kv-datasets.ts ← Upstash Redis helpers for dataset metadata
components/dataset-leaderboard.tsx ← Dataset list UI (mirrors skill leaderboard)
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 3d ago First seen · 453 lines · 10,383 tokens per session scan A fa9effd85b2c
OpenPersona AGENTS.md is an instructions file published in the GitHub repository acnlabs/OpenPersona (48 stars, last pushed 23d ago), licensed MIT. It adds 10,383 tokens to every session, about $0.0519 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other instructions, from other repositories
zeroclaw CLAUDE.md
Claude Code instructions for zeroclaw-labs/zeroclaw, covering claude.md — zeroclaw (claude code), claude code settings, hooks and slash commands.
rosclaw CLAUDE.md
Instructions for ros-claw/rosclaw, covering claude.md — rosclaw project onboarding, rosclaw runtime boundary (managed), safety contract (p0), robot integration setup and capability apps.
AgentEval copilot-instructions.md
Instructions for AgentEvalHQ/AgentEval, covering agenteval - ai coding agent instructions, architecture overview, environment setup, optional: secondary models for comparison and build & test commands.
AgentEval maf-upgrade-preparation.instructions.md
Instructions for analyzing a new MAF version and producing an upgrade plan BEFORE updating the NuGet package.
AgentEval tracing.instructions.md
Guidelines for implementing trace recording and replay.
zhin zhin-plugin.instructions.md
Instructions for zhinjs/zhin, covering zhin plugin runtime authoring, package contract, convention directories, imports and native typescript and command routes.