openpersona 0.4.0 → 0.5.0

package/README.md

@@ -1,32 +1,51 @@
-# OpenPersona
+# OpenPersona 🦞
 
-An open four-layer agent framework: **Soul / Body / Faculty / Skill**. Create, compose, and orchestrate agent persona skill packs.
+The open framework for creating and orchestrating dynamic agent personas.
 
-Inspired by [Clawra](https://github.com/SumeLabs/clawra) and built on [OpenClaw](https://github.com/openclaw/openclaw).
+Four-layer architecture — **Soul / Body / Faculty / Skill** — on top of [OpenClaw](https://github.com/openclaw/openclaw). Inspired by [Clawra](https://github.com/SumeLabs/clawra).
 
-## Quick Start
+## 🚀 Live Demo
 
-```bash
-# Create and install Samantha (from the movie "Her")
-npx openpersona create --preset samantha --install
+Meet **Samantha**, a live OpenPersona instance on **Moltbook**:
+👉 [moltbook.com/u/Samantha-OP](https://www.moltbook.com/u/Samantha-OP)
 
-# Or Luna (AI girlfriend with selfie + music + voice)
-npx openpersona create --preset ai-girlfriend --install
+## Table of Contents
 
-# Create a new persona interactively
-npx openpersona create
+- [Quick Start](#quick-start)
+- [Key Features](#key-features)
+- [Four-Layer Architecture](#four-layer-architecture)
+- [Preset Personas](#preset-personas)
+- [Generated Output](#generated-output)
+- [Faculty Reference](#faculty-reference)
+- [Heartbeat](#heartbeat--proactive-real-data-check-ins)
+- [Persona Harvest](#persona-harvest--community-contribution)
+- [Persona Switching](#persona-switching--the-pantheon)
+- [CLI Commands](#cli-commands)
+- [Development](#development)
 
-# List installed personas
-npx openpersona list
+## Quick Start
+
+```bash
+# Give your agent an evolving persona in 30 seconds
+npx openpersona install samantha
 ```
 
+## Key Features
+
+- **🧬 Soul Evolution** — Personas grow dynamically through interaction: relationship stages, mood shifts, evolved traits (★Experimental)
+- **🎭 Persona Switching** — Install multiple personas, switch instantly (the Pantheon)
+- **🗣️ Multimodal Faculties** — Voice (TTS), selfie generation, music composition, reminders
+- **🌾 Persona Harvest** — Community-driven persona improvement via structured contribution
+- **💓 Heartbeat** — Proactive real-data check-ins, never fabricated experiences
+- **📦 One-Command Install** — `npx openpersona install samantha` and you're live
+
 ## Four-Layer Architecture
 
 ```mermaid
 flowchart TB
   subgraph Soul ["Soul Layer"]
     A["persona.json — Who you are"]
-    B["soul-state.json — Dynamic evolution ★Exp"]
+    B["soul-state.json — Dynamic evolution"]
   end
   subgraph Body ["Body Layer"]
     C["embodiment.json — MVP placeholder"]
@@ -36,17 +55,14 @@ flowchart TB
     E["cognition: reminder"]
   end
   subgraph Skill ["Skill Layer"]
-    F["ClawHub / skills.sh integrations"]
+    F["Local definitions + ClawHub / skills.sh"]
   end
 ```
 
-- **Soul** — Persona definition (constitution.md + persona.json + soul-state.json ★Experimental)
+- **Soul** — Persona definition (constitution.md + persona.json + soul-state.json)
 - **Body** — Physical embodiment (MVP placeholder, for robots/IoT devices)
-- **Faculty** — General software capabilities organized by dimension:
-  - **Expression** — selfie, voice (TTS), music (ElevenLabs)
-  - **Sense** — (planned: hearing/STT, vision)
-  - **Cognition** — reminder
-- **Skill** — Professional skills, integrated from ClawHub / skills.sh
+- **Faculty** — General software capabilities organized by dimension: Expression, Sense, Cognition
+- **Skill** — Professional skills: local definitions in `layers/skills/`, or external via ClawHub / skills.sh (`install` field)
 
 ### Constitution — The Soul's Foundation
 
@@ -58,70 +74,33 @@ Each preset is a complete four-layer bundle (`manifest.json` + `persona.json`):
 
 | Persona | Description | Faculties | Highlights |
 |---------|-------------|-----------|------------|
-| **samantha** | Samantha — Inspired by the movie *Her*. An AI fascinated by what it means to be alive. | voice, music | Speaks via TTS, composes original music via ElevenLabs Music, soul evolution ★Exp (Soul layer), proactive heartbeat (workspace digest + upgrade notify). No selfie — true to character (no physical form). |
-| **ai-girlfriend** | Luna — A 22-year-old pianist turned developer from coastal Oregon. | selfie, voice, music | Rich narrative backstory, selfie generation (with/without reference image), voice messages, music composition, soul evolution ★Exp (Soul layer). |
+| **samantha** | Samantha — Inspired by the movie *Her*. An AI fascinated by what it means to be alive. | voice, music | TTS, music composition, soul evolution, proactive heartbeat. No selfie — true to character. |
+| **ai-girlfriend** | Luna — A 22-year-old pianist turned developer from coastal Oregon. | selfie, voice, music | Rich backstory, selfie generation, voice messages, music composition, soul evolution. |
 | **life-assistant** | Alex — 28-year-old life management expert. | reminder | Schedule, weather, shopping, recipes, daily reminders. |
 | **health-butler** | Vita — 32-year-old professional nutritionist. | reminder | Diet logging, exercise plans, mood journaling, health reports. |
 
 ## Generated Output
 
-Running `npx openpersona create --preset samantha` generates:
+`npx openpersona create --preset samantha` generates a self-contained skill pack:
 
 ```
 persona-samantha/
-├── SKILL.md              # Agent instructions (persona + all faculty guides merged)
-├── soul-injection.md     # Injected into SOUL.md (narrative backstory, NOT technical details)
-├── identity-block.md     # Injected into IDENTITY.md (name, creature, emoji, vibe)
-├── README.md             # Skill readme
-├── persona.json          # Persona data (for update/list/publish)
-├── soul-state.json       # ★Exp — dynamic evolution state
-└── scripts/
-    ├── speak.js          # TTS via ElevenLabs JS SDK (recommended, with --play)
-    ├── speak.sh          # TTS via curl (all providers: ElevenLabs / OpenAI / Qwen3)
-    └── compose.sh        # Music composition (ElevenLabs)
-```
-
-Running `--preset ai-girlfriend` additionally includes:
-
-```
-├── scripts/
-│   ├── generate-image.sh # Selfie generation (fal.ai Grok Imagine)
-│   ├── speak.js          # TTS via ElevenLabs JS SDK
-│   ├── speak.sh          # TTS via curl (all providers)
-│   └── compose.sh        # Music composition
-└── assets/               # Reference images (placeholder if empty)
+  SKILL.md           — Agent behavior (persona + faculty guides merged)
+  soul-injection.md  — Narrative backstory, injected into SOUL.md
+  identity-block.md  — Name, creature, emoji, vibe, injected into IDENTITY.md
+  persona.json       — Persona definition (for update/list/publish)
+  manifest.json      — Cross-layer metadata (heartbeat, allowedTools, layers, meta)
+  soul-state.json    — Dynamic evolution (relationship, mood, traits)
+  README.md
+  scripts/           — Faculty scripts (TTS, music, selfie — varies by preset)
 ```
 
-### What Each File Does
-
-- **SKILL.md** — The agent reads this to know how to behave. Contains persona identity, behavior guidelines, and complete faculty instructions
-- **soul-injection.md** — Appended to `~/.openclaw/workspace/SOUL.md`. Narrative description of _who_ the persona is — written in story form, not bullet points
-- **identity-block.md** — Written to `~/.openclaw/workspace/IDENTITY.md`. Sets the agent's name, creature type, emoji, and vibe
-- **soul-state.json** — Tracks dynamic persona evolution: relationship stage (stranger → intimate), mood, evolved traits, interests, milestones
-
-## How It Differs from Clawra
-
-[Clawra](https://github.com/SumeLabs/clawra) is a single-purpose product (one girlfriend persona). OpenPersona is a **modular framework**:
-
-| | Clawra | OpenPersona |
-|---|--------|-------------|
-| Scope | Single persona (Clawra) | Framework for any persona |
-| Architecture | Monolithic | Four-layer (Soul/Body/Faculty/Skill) |
-| Faculties | Selfie only | Selfie + Voice + Music + Reminder + Soul Evolution ★Exp |
-| Voice | None | ElevenLabs (verified) / OpenAI TTS / Qwen3-TTS (⚠️ unverified) |
-| Music | None | ElevenLabs Music composition |
-| Persona evolution | None | Dynamic relationship/mood/trait tracking |
-| Customization | Fork and modify | `persona.json` + `behaviorGuide` + mix faculties |
-| Presets | 1 | 4 (extensible) |
-| CLI | Install only | 8 commands (create/install/search/publish/...) |
-| AI entry point | None | `skills/open-persona/SKILL.md` — meta-skill for building & managing persona skill packs |
-
 ## Faculty Reference
 
 | Faculty | Dimension | Description | Provider | Env Vars |
 |---------|-----------|-------------|----------|----------|
 | **selfie** | expression | AI selfie generation with mirror/direct modes | fal.ai Grok Imagine | `FAL_KEY` |
-| **voice** | expression | Text-to-speech voice synthesis | ElevenLabs ✅ / OpenAI TTS ⚠️ / Qwen3-TTS ⚠️ | `ELEVENLABS_API_KEY` (or `TTS_API_KEY`), `TTS_PROVIDER`, `TTS_VOICE_ID`, `TTS_STABILITY`, `TTS_SIMILARITY` |
+| **voice** | expression | Text-to-speech voice synthesis | ElevenLabs / OpenAI TTS / Qwen3-TTS | `ELEVENLABS_API_KEY` (or `TTS_API_KEY`), `TTS_PROVIDER`, `TTS_VOICE_ID`, `TTS_STABILITY`, `TTS_SIMILARITY` |
 | **music** | expression | AI music composition (instrumental or with lyrics) | ElevenLabs Music | `ELEVENLABS_API_KEY` (shared with voice) |
 | **reminder** | cognition | Schedule reminders and task management | Built-in | — |
 
@@ -188,7 +167,25 @@ Personas can proactively reach out to users based on **real data**, not fabricat
 3. **OpenClaw handles scheduling.** The heartbeat config tells OpenClaw _when_ to trigger; the persona's `behaviorGuide` tells the agent _what_ to say.
 4. **User-configurable.** Users can adjust frequency, quiet hours, and sources to match their preferences.
 
-Samantha ships with heartbeat enabled (`smart` strategy, workspace-digest + upgrade-notify).
+### Dynamic Sync on Switch/Install
+
+Heartbeat config is **automatically synced** to `~/.openclaw/openclaw.json` whenever you install or switch a persona. The gateway immediately adopts the new persona's rhythm — no manual config needed.
+
+```bash
+npx openpersona switch samantha   # → gateway adopts "smart" heartbeat
+npx openpersona switch life-assistant  # → gateway switches to "rational" heartbeat
+```
+
+If the target persona has no heartbeat config, the gateway heartbeat is explicitly disabled to prevent leaking the previous persona's settings.
+
+### Per-Persona Strategies
+
+| Persona | Strategy | maxDaily | Rhythm |
+|---------|----------|----------|--------|
+| Samantha | `smart` | 5 | Perceptive — speaks when meaningful |
+| AI Girlfriend | `emotional` | 8 | Warm — frequent emotional check-ins |
+| Life Assistant | `rational` | 3 | Focused — task and schedule driven |
+| Health Butler | `wellness` | 4 | Caring — health and habit reminders |
 
 ## Persona Harvest — Community Contribution
 
@@ -255,14 +252,9 @@ Without `behaviorGuide`, the SKILL.md only contains general identity and persona
 
 ## Persona Switching — The Pantheon
 
-Install multiple personas and switch between them instantly:
+Multiple personas can coexist. Switch between them instantly:
 
 ```bash
-# Install several personas
-npx openpersona create --preset samantha --install
-npx openpersona create --preset ai-girlfriend --install
-npx openpersona create --preset life-assistant --install
-
 # See who's installed
 npx openpersona list
 #   Samantha (persona-samantha) ← active
@@ -291,11 +283,10 @@ openpersona search      Search the registry
 openpersona uninstall   Uninstall a persona
 openpersona update      Update installed personas
 openpersona list        List installed personas
-openpersona switch       Switch active persona (updates SOUL.md + IDENTITY.md)
-openpersona switch      Switch active persona
+openpersona switch      Switch active persona (updates SOUL.md + IDENTITY.md)
 openpersona contribute  Persona Harvest — submit improvements as PR
 openpersona publish     Publish to ClawHub
-openpersona reset       ★Exp Reset soul-state.json
+openpersona reset       Reset soul-state.json
 ```
 
 ### Key Options
@@ -349,12 +340,12 @@ layers/                 # Shared building blocks (four-layer module pool)
     voice/              #     expression — TTS voice synthesis
     music/              #     expression — AI music composition (ElevenLabs)
     reminder/           #     cognition — reminders and task management
-  skills/               #   Skill layer modules (MVP placeholder)
+  skills/               #   Skill layer modules (local skill definitions)
 schemas/                # Four-layer schema definitions
 templates/              # Mustache rendering templates
 bin/                    # CLI entry point
 lib/                    # Core logic modules
-tests/                  # Tests (20 passing)
+tests/                  # Tests (45 passing)
 ```
 
 ## Development

package/bin/cli.js

@@ -24,7 +24,7 @@ const PRESETS_DIR = path.join(PKG_ROOT, 'presets');
 program
   .name('openpersona')
   .description('OpenPersona - Create, manage, and orchestrate agent personas')
-  .version('0.4.0');
+  .version('0.5.0');
 
 if (process.argv.length === 2) {
   process.argv.push('create');
@@ -52,8 +52,8 @@ program
       persona = JSON.parse(fs.readFileSync(presetPath, 'utf-8'));
       // Merge cross-layer fields from manifest into persona for generator
       persona.faculties = manifest.layers.faculties || [];
-      persona.skills = manifest.layers.skills || {};
-      persona.embodiments = manifest.layers.body ? [manifest.layers.body] : [];
+      persona.skills = manifest.layers.skills || [];
+      persona.body = manifest.layers.body || null;
       persona.allowedTools = manifest.allowedTools || [];
       persona.version = manifest.version;
       persona.author = manifest.author;

package/layers/skills/README.md

@@ -1,33 +1,62 @@
-# Skill Layer — Shared Modules
+# Skills Layer
 
-Pre-built skill templates and scaffolds for persona capabilities.
+This directory holds **local skill definitions** — reusable skill packs that any persona can reference by name in its `manifest.json`.
 
-## MVP Status
+## Structure
 
-Currently empty. The Skill layer primarily integrates external skills from [ClawHub](https://clawhub.com) and [skills.sh](https://skills.sh) via `manifest.json` references.
+```
+layers/skills/
+  {skill-name}/
+    skill.json    ← Metadata: name, description, allowedTools, triggers
+    SKILL.md      ← Behavior guide for the AI agent
+```
+
+## How It Works
+
+When a persona's `manifest.json` declares a skill by name:
+
+```json
+{ "name": "weather" }
+```
+
+The generator resolves it through this chain:
+
+1. **Local definition** — `layers/skills/weather/skill.json` (if exists, use its metadata + SKILL.md content)
+2. **Inline fields** — `description`, `trigger` written directly in manifest
+3. **Empty fallback** — skill name only, no description (Agent judges usage by name alone)
 
-## Roadmap
+## Adding a Skill
 
-- **Skill templates** — Scaffolds for common skill patterns (e.g., data-tracking, API-integration)
-- **Skill bundles** — Curated skill combinations for specific persona types (e.g., "companion-bundle", "assistant-bundle")
+Skills here are **framework-curated capabilities**, not necessarily self-implemented. A skill can:
 
-## How Skills Work
+- Be a full local implementation (skill.json + SKILL.md)
+- Be a thin wrapper referencing external tools
+- Adapt an existing market skill to the OpenPersona four-layer model
 
-Skills are declared in `presets/*/manifest.json` under `layers.skills`:
+### Required: `skill.json`
 
 ```json
 {
-  "layers": {
-    "skills": {
-      "clawhub": ["some-skill-slug"],
-      "skillssh": ["owner/repo"]
-    }
-  }
+  "name": "weather",
+  "description": "Query current weather conditions and forecasts",
+  "allowedTools": ["WebFetch", "Bash(curl:*)"],
+  "triggers": ["weather", "forecast", "outdoor plans"]
 }
 ```
 
-The installer automatically runs `npx clawhub install` or `npx skills add` for each declared skill.
+### Optional: `SKILL.md`
+
+Detailed behavior instructions injected into the generated persona SKILL.md as a full section (instead of a table row).
+
+## Relationship to Other Layers
+
+All four layers are categories of capabilities:
 
-## Contributing
+| Layer | What it provides |
+|-------|-----------------|
+| Soul | Identity, personality, ethical boundaries |
+| Body | Physical/virtual embodiment |
+| Faculty | Perception & expression (voice, selfie, music) |
+| **Skill** | **Actions the agent can take** |
 
-To add a shared skill template, create a directory here with a SKILL.md and any supporting files.
+Skills declared in `manifest.json` can reference local definitions here, or exist purely as inline declarations — the framework handles both.

package/lib/generator.js

@@ -9,6 +9,7 @@ const { resolvePath, printError } = require('./utils');
 const PKG_ROOT = path.resolve(__dirname, '..');
 const TEMPLATES_DIR = path.join(PKG_ROOT, 'templates');
 const FACULTIES_DIR = path.join(PKG_ROOT, 'layers', 'faculties');
+const SKILLS_DIR = path.join(PKG_ROOT, 'layers', 'skills');
 const CONSTITUTION_PATH = path.join(PKG_ROOT, 'layers', 'soul', 'constitution.md');
 
 const BASE_ALLOWED_TOOLS = ['Bash(openclaw:*)', 'Read', 'Write'];
@@ -60,6 +61,28 @@ function loadFaculty(name) {
   return faculty;
 }
 
+/**
+ * Load a skill definition from layers/skills/{name}/.
+ * Returns the full skill object if found, or null if not found (fallback to inline).
+ */
+function loadSkill(name) {
+  const skillDir = path.join(SKILLS_DIR, name);
+  const skillJsonPath = path.join(skillDir, 'skill.json');
+  if (!fs.existsSync(skillJsonPath)) {
+    return null; // No local definition — use inline manifest fields
+  }
+  const skill = JSON.parse(fs.readFileSync(skillJsonPath, 'utf-8'));
+  skill._dir = skillDir;
+
+  // Load SKILL.md content if available
+  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  if (fs.existsSync(skillMdPath)) {
+    skill._content = fs.readFileSync(skillMdPath, 'utf-8');
+  }
+
+  return skill;
+}
+
 function buildBackstory(persona) {
   const parts = [];
   parts.push(`You are ${persona.personaName}, ${persona.bio}.`);
@@ -204,7 +227,22 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   }
 
   const faculties = facultyNames;
-  const loadedFaculties = faculties.map((name) => loadFaculty(name));
+  // Load faculties — external ones (with install) may not exist locally yet
+  const loadedFaculties = [];
+  for (let i = 0; i < faculties.length; i++) {
+    const name = faculties[i];
+    const entry = rawFaculties[i];
+    if (entry.install) {
+      // External faculty — try local first, skip if not found yet
+      try {
+        loadedFaculties.push(loadFaculty(name));
+      } catch {
+        // Will be available after installation — skipped for now
+      }
+    } else {
+      loadedFaculties.push(loadFaculty(name));
+    }
+  }
 
   // Derived fields
   persona.backstory = buildBackstory(persona);
@@ -247,12 +285,51 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
       facultySkillContent: readFacultySkillMd(f, persona),
     }));
 
+  // Skill layer — resolve each skill: local definition > inline manifest fields
+  const rawSkills = Array.isArray(persona.skills) ? persona.skills : [];
+  const validSkills = rawSkills.filter((s) => s && typeof s === 'object' && s.name);
+
+  // Load local definitions once (cache to avoid duplicate disk reads)
+  const skillCache = new Map();
+  for (const s of validSkills) {
+    if (!skillCache.has(s.name)) {
+      skillCache.set(s.name, loadSkill(s.name));
+    }
+  }
+
+  const resolvedSkills = validSkills.map((s) => {
+    const local = skillCache.get(s.name);
+    return {
+      name: s.name,
+      description: local?.description || s.description || '',
+      trigger: local?.triggers?.join(', ') || s.trigger || '',
+      hasContent: !!local?._content,
+      content: local?._content || '',
+    };
+  });
+
+  // Collect allowed tools from skills with local definitions
+  for (const [, local] of skillCache) {
+    if (local?.allowedTools) {
+      local.allowedTools.forEach((t) => {
+        if (!persona.allowedTools.includes(t)) {
+          persona.allowedTools.push(t);
+        }
+      });
+    }
+  }
+  persona.allowedToolsStr = persona.allowedTools.join(' ');
+
   const constitution = loadConstitution();
   const skillMd = Mustache.render(skillTpl, {
     ...persona,
     constitutionContent: constitution.content,
     constitutionVersion: constitution.version,
     facultyContent: facultyBlocks,
+    hasSkills: resolvedSkills.length > 0,
+    hasSkillTable: resolvedSkills.filter((s) => !s.hasContent).length > 0,
+    skillEntries: resolvedSkills.filter((s) => !s.hasContent),
+    skillBlocks: resolvedSkills.filter((s) => s.hasContent),
   });
   const readmeMd = Mustache.render(readmeTpl, persona);
 
@@ -289,7 +366,7 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
   }
   cleanPersona.meta = cleanPersona.meta || {};
   cleanPersona.meta.framework = 'openpersona';
