Mental map

Learn PersonaKit

Place PersonaKit among prompts, skills, harnesses, MCP, CLI tools, and coding agents.

PersonaKit makes the most sense when you stop asking whether it replaces prompts, skills, memory, or compression. It does not. PersonaKit composes schema-backed project context into a resolved contract for the role, rules, stop points, allowed capabilities, and forbidden actions of a specific handoff.

That matters more as agents get better. A capable agent with good memory and useful skills can still do the wrong extra thing unless the active work mode is visible before the work begins.

Recommended path

Learn With ReleaseDesk

ReleaseDesk is the sample product: a tiny release-readiness dashboard with a real bug, a local readiness skill, and a completed PersonaKit root. Start by building its foundation, then continue with the same project through a normal engineering workday.

  1. Build The ReleaseDesk Foundation

    Fix the readiness bug, then add PersonaKit only when agent boundaries become useful.

    Start the product lab

  2. Continue Into The Workday

    Use that same ReleaseDesk project for review, approved follow-up, docs, and a host handoff. Return here after the foundation lab, or use the next-step card at the end of that tutorial.

    Next after foundation
Map the layers Use a host skill Read the contract Compose the pieces Turn a prompt into a contract Export handoff context

Map The Layers

Layer Plain Job PersonaKit Relationship
Prompt A one-time expression of intent. PersonaKit keeps durable rules out of the prompt so the task text can stay small.
Saved prompt Reusable text that still has to be copied or remembered. PersonaKit turns repeated setup into structured, inspectable, schema-backed project context.
Skill A local procedure, helper, or capability. Host skills teach procedures; PersonaKit declares whether those procedures are allowed or forbidden for a work mode.
Harness The wrapper that calls models, tools, or agent runtimes. PersonaKit deterministically produces the contract a harness can pass into the worker.
MCP A protocol surface for context, tools, prompts, and provenance. PersonaKit MCP exposes read-only grounding so clients can resolve contracts before action.
CLI The practical local interface for validation, inspection, and export. PersonaKit CLI proves the contract before another coding tool starts work.
Agent The worker that reads context and performs the task. PersonaKit prepares the agent. It does not become the agent.

Use A Host Skill As The Front Door

If your agent host supports skills, a small grounding skill can make PersonaKit easier to invoke through autocomplete, fuzzy search, or a command palette. The host skill is only the front door: it resolves the PersonaKit contract before action, and PersonaKit remains the authority for what is allowed.

Use $personakit-grounding to resolve the requested PersonaKit session before acting.

Open the PersonaKit grounding skill example

Read The Contract

A resolved contract answers the questions that usually get scattered through chat history.

Who Is Working?

The persona defines responsibilities, values, and non-goals.

What Kind Of Work?

The directive defines steps, acceptance criteria, verification, and stop points.

Which Rules Apply?

Kits and essentials carry durable project guidance into the resolved payload.

Which Capabilities Are Allowed?

Skill authorization makes allowed and forbidden capabilities visible before work begins.

Compose The Pieces

You define a session as the entry point. PersonaKit composes reusable parts into the resolved contract. Operators should not have to copy the same careful-review paragraph into every prompt or maintain several nearly identical skills just to change a boundary.

Persona

Who is acting.

Directive

What kind of work this is.

Kit

Rules that should travel across related sessions.

Intent

Reusable work patterns and decision rails required by kits or directives.

Essentials

Required grounding that belongs in the resolved payload.

Skills

Capabilities that may be authorized or forbidden for this lane.

Session

The composed lane that selects the pieces to resolve together.

Review Composition Example

Review work shows why the pieces stay separate:

Composition Result
behavior-reviewer + behavior-preserving-review The existing read-only review lane reports findings without becoming the implementer.
Same reviewer + a different directive and session A conceptual implementation-after-approval lane could be separate instead of mutating the read-only lane.
Shared review kit or essential Review discipline can travel across lanes without being pasted into each task prompt.
Same skill catalog, different sessions A capability can stay reusable while authorization is decided by the resolved contract.

Turn A Prompt Into A Contract

Start with a loose prompt:

Review this bugfix carefully. Stay read-only. Watch for behavior changes and missing tests. Do not edit code unless I approve a fix.

PersonaKit asks which parts are durable enough to become reusable structure:

Prompt Fragment Contract Piece
Review this bugfix carefully. Persona: behavior reviewer.
Stay read-only. Skill boundary: authorize review, forbid editing.
Watch for behavior changes and missing tests. Directive: review steps and acceptance criteria.
Do not edit code unless I approve a fix. Stop point: implementation requires operator approval.

The next prompt can shrink because the contract carries the repeated setup:

Operate under behavior-review. Review the current diff and report findings.

Study the review-session example

Export Handoff Context

The practical loop is small and inspectable:

  1. Validate the authored PersonaKit root.
  2. Resolve the session contract.
  3. Inspect or export the context.
  4. Copy the exported grounding into the coding tool you use for the actual work.
personakit validate --root .personakit
personakit contract --root .personakit --session behavior-review
personakit export --root .personakit --session behavior-review

Start the ReleaseDesk tutorial