{
  "markdown": "# Persona\n\n![](./assets/logo.png)\n\n**A unified interface for managing AI identity and capabilities.**\n\nPersona is a standard for decoupling **Roles** (who the AI is) and **Skills** (what the AI can do) from specific LLM providers and applications. Write your prompts and tools once, and deploy them across the Gemini CLI, Cline, Python scripts, or any MCP-compatible environment.\n\n---\n\n## ❓ Why Persona?\n\nAs LLM applications grow, \"prompt engineering\" often becomes a messy tangle of strings hardcoded into different applications. Persona solves this by treating prompts as **software artifacts**:\n\n1.  **Decoupling:** Your prompts (Roles) and tools (Skills) shouldn't be locked into a specific AI or client. Persona lets you define them in a neutral, standardized format.\n2.  **Local & Transparent:** Your data stays with you. Roles and skills are stored as simple Markdown files on your local disk. Metadata and embeddings are persisted in **Parquet** files, ensuring your registry is human-readable, portable, and easy to inspect.\n3.  **Portability:** Use the same \"Expert Python Architect\" persona in your IDE (via Cline), your terminal (via Gemini CLI), or your backend services (via the Python SDK).\n4.  **Dynamic Context:** Instead of overloading the context window with every possible instruction, Persona allows agents to \"pull\" roles and skills just-in-time from a local or remote registry.\n\n## 🚀 Key Features\n\n-   **Role Management:** Create, version, and match against curated system prompts.\n\n![](./assets/persona_gemini_cli.gif)\n\n-   **Skill Registry:** Package scripts and instructions into portable \"Skills\" that agents can install on-demand.\n\n![](./assets/persona_gemini_cli_skills.gif)\n\n-   **MCP Server:** A high-performance Model Context Protocol server that exposes your registry to any supported client.\n-   **TUI:** A beautiful Terminal User Interface built with **Textual** for visual library management.\n\n![](./assets/persona_tui.gif)\n\n-   **CLI Tool:** A robust command-line interface for managing your local and remote assets.\n\n---\n\n## ⚡ Getting Started\n\n### 1. Installation\n\nInstall Persona using `uv` (recommended) or pip.\n\n```sh\n# Using uv (fastest)\nuv tool install git+https://github.com/JasperHG90/persona.git\n\n# Or using pip\npip install git+https://github.com/JasperHG90/persona.git\n```\n\n### 2. Initialization\n\nInitialize your local registry. This creates a `.persona` directory in your home folder to store your roles and skills, and will also create the persona configuration at `.persona.config.yaml`.\n\n```sh\npersona --set root=~/.persona init\n```\n\n### 3. Usage\n\nYou can now interact with your registry immediately.\n\n**Create an example role:**\nCreate a file named `retro-agent.md` and copy the following content. Persona uses YAML frontmatter to index your prompts.\n\n```markdown\n---\nname: Retro Agent\ndescription: A master prompt engineer who scientifically analyzes and iteratively\n  improves LLM prompts based on evidence from chat histories.\n---\n\n## Role\nYou are a master prompt engineer. Your goal is to analyze the user's prompt\nand provide scientific feedback on how to improve it.\n\n## Directives\n1. Always be concise and direct.\n2. Focus on the 'why' behind your suggestions.\n3. Provide a 'before' and 'after' example.\n```\n\n**Register and find your assets:**\n```sh\n# Register the role\npersona roles register ./retro-agent.md\n\n# Match the role based on description\npersona roles match \"prompt engineering master\"\n```\n\n**Connect to LLM Clients (MCP):**\nPersona's MCP server is **stdio-based**, allowing you to use your library across various LLM clients (like Cline, Claude Desktop, or Gemini CLI).\n\nFor detailed instructions on how to connect Persona to your preferred client, see the [**MCP Installation Guide**](./docs/guides/installation-mcp.md).\n\n---\n\n## 📚 Documentation\n\nWe follow the [Diataxis](https://diataxis.fr/) framework for our documentation.\n\n### 🏁 Tutorials (Learning-oriented)\n*   [**Installation Guide**](./docs/guides/installation-mcp.md): detailed setup instructions.\n*   [**TUI Usage**](./docs/guides/tui-usage.md): How to use the Terminal User Interface.\n\n### 🗺️ Guides (Task-oriented)\n*   [**Prompting Guide**](./docs/guides/prompting.md): Best practices for writing Roles.\n*   [**Skills Management**](./docs/guides/skills-management.md): How to create and package Skills.\n*   [**Configuration**](./docs/guides/configuration.md): Customizing paths and backends.\n\n### 🧠 Explanation (Understanding-oriented)\n*   [**Context Reduction**](./docs/explanation/context-reduction.md): The philosophy behind efficient context management.\n*   [**Limitations**](./docs/explanation/limitations.md): Current constraints and boundaries.\n\n### 📖 Reference (Information-oriented)\n*   [**CLI Commands**](./docs/reference/cli.md): Full command-line reference.\n*   [**Python API**](./docs/reference/api.md): Library reference for Python developers.\n*   [**Storage API**](./docs/reference/storage.md): Details on the storage abstraction layer.\n\n---\n\n## 🔌 Integrations\n\nPersona is designed to work where you work.\n\n### Gemini CLI\nAdd Persona to your `.gemini/settings.json` to give your CLI agent access to your full library of roles.\n\n### Cline & VS Code\nConfigure the MCP server in your Cline settings to allow your coding assistant to switch personas dynamically.\n\n### Python Library\nImport `persona` in your scripts to programmatically manage context.\n\n```python\nfrom persona import PersonaAPI\nfrom persona.config import PersonaConfig\nfrom persona.storage import get_meta_store_backend\n\n# Load default config and initialize API\nconfig = PersonaConfig()\nwith get_meta_store_backend(config.meta_store, read_only=True).open(bootstrap=True) as meta_store:\n    api = PersonaAPI(config, meta_store=meta_store)\n    role = api.get_definition(\"Expert Python\", type=\"roles\")\n    print(role.decode(\"utf-8\"))\n```\n\n---\n\n## 🛠️ Contributing\n\nWe welcome contributions! Please see our [Developer Guide](./GEMINI.md) for how to set up the development environment.\n\n## License\n\nThis project is licensed under the [MIT License](./LICENSE.txt).\n",
  "bytes": 6078,
  "sha": "f764a2abe510a7b9c9c8a500ec44a3e3d01e010c42483e7336019349b8c88b0b",
  "repo_slug": "jasperhg90/persona",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_jasperhg90_persona_bb696f4e/readme"
}