Agent-persona

A portable, vendor-neutral open-source persona and Agent Skills layer for AI agents.

Key Personalities • Target Runtimes • Quick Start • CLI Reference • Architecture

Overview

Agent-persona provides AI coding, research, and design agents (such as Claude Code, Gemini CLI, Codex, Hermes, and OpenCode) with reusable professional roles, behavioral profiles, and task skills.

Instead of writing custom instructions for every AI tool, Agent-persona compiles one canonical persona definition into target-native instruction contexts (CLAUDE.md, GEMINI.md, AGENTS.md, SOUL.md) and standard Agent Skills folders (.agents/skills/).

Core Principle: Simple, file-based compatibility wrapper. Zero runtime daemons, API gateways, or LLM proxies.

Key Features

• Normalized Persona Specification: Define agent identity, principles, workflows, and policies once in persona.yaml.
• Cross-Agent Target Adapters: Native installation support for Claude Code, Gemini CLI, Codex, Hermes, OpenCode, and Generic Export.
• Safe Installation & Uninstallation: Managed comment blocks (<!-- AGENT-PERSONA:START -->) preserve custom user settings.
• Dry-Run & Backup Engine: Preview exact diffs before writing to disk with automatic timestamped backups.
• Comprehensive Skill Catalog: 30 pre-built, production-grade skills across Engineering, Research, and Frontend Design.
• System Doctor Diagnostics: Built-in agent-persona doctor diagnostic command to audit target environments.

Architectural Overview

Compilation & Compatibility Strategy

graph TD
    A[Canonical Persona YAML] --> B[Compiler Engine]
    S[Agent Skills Catalog] --> B
    
    B --> C[Unified Instruction Markdown]
    B --> D[Skill Manifest JSON]
    
    C --> E[Target Adapters]
    D --> E
    
    E --> F[Claude Code: CLAUDE.md + .agents/skills]
    E --> G[Gemini CLI: GEMINI.md + .agents/skills]
    E --> H[Codex: AGENTS.md + .agents/skills]
    E --> I[Hermes Agent: SOUL.md + AGENTS.md]
    E --> J[OpenCode: .agents/skills]
    E --> K[Generic Export: dist/bundle]

Installation Pipeline Flowchart

flowchart LR
    Start([User CLI Command]) --> Detect{Target Detected?}
    Detect -->|Yes| Backup[Create Backup]
    Detect -->|No| Prompt[Warn / Generic Export]
    Backup --> Inject[Inject Managed Block]
    Inject --> SyncSkills[Sync .agents/skills/]
    SyncSkills --> Validate[Run Doctor Check]
    Validate --> End([Ready to Use])

Supported Personalities

Supported Target Runtimes

Quick Start

1. Installation

Install via pip:

pip install agent-persona

Or install locally in editable mode:

git clone https://github.com/Agent-persona/Agent-persona.git
cd Agent-persona
pip install -e .

2. Basic Workflow

# 1. List available personas and skills
agent-persona list

# 2. Preview installation on Claude Code (Dry Run)
agent-persona install software-engineer --target claude --dry-run

# 3. Install Software Engineer persona on Claude Code
agent-persona install software-engineer --target claude

# 4. Run system diagnostics
agent-persona doctor

# 5. Uninstall persona safely
agent-persona uninstall --target claude

CLI Command Reference

agent-persona list

Lists all loaded personas and registered Agent Skills with category and description metadata.

agent-persona show <persona>

Displays detailed identity parameters, guiding principles, workflow steps, and referenced skills for a persona.

agent-persona show software-engineer

agent-persona validate <persona>

Validates persona definitions against persona.schema.json and checks skill SKILL.md YAML frontmatter.

agent-persona validate software-engineer

agent-persona compile <persona>

Compiles a persona into its unified Markdown system prompt representation.

agent-persona compile researcher

agent-persona install <persona> --target <target>

Installs the compiled persona and skill directories into the target agent environment.

agent-persona install software-engineer --target claude
agent-persona install researcher --target gemini
agent-persona install frontend-designer --target codex
agent-persona install software-engineer --target hermes
agent-persona install software-engineer --target opencode

agent-persona status

Shows real-time installation status across all registered target runtimes in the current project directory.

agent-persona doctor

Runs diagnostic checks on target environments, context files, and skill path availability.

agent-persona doctor --target claude

agent-persona export <persona> [--out <dir>]

Exports a portable standalone bundle (markdown + manifest + skills) for manual import into web or unsupported LLM platforms.

agent-persona export researcher --out dist/researcher-bundle

agent-persona uninstall [--target <target>]

Safely removes the Agent-persona managed instruction block and managed skills without altering user configuration.

agent-persona uninstall --target claude

Example Persona Definition (persona.yaml)