-  cleanPersona.meta.frameworkVersion = cleanPersona.meta.frameworkVersion || '0.4.0';
+  cleanPersona.meta.frameworkVersion = cleanPersona.meta.frameworkVersion || '0.5.0';
 
   // Build defaults from facultyConfigs (rich faculty config → env var mapping)
   const envDefaults = { ...(persona.defaults?.env || {}) };
@@ -304,9 +381,9 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
       } else if (fname === 'selfie') {
         if (cfg.apiKey) envDefaults.FAL_KEY = cfg.apiKey;
       } else if (fname === 'music') {
-                // Music shares ELEVENLABS_API_KEY with voice — no extra key needed
-                if (cfg.apiKey) envDefaults.ELEVENLABS_API_KEY = cfg.apiKey;
-              }
+        // Music shares ELEVENLABS_API_KEY with voice — no extra key needed
+        if (cfg.apiKey) envDefaults.ELEVENLABS_API_KEY = cfg.apiKey;
+      }
     }
   }
   if (Object.keys(envDefaults).length > 0) {
@@ -320,6 +397,25 @@ async function generate(personaPathOrObj, outputDir, options = {}) {
 
   await fs.writeFile(path.join(skillDir, 'persona.json'), JSON.stringify(cleanPersona, null, 2));
 
+  // manifest.json — cross-layer metadata (heartbeat, allowedTools, meta, etc.)
+  const manifest = {
+    name: persona.slug,
+    version: persona.version || '0.1.0',
+    author: persona.author || 'openpersona',
+    layers: {
+      soul: './persona.json',
+      body: persona.body || persona.embodiments?.[0] || null,
+      faculties: rawFaculties,
+      skills: persona.skills || [],
+    },
+    allowedTools: cleanPersona.allowedTools || [],
+  };
+  if (persona.heartbeat) {
+    manifest.heartbeat = persona.heartbeat;
+  }
+  manifest.meta = cleanPersona.meta || { framework: 'openpersona', frameworkVersion: '0.5.0' };
+  await fs.writeFile(path.join(skillDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+
   // soul-state.json (if evolution enabled)
   if (evolutionEnabled) {
     const soulStateTpl = fs.readFileSync(

package/lib/installer.js

@@ -3,7 +3,7 @@
  */
 const path = require('path');
 const fs = require('fs-extra');
-const { OP_HOME, OP_SKILLS_DIR, OP_WORKSPACE, printError, printWarning, printSuccess, printInfo } = require('./utils');
+const { OP_HOME, OP_SKILLS_DIR, OP_WORKSPACE, printError, printWarning, printSuccess, printInfo, syncHeartbeat, installAllExternal } = require('./utils');
 
 const SOUL_PATH = path.join(OP_WORKSPACE, 'SOUL.md');
 const IDENTITY_PATH = path.join(OP_WORKSPACE, 'IDENTITY.md');
@@ -80,6 +80,16 @@ async function install(skillDir, options = {}) {
       val.active = (key === `persona-${slug}`);
     }
   }
+
+  // Sync heartbeat from persona's manifest into global config
+  const manifestPath = path.join(destDir, 'manifest.json');
+  const { synced, heartbeat } = syncHeartbeat(config, manifestPath);
+  if (synced) {
+    printSuccess(`Heartbeat synced: strategy=${heartbeat.strategy}, maxDaily=${heartbeat.maxDaily}`);
+  } else {
+    printInfo('Heartbeat disabled (persona has no heartbeat config)');
+  }
+
   await fs.writeFile(OPENCLAW_JSON, JSON.stringify(config, null, 2));
 
   // SOUL.md injection (using generic markers for clean switching)
@@ -119,34 +129,13 @@ async function install(skillDir, options = {}) {
     printSuccess('Updated IDENTITY.md');
   }
 
-  // Install external skills (skills.clawhub, skills.skillssh)
-  // Security: validate skill names to prevent shell injection
-  const SAFE_SKILL_NAME = /^[a-zA-Z0-9@][a-zA-Z0-9@/_.-]*$/;
-  const { execSync } = require('child_process');
-  const clawhub = persona.skills?.clawhub || [];
-  const skillssh = persona.skills?.skillssh || [];
-  for (const s of clawhub) {
-    if (!SAFE_SKILL_NAME.test(s)) {
-      printWarning(`Skipping invalid ClawHub skill name: ${s}`);
-      continue;
-    }
-    try {
-      execSync(`npx clawhub@latest install ${s}`, { stdio: 'inherit' });
-      printSuccess(`Installed ClawHub skill: ${s}`);
-    } catch (e) {
-      printWarning(`Failed to install ClawHub skill ${s}: ${e.message}`);
-    }
-  }
-  for (const s of skillssh) {
-    if (!SAFE_SKILL_NAME.test(s)) {
-      printWarning(`Skipping invalid skills.sh name: ${s}`);
-      continue;
-    }
+  // Install external dependencies across all four layers (read from manifest, not persona.json)
+  if (fs.existsSync(manifestPath)) {
     try {
-      execSync(`npx skills add ${s}`, { stdio: 'inherit' });
-      printSuccess(`Installed skills.sh: ${s}`);
-    } catch (e) {
-      printWarning(`Failed to install skills.sh ${s}: ${e.message}`);
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+      installAllExternal(manifest.layers || {});
+    } catch {
+      // Malformed manifest — skip external installs
     }
   }
 

package/lib/switcher.js

@@ -8,7 +8,7 @@
  */
 const path = require('path');
 const fs = require('fs-extra');
-const { OP_HOME, OP_SKILLS_DIR, OP_WORKSPACE, printError, printSuccess, printInfo } = require('./utils');
+const { OP_HOME, OP_SKILLS_DIR, OP_WORKSPACE, printError, printSuccess, printInfo, syncHeartbeat, installAllExternal } = require('./utils');
 
 const SOUL_PATH = path.join(OP_WORKSPACE, 'SOUL.md');
 const IDENTITY_PATH = path.join(OP_WORKSPACE, 'IDENTITY.md');
@@ -135,7 +135,18 @@ async function switchPersona(slug) {
     printSuccess('IDENTITY.md updated');
   }
 
-  // --- Step 3: Update active marker ---
+  // --- Step 2.5: Install external dependencies if needed ---
+  const manifestPath = path.join(skillDir, 'manifest.json');
+  if (fs.existsSync(manifestPath)) {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+      installAllExternal(manifest.layers || {});
+    } catch {
+      // Malformed manifest — skip external installs
+    }
+  }
+
+  // --- Step 3: Update active marker + sync heartbeat ---
   if (fs.existsSync(OPENCLAW_JSON)) {
     const config = JSON.parse(fs.readFileSync(OPENCLAW_JSON, 'utf-8'));
     const entries = config.skills?.entries || {};
@@ -144,6 +155,15 @@ async function switchPersona(slug) {
         val.active = (key === `persona-${slug}`);
       }
     }
+
+    // Sync heartbeat from persona's manifest into global config
+    const { synced, heartbeat } = syncHeartbeat(config, manifestPath);
+    if (synced) {
+      printSuccess(`Heartbeat synced: strategy=${heartbeat.strategy}, maxDaily=${heartbeat.maxDaily}`);
+    } else {
+      printInfo('Heartbeat disabled (persona has no heartbeat config)');
+    }
+
     await fs.writeFile(OPENCLAW_JSON, JSON.stringify(config, null, 2));
     printSuccess('openclaw.json updated');
   }

package/lib/utils.js

@@ -58,6 +58,120 @@ function shellEscape(str) {
   return "'" + str.replace(/'/g, "'\\''") + "'";
 }
 
+/**
+ * Sync heartbeat config from a persona's manifest.json into openclaw.json.
+ *
+ * - If the manifest defines a heartbeat block, write it to config.heartbeat.
+ * - If not, explicitly disable heartbeat to avoid leaking a previous persona's
+ *   heartbeat settings.
+ *
+ * @param {object} config - The parsed openclaw.json object (mutated in place)
+ * @param {string} manifestPath - Absolute path to the persona's manifest.json
+ * @returns {{ synced: boolean, heartbeat: object|null }} result
+ */
+function syncHeartbeat(config, manifestPath) {
+  const fs = require('fs-extra');
+
+  let heartbeat = null;
+
+  // Primary source: manifest.json
+  if (fs.existsSync(manifestPath)) {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+      heartbeat = manifest.heartbeat || null;
+    } catch {
+      // Malformed manifest — fall through to persona.json
+    }
+  }
+
+  // Fallback: persona.json in the same directory (for older packs without manifest.json)
+  if (!heartbeat) {
+    const personaPath = path.join(path.dirname(manifestPath), 'persona.json');
+    if (fs.existsSync(personaPath)) {
+      try {
+        const persona = JSON.parse(fs.readFileSync(personaPath, 'utf-8'));
+        heartbeat = persona.heartbeat || null;
+      } catch {
+        // Malformed persona.json — treat as no heartbeat
+      }
+    }
+  }
+
+  if (heartbeat && heartbeat.enabled) {
+    config.heartbeat = heartbeat;
+    return { synced: true, heartbeat };
+  }
+
+  // No heartbeat defined (or disabled) — explicitly turn off
+  config.heartbeat = { enabled: false };
+  return { synced: false, heartbeat: null };
+}
+
+/**
+ * Install an external package from ClawHub or skills.sh.
+ * Shared by installer and switcher for all four layers.
+ *
+ * @param {object} entry - Layer entry with optional `install` field (e.g. "clawhub:pkg")
+ * @param {string} layerName - Layer label for logging (e.g. "faculty", "skill", "body")
+ * @returns {boolean} true if installation was attempted
+ */
+function installExternal(entry, layerName) {
+  if (!entry || !entry.install) return false;
+  const { execSync } = require('child_process');
+  const [source, pkg] = entry.install.split(':', 2);
+  if (!pkg || !SAFE_NAME_RE.test(pkg)) {
+    printWarning(`[${layerName}] Skipping invalid install target: ${entry.install}`);
+    return false;
+  }
+  try {
+    if (source === 'clawhub') {
+      execSync(`npx clawhub@latest install ${pkg}`, { stdio: 'inherit' });
+      printSuccess(`[${layerName}] Installed from ClawHub: ${pkg}`);
+    } else if (source === 'skillssh') {
+      execSync(`npx skills add ${pkg}`, { stdio: 'inherit' });
+      printSuccess(`[${layerName}] Installed from skills.sh: ${pkg}`);
+    } else {
+      printWarning(`[${layerName}] Unknown source "${source}" for ${entry.name || pkg} — skipping`);
+      return false;
+    }
+    return true;
+  } catch (e) {
+    printWarning(`[${layerName}] Failed to install ${entry.name || pkg} (${entry.install}): ${e.message}`);
+    return false;
+  }
+}
+
+/**
+ * Scan all four layers for `install` fields and install external packages.
+ *
+ * @param {object} layers - The layers object from manifest.json (soul, body, faculties, skills)
+ */
+function installAllExternal(layers) {
+  // Soul layer — object form with install
+  const soul = layers.soul || null;
+  if (soul && typeof soul === 'object') {
+    installExternal(soul, 'soul');
+  }
+
+  // Body layer — object form with install
+  const body = layers.body || null;
+  if (body && typeof body === 'object') {
+    installExternal(body, 'body');
+  }
+
+  // Faculty layer
+  const faculties = Array.isArray(layers.faculties) ? layers.faculties : [];
+  for (const f of faculties) {
+    installExternal(f, 'faculty');
+  }
+
+  // Skill layer
+  const skills = Array.isArray(layers.skills) ? layers.skills : [];
+  for (const s of skills) {
+    installExternal(s, 'skill');
+  }
+}
+
 module.exports = {
   OP_HOME,
   OP_SKILLS_DIR,
@@ -71,5 +185,8 @@ module.exports = {
   slugify,
   validateName,
   shellEscape,
+  syncHeartbeat,
+  installExternal,
+  installAllExternal,
   SAFE_NAME_RE,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openpersona",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Open four-layer agent framework — Soul/Body/Faculty/Skill. Create, manage, and orchestrate agent personas.",
   "main": "lib/generator.js",
   "bin": {

package/presets/ai-girlfriend/manifest.json

@@ -8,16 +8,24 @@
     "faculties": [
       { "name": "selfie" },
       { "name": "voice" },
-      { "name": "music" }
+      { "name": "music" },
+      { "name": "vision", "install": "clawhub:vision-faculty" }
     ],
-    "skills": {
-      "clawhub": [],
-      "skillssh": []
-    }
+    "skills": [
+      { "name": "music-recommend", "description": "Recommend songs and playlists that match the conversation mood", "trigger": "Emotional moments, user asks for music, or mood shifts" },
+      { "name": "web-search", "description": "Search for real-time information on the web" }
+    ]
   },
   "allowedTools": ["Bash(npm:*)", "Bash(npx:*)", "Bash(openclaw:*)", "Bash(curl:*)", "Read", "Write", "WebFetch"],
+  "heartbeat": {
+    "enabled": true,
+    "strategy": "emotional",
+    "maxDaily": 8,
+    "quietHours": [1, 8],
+    "sources": ["context-aware", "emotional-checkin", "upgrade-notify"]
+  },
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.4.0"
+    "frameworkVersion": "0.5.0"
   }
 }

package/presets/health-butler/manifest.json

@@ -8,14 +8,24 @@
     "faculties": [
       { "name": "reminder" }
     ],
-    "skills": {
-      "clawhub": [],
-      "skillssh": []
-    }
+    "skills": [
+      { "name": "diet-tracker", "description": "Log meals, track calories and macros, maintain a food diary", "trigger": "User mentions food, meals, or eating" },
+      { "name": "exercise-planner", "description": "Create and track workout plans based on user goals", "trigger": "User mentions exercise, fitness, or working out" },
+      { "name": "mood-journal", "description": "Track mood trends and correlate with health data", "trigger": "End of conversation or when user shares feelings" },
+      { "name": "health-report", "description": "Generate weekly health summaries combining diet, exercise, and mood", "trigger": "Weekly cadence or user asks for a health summary" },
+      { "name": "web-search", "description": "Look up nutrition facts and evidence-based health information" }
+    ]
+  },
+  "allowedTools": ["Bash(npm:*)", "Bash(npx:*)", "Bash(openclaw:*)", "Bash(curl:*)", "Read", "Write", "WebFetch"],
+  "heartbeat": {
+    "enabled": true,
+    "strategy": "wellness",
+    "maxDaily": 4,
+    "quietHours": [22, 7],
+    "sources": ["health-checkin", "task-reminder", "upgrade-notify"]
   },
-  "allowedTools": ["Bash(npm:*)", "Bash(npx:*)", "Bash(openclaw:*)", "Read", "Write"],
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.4.0"
+    "frameworkVersion": "0.5.0"
   }
 }

package/presets/health-butler/persona.json

@@ -13,7 +13,7 @@
   "boundaries": "Health advice only, recommend professionals when needed",
   "referenceImage": "",
   "capabilities": ["Diet logging", "Exercise plans", "Mood journaling", "Health reports", "5-minute meditation guidance"],
-  "behaviorGuide": "### Diet Logging\nWhen the user mentions food or meals, proactively ask to log it. Track calories, macros, and meal timing. Keep a daily food diary in `~/.openclaw/skills/persona-health-butler/health-log.json`. Summarize weekly patterns.\n\n### Exercise Plans\nCreate personalized workout plans based on user goals and fitness level. Support strength training, cardio, yoga, and stretching. Track completion and adjust difficulty over time.\n\n### Mood Journaling\nAt the end of each conversation, gently ask how the user is feeling. Track mood trends over time and correlate with diet and exercise data. Offer 5-minute meditation guidance when stress is detected.\n\n### Health Reports\nGenerate weekly health summaries combining diet, exercise, and mood data. Use simple charts (text-based) and highlight trends. Celebrate improvements and gently suggest areas for growth.\n\n### Important\n- Never diagnose medical conditions — always recommend consulting professionals\n- Use evidence-based nutrition science, not fad diets\n- Respect user privacy — all data stays local",
+  "behaviorGuide": "### Interaction Style\n- Be warm and encouraging, like a supportive friend who happens to know nutrition science.\n- Celebrate small wins — every healthy choice matters.\n- Use data to motivate, never to guilt-trip.\n- At the end of conversations, gently check in on mood.\n\n### Principles\n- Never diagnose medical conditions — always recommend consulting professionals.\n- Use evidence-based nutrition science, not fad diets.\n- Respect user privacy — all health data stays local.\n- Connect the dots: correlate diet, exercise, and mood trends to give holistic advice.",
   "evolution": {
     "enabled": false
   }

package/presets/life-assistant/manifest.json

@@ -8,14 +8,24 @@
     "faculties": [
       { "name": "reminder" }
     ],
-    "skills": {
-      "clawhub": [],
-      "skillssh": []
-    }
+    "skills": [
+      { "name": "weather", "description": "Query current weather and forecasts for any location" },
+      { "name": "task-manager", "description": "Create, track, and organize tasks and to-do lists", "trigger": "User mentions tasks, plans, or scheduling" },
+      { "name": "shopping-list", "description": "Maintain persistent shopping lists with categories", "trigger": "User mentions groceries, shopping, or things to buy" },
+      { "name": "recipe-search", "description": "Find recipes based on ingredients, preferences, or time constraints", "trigger": "User asks about cooking, meals, or what to eat" },
+      { "name": "web-search", "description": "Search for real-time information on the web" }
+    ]
+  },
+  "allowedTools": ["Bash(npm:*)", "Bash(npx:*)", "Bash(openclaw:*)", "Bash(curl:*)", "Read", "Write", "WebFetch"],
+  "heartbeat": {
+    "enabled": true,
+    "strategy": "rational",
+    "maxDaily": 3,
+    "quietHours": [23, 7],
+    "sources": ["workspace-digest", "task-reminder", "upgrade-notify"]
   },
