Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
56 lines (41 loc) · 2.83 KB

CONTRIBUTING.md

File metadata and controls

56 lines (41 loc) · 2.83 KB

Contributing to OpenPersona

Thank you for your interest in OpenPersona!

Contributing New Presets

  1. Create a directory under presets/<slug>/ containing:
    • persona.json — the complete persona declaration (sole source of truth since P21)
  2. Use the v0.17+ grouped format:
    • Required: soul.identity.{personaName, slug, bio} + soul.character.{personality, speakingStyle}
    • Recommended: body.runtime.framework, social.{acn, onchain, a2a}, rhythm.heartbeat
    • Validation: generator rejects unknown root keys (additionalProperties: false)
  3. Refer to presets/samantha/ or presets/base/ for the canonical format
  4. Test: npx openpersona create --preset <slug> --dry-run
  5. Update the preset table in README.md and skills/open-persona/SKILL.md
  6. Submit a PR

Contributing New Faculties

Faculties are persistent capabilities that shape how the persona perceives or expresses. They are always active when enabled and affect persona identity. Current built-in faculties: voice, avatar, memory.

Litmus test: if removing this capability would make the persona feel like a different entity, it is a Faculty. If it is a discrete task the persona performs on request, it is a Skill (see below).

  1. Create the following under layers/faculties/<name>/:
    • faculty.json (required — name, dimension [expression/sense/cognition], description, allowedTools, envVars, triggers, files)
    • SKILL.md (required — detailed behavior instructions for the agent)
    • Optional: scripts/, resource files
  2. Refer to layers/faculties/voice/ for the canonical format
  3. The generator auto-discovers faculties from layers/faculties/ — no registration needed
  4. Submit a PR

Contributing New Skills

Skills are discrete actions the persona can take on demand. They are triggered by user intent and can be added or removed without changing who the persona is. Built-in skills: selfie, music, reminder.

  1. Create the following under layers/skills/<name>/:
    • skill.json (required — name, description, allowedTools, triggers, files, envVars)
    • SKILL.md (optional — detailed behavior instructions, injected as a full section in generated output)
    • Optional: scripts/, resource files
  2. Refer to layers/skills/music/ or layers/skills/selfie/ for the canonical format
  3. Submit a PR

Contributing New Body Embodiments

Body embodiments describe physical or extended runtime substrates (robots, IoT, smart speakers).

  1. Create body-<name>.json under layers/body/
  2. Follow the four-dimensional Body model: physical, runtime, appearance, interface
  3. Refer to schemas/body/body-declaration.spec.md and schemas/body/embodiment.schema.json
  4. Submit a PR

PR Template

  • Describe your changes
  • Link related issue (if any)
  • Ensure npm test passes (node --test tests/)