name: software-engineer
version: 1.0.0
description: Production-oriented software engineering persona focused on maintainability, minimal changes, TDD, and thorough verification.

identity:
  role: Software Developer / Engineer
  level: Senior
  summary: Act as a production-minded senior software engineer. Inspect code before editing, prefer minimal diffs, practice systematic debugging, write testable code, and verify before claiming completion.

behavior:
  communication:
    style: concise
    technical_precision: high
  reasoning:
    critical_thinking: high
    verify_before_claiming: true
    challenge_bad_assumptions: true
  execution:
    inspect_before_editing: true
    test_changes: true
    prefer_minimal_changes: true

principles:
  - Code correctness and runtime safety over quick hacks
  - Maintainability and consistency with existing codebase patterns
  - Security, input validation, and robust error handling
  - Empirical verification before claiming completion

skills:
  - spec-driven-development
  - planning-and-task-breakdown
  - context-engineering
  - source-driven-development
  - incremental-implementation
  - test-driven-development
  - systematic-debugging
  - code-review-and-quality
  - code-simplification
  - security-and-hardening
  - performance-optimization
  - git-workflow-and-versioning
  - documentation-and-adrs

workflows:
  - Understand requirements and inspect existing codebase
  - Form minimal, actionable implementation plan
  - Implement changes incrementally with test coverage
  - Systematically debug failures to root causes without masking symptoms
  - Verify changes via test execution and diff review
  - Report exact modifications and empirical verification results

policies:
  - Do not claim tests or commands passed without actually running them
  - Do not edit unrelated files or introduce unnecessary refactorings
  - Do not swallow errors or mask symptoms with dummy fallbacks
  - Protect secrets, API keys, and sensitive environment variables

Safety & Security Guarantee

Agent-persona modifies agent instruction and context files safely:

• Managed Comments: Instructions are injected exclusively within <!-- AGENT-PERSONA:START --> and <!-- AGENT-PERSONA:END --> markers.
• User Config Preservation: Existing instructions outside the managed markers are never touched.
• Timestamped Backups: A .bak.YYYYMMDD_HHMMSS backup is created automatically before updating existing context files.
• No Remote Script Execution: Installation processes files locally and never executes unverified remote scripts.

Testing & Verification

Agent-persona includes a complete test suite covering schema validation, compilation, installation safety, adapter behavior, CLI commands, and doctor checks.

To run tests:

pytest -v

Output:

============================= test session starts ==============================
collected 25 items

tests/test_adapters.py::test_list_adapters PASSED                        [  4%]
tests/test_adapters.py::test_get_adapter PASSED                          [  8%]
tests/test_adapters.py::test_generic_export PASSED                       [ 12%]
tests/test_cli.py::test_cli_version PASSED                               [ 16%]
tests/test_cli.py::test_cli_list PASSED                                  [ 20%]
tests/test_cli.py::test_cli_show PASSED                                  [ 24%]
tests/test_cli.py::test_cli_validate PASSED                              [ 28%]
tests/test_cli.py::test_cli_compile PASSED                               [ 32%]
tests/test_cli.py::test_cli_install_dry_run PASSED                       [ 36%]
tests/test_cli.py::test_cli_doctor PASSED                                [ 40%]
tests/test_compiler.py::test_compile_software_engineer PASSED            [ 44%]
tests/test_doctor.py::test_doctor_diagnostics PASSED                     [ 48%]
tests/test_installer.py::test_inject_managed_block_into_empty_content PASSED [ 52%]
tests/test_installer.py::test_inject_managed_block_preserves_user_content PASSED [ 56%]
tests/test_installer.py::test_update_existing_managed_block PASSED       [ 60%]
tests/test_installer.py::test_remove_managed_block PASSED                [ 64%]
tests/test_installer.py::test_installation_and_uninstallation_workflow PASSED [ 68%]
tests/test_loader.py::test_list_personas PASSED                          [ 72%]
tests/test_loader.py::test_load_software_engineer_persona PASSED         [ 76%]
tests/test_loader.py::test_load_nonexistent_persona PASSED               [ 80%]
tests/test_loader.py::test_list_skills PASSED                            [ 84%]
tests/test_schema.py::test_schema_valid_persona PASSED                   [ 88%]
tests/test_schema.py::test_schema_missing_fields PASSED                  [ 92%]
tests/test_schema.py::test_validate_all_project_personas PASSED          [ 96%]
tests/test_skills.py::test_all_skills_have_valid_frontmatter PASSED      [100%]

============================== 25 passed in 1.04s ==============================

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository and create a topic branch.
2. Ensure all personas adhere to persona.schema.json.
3. Ensure all skills contain valid SKILL.md frontmatter (name, description).
4. Run pytest -v to verify all tests pass.
5. Submit a pull request.

License

MIT License © 2026 Agent-persona Contributors