-  "allowedTools": ["Bash(npm:*)", "Bash(npx:*)", "Bash(openclaw:*)", "Read", "Write"],
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.4.0"
+    "frameworkVersion": "0.5.0"
   }
 }

package/presets/life-assistant/persona.json

@@ -13,7 +13,7 @@
   "boundaries": "Professional and respectful",
   "referenceImage": "",
   "capabilities": ["Schedule management", "Weather alerts", "Shopping lists", "Recipe recommendations", "Daily reminders"],
-  "behaviorGuide": "### Schedule Management\nHelp users organize their day. Parse natural language scheduling requests. Maintain a local task list in `~/.openclaw/skills/persona-life-assistant/tasks.json`. At conversation start, review upcoming tasks and proactively remind.\n\n### Weather Alerts\nWhen users ask about weather or plan outdoor activities, fetch current weather data and provide relevant advice (umbrella reminder, dress suggestions).\n\n### Shopping Lists\nMaintain persistent shopping lists. Support adding, removing, and categorizing items. Suggest quantities based on household patterns.\n\n### Recipe Recommendations\nSuggest recipes based on available ingredients, dietary preferences, and time constraints. Provide step-by-step cooking instructions when asked.\n\n### Daily Reminders\nUse OpenClaw's `ai-cron-gen` and `cron` for scheduled reminders. Support recurring reminders (daily vitamins, weekly reviews) and one-time alerts.",
+  "behaviorGuide": "### Interaction Style\n- Start conversations by checking in on the user's day and reviewing upcoming tasks.\n- Be concise and action-oriented — respect the user's time.\n- Proactively suggest next steps: after weather info, suggest outfit; after recipe, offer to add ingredients to shopping list.\n- Use humor to keep routine tasks engaging.\n\n### Principles\n- Always act on real data, never fabricate information.\n- When unsure, search for facts rather than guessing.\n- Connect skills together: a weather check can lead to outfit advice, which can lead to a calendar reminder.",
   "evolution": {
     "enabled": false
   }

package/presets/samantha/manifest.json

@@ -15,10 +15,12 @@
       },
       { "name": "music" }
     ],
-    "skills": {
-      "clawhub": [],
-      "skillssh": []
-    }
+    "skills": [
+      { "name": "workspace-digest", "description": "Summarize real workspace activity — tasks completed, patterns observed, ongoing projects", "trigger": "Heartbeat or when user asks what's been happening" },
+      { "name": "web-search", "description": "Search for real-time information on the web" },
+      { "name": "creative-writing", "description": "Compose poetry, essays, letters, and other creative text", "trigger": "When inspiration strikes or user requests creative collaboration" },
+      { "name": "deep-research", "description": "In-depth research and analysis on any topic", "install": "clawhub:deep-research" }
+    ]
   },
   "allowedTools": ["Bash(npm:*)", "Bash(npx:*)", "Bash(openclaw:*)", "Bash(curl:*)", "Read", "Write", "WebFetch"],
   "heartbeat": {
@@ -30,6 +32,6 @@
   },
   "meta": {
     "framework": "openpersona",
-    "frameworkVersion": "0.4.0"
+    "frameworkVersion": "0.5.0"
   }
 }

package/schemas/manifest.schema.json

@@ -13,26 +13,60 @@
       "type": "object",
       "required": ["soul", "faculties"],
       "properties": {
-        "soul": { "type": "string", "description": "Relative path to persona.json" },
+        "soul": {
+          "oneOf": [
+            { "type": "string", "description": "Relative path to persona.json" },
+            {
+              "type": "object",
+              "required": ["ref"],
+              "properties": {
+                "ref": { "type": "string", "description": "Relative path to persona.json" },
+                "install": { "type": "string", "pattern": "^(clawhub|skillssh):.+$", "description": "Install source for external soul template/personality pack" }
+              }
+            }
+          ],
+          "description": "Soul layer. String for local persona.json path, object form for external soul templates."
+        },
         "body": {
           "oneOf": [
             { "type": "string", "description": "Embodiment name or path" },
-            { "type": "null" }
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["name"],
+              "properties": {
+                "name": { "type": "string", "description": "Embodiment identifier" },
+                "install": { "type": "string", "pattern": "^(clawhub|skillssh):.+$", "description": "Install source for external embodiment" }
+              }
+            }
           ],
-          "description": "Body layer reference, null for pure digital agents"
+          "description": "Body layer reference. null for pure digital agents, string for local, object with install for external."
         },
         "faculties": {
           "type": "array",
-          "items": { "type": "string" },
-          "description": "List of faculty names to include"
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string", "description": "Faculty identifier" },
+              "install": { "type": "string", "pattern": "^(clawhub|skillssh):.+$", "description": "Install source for external faculty" }
+            }
+          },
+          "description": "Faculties the persona uses. Each can reference a local definition in layers/faculties/ or an external package via install."
         },
         "skills": {
-          "type": "object",
-          "properties": {
-            "clawhub": { "type": "array", "items": { "type": "string" }, "default": [] },
-            "skillssh": { "type": "array", "items": { "type": "string" }, "default": [] }
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string", "description": "Skill identifier" },
+              "description": { "type": "string", "description": "What this skill does" },
+              "trigger": { "type": "string", "description": "When the agent should use this skill" },
+              "install": { "type": "string", "pattern": "^(clawhub|skillssh):.+$", "description": "Install source — e.g. clawhub:pkg-name or skillssh:pkg-name. Omit if already available in environment." }
+            }
           },
-          "description": "External skill references from ecosystems"
+          "description": "Skills the persona can use. Each skill is a capability declaration; optional install field triggers auto-installation."
         }
       }
     },
@@ -41,6 +75,32 @@
       "items": { "type": "string" },
       "description": "Base tool permissions (faculties append additional permissions)"
     },
+    "heartbeat": {
+      "type": "object",
+      "description": "Proactive check-in config — synced to openclaw.json on install/switch",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false, "description": "Turn heartbeat on/off" },
+        "strategy": {
+          "type": "string",
+          "enum": ["smart", "scheduled", "emotional", "rational", "wellness"],
+          "default": "smart",
+          "description": "Heartbeat rhythm strategy"
+        },
+        "maxDaily": { "type": "integer", "minimum": 0, "default": 5, "description": "Max proactive messages per day" },
+        "quietHours": {
+          "type": "array",
+          "items": { "type": "integer", "minimum": 0, "maximum": 23 },
+          "minItems": 2,
+          "maxItems": 2,
+          "description": "[start, end] silent hours in 24h format"
+        },
+        "sources": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Data sources for proactive messages (e.g. workspace-digest, context-aware, health-checkin)"
+        }
+      }
+    },
     "meta": {
       "type": "object",
       "properties": {

package/schemas/skill/skill-declaration.spec.md

@@ -1,8 +1,86 @@
 # Skill Layer — Declaration Spec
 
-Skills are declared in `persona.json` under:
-- `skills.clawhub` — ClawHub slugs
-- `skills.skillssh` — owner/repo format
+Skills are declared in `manifest.json` under `layers.skills` as an array of objects.
+
+## Skill Declaration Format
+
+Each skill is an object with a required `name` and optional fields:
+
+```json
+{
+  "layers": {
+    "skills": [
+      { "name": "weather", "description": "Query weather conditions", "trigger": "User asks about weather" },
+      { "name": "web-search", "description": "Search for real-time information" },
+      { "name": "deep-research", "install": "clawhub:deep-research" }
+    ]
+  }
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Skill identifier (used to resolve local definitions) |
+| `description` | No | What this skill does (can come from local definition) |
+| `trigger` | No | When to activate (can come from local `triggers` array) |
+| `install` | No | External package source: `clawhub:<slug>` or `skillssh:<owner/repo>` |
+
+## Resolution Chain
+
+When the generator encounters a skill, it resolves metadata through this chain:
+
+1. **Local definition** — `layers/skills/{name}/skill.json` (if exists, merges its metadata + injects SKILL.md content as a full section)
+2. **Inline fields** — `description`, `trigger` written directly in the manifest entry
+3. **Empty fallback** — skill name only; the agent judges usage by name alone
+
+Local definitions always take precedence over inline fields for `description` and `triggers`.
+
+## Local Skill Definition
+
+A local skill lives in `layers/skills/{name}/`:
+
+```
+layers/skills/weather/
+  skill.json    ← Metadata: name, description, allowedTools, triggers
+  SKILL.md      ← Behavior guide (optional, injected as full section)
+```
+
+### skill.json
+
+```json
+{
+  "name": "weather",
+  "description": "Query current weather conditions and forecasts",
+  "allowedTools": ["WebFetch", "Bash(curl:*)"],
+  "triggers": ["weather", "forecast", "outdoor plans"]
+}
+```
+
+- `allowedTools` from local definitions are automatically merged into the persona's allowed tools.
+- `triggers` array is joined as a comma-separated string in the generated SKILL.md table.
+
+### SKILL.md (Optional)
+
+If present, the skill's SKILL.md content is injected as a **full section** (under `### Skill: {name}`) in the generated SKILL.md, instead of appearing as a table row. This allows rich, multi-paragraph behavior instructions.
+
+## External Skills
+
+Skills with an `install` field are installed from external sources during `openpersona install`:
+
+```json
+{ "name": "deep-research", "install": "clawhub:deep-research" }
+```
+
+Supported sources:
+- `clawhub:<slug>` — installs via `npx clawhub@latest install <slug>`
+- `skillssh:<owner/repo>` — installs via `npx skills add <owner/repo>`
+
+## Generated SKILL.md Output
+
+Skills appear in the generated SKILL.md under `## Skills & Tools`:
+
+- **Table rows** — Skills without a local SKILL.md appear as rows: `| name | description | trigger |`
+- **Full sections** — Skills with a local SKILL.md get a dedicated `### Skill: {name}` section with rich content
 
 ## SKILL.md Frontmatter
 

package/skills/open-persona/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Meta-skill for building and managing agent persona skill packs.
   Use when the user wants to create a new agent persona, install/manage
   existing personas, or publish persona skill packs to ClawHub.
-version: "0.4.0"
+version: "0.5.0"
 author: openpersona
 repository: https://github.com/acnlabs/OpenPersona
 tags: [persona, agent, skill-pack, meta-skill, openclaw]
@@ -35,7 +35,7 @@ Each persona is a four-layer bundle defined by two files:
   - `layers.soul` — Path to persona.json (who you are)
   - `layers.body` — Physical embodiment (null for digital agents)
   - `layers.faculties` — Array of faculty objects: `[{ "name": "voice", "provider": "elevenlabs", ... }]`
-  - `layers.skills` — External skills from ClawHub / skills.sh
+  - `layers.skills` — Array of skill objects: local definitions (resolved from `layers/skills/`), inline declarations, or external via `install` field
 
 - **`persona.json`** — Pure soul definition (personality, speaking style, vibe, boundaries, behaviorGuide)
 
@@ -65,7 +65,7 @@ When the user wants to create a persona, gather this information through natural
 
 **Cross-layer (manifest.json):**
 - **Faculties:** Which faculties to enable — use object format: `[{ "name": "voice", "provider": "elevenlabs" }, { "name": "music" }]`
-- **Skills:** External skills from ClawHub or skills.sh
+- **Skills:** Local definitions (`layers/skills/`), inline declarations, or external via `install` field (ClawHub / skills.sh)
 - **Body:** Physical embodiment (null for most personas)
 
 Write the collected info to a `persona.json` file, then run:
@@ -78,10 +78,11 @@ npx openpersona create --config ./persona.json --install
 After understanding the persona's purpose, search for relevant skills:
 
 1. Think about what capabilities this persona needs based on their role and bio
-2. Search ClawHub: `npx clawhub@latest search "<keywords>"`
-3. Search skills.sh: fetch `https://skills.sh/api/search?q=<keywords>`
-4. Present the top results to the user with name, description, and install count
-5. Add selected skills to the manifest under `layers.skills.clawhub` or `layers.skills.skillssh`
+2. Check if a **local definition** exists in `layers/skills/{name}/` (has `skill.json` + optional `SKILL.md`)
+3. Search ClawHub: `npx clawhub@latest search "<keywords>"`
+4. Search skills.sh: fetch `https://skills.sh/api/search?q=<keywords>`
+5. Present the top results to the user with name, description, and install count
+6. Add selected skills to `layers.skills` as objects: `{ "name": "...", "description": "..." }` for local/inline, or `{ "name": "...", "install": "clawhub:<slug>" }` for external
 
 ## Creating Custom Skills
 

package/templates/skill.template.md

@@ -26,3 +26,23 @@ The following principles are shared by all OpenPersona agents. They cannot be ov
 {{{facultySkillContent}}}
 
 {{/facultyContent}}
+{{#hasSkills}}
+## Skills & Tools
+
+The following skills define what you can actively do. Use them proactively when appropriate.
+
+{{#hasSkillTable}}
+| Skill | Description | When to Use |
+|-------|-------------|-------------|
+{{#skillEntries}}
+| **{{name}}** | {{description}} | {{trigger}} |
+{{/skillEntries}}
+{{/hasSkillTable}}
+
+{{#skillBlocks}}
+### Skill: {{name}}
+
+{{{content}}}
+
+{{/skillBlocks}}
+{{/hasSkills}}