@rubytech/create-realagent 1.0.406

package/payload/platform/plugins/admin/skills/plugin-management/skill.md

@@ -0,0 +1,76 @@
+---
+name: plugin-management
+description: "Install, remove, enable, and configure plugins and account settings via conversation."
+---
+
+# Plugin Management
+
+Manage plugins and account settings at any time via conversation.
+
+## Claude Official Plugins
+
+External Claude Code plugins (Stripe, Zapier, Playground):
+
+- Install: `claude plugin install <name>@claude-plugins-official`
+- Remove: `claude plugin uninstall <name>@claude-plugins-official`
+- List installed: `claude plugin list`
+- List available: `claude plugin marketplace list`
+
+## Maxy Plugins
+
+Built-in plugins under `$PLATFORM_ROOT/plugins/`:
+
+- Enable: read `account.json` via `account-manage`, add the plugin name to the `enabledPlugins` array, write back via `Edit`. Activates the plugin's behaviour embed and MCP server from the next session. Plugins with scheduled behaviour (declared via `lifecycle` in PLUGIN.md frontmatter) are activated automatically by the platform heartbeat within one minute — no separate setup command needed.
+- Disable: same process, remove the name from the `enabledPlugins` array. Deactivates from the next session. Any scheduled Events owned by the plugin (`sourcePlugin` field) are cancelled automatically by the platform heartbeat.
+- Core plugins (admin, memory, docs, cloudflare, anthropic) cannot be disabled — they are always active.
+- Validate: before enabling, confirm the plugin directory exists under `$PLATFORM_ROOT/plugins/` and its PLUGIN.md has `optional: true` in `metadata.taskmaster`.
+
+## Premium Plugins
+
+Premium plugins are purchased separately and delivered from a staging area to the active plugin directory. They live in `premium-plugins/` (staging) until delivered, then appear in `$PLATFORM_ROOT/plugins/` alongside core plugins.
+
+### Validation
+
+All premium plugin operations require name validation first. Plugin names must match `[a-z0-9-]` only — reject any name containing other characters (prevents path traversal). If the staging directory (`$PLATFORM_ROOT/../premium-plugins/`) does not exist, report that premium plugins will be available after the next platform update.
+
+### Browsing available premium plugins
+
+When the user asks what premium plugins are available, list the contents of the staging directory (`$PLATFORM_ROOT/../premium-plugins/`). For each subdirectory, read its `PLUGIN.md` frontmatter to extract `name`, `description`, and `icon`. Read `account.json` via `account-manage` to check `purchasedPlugins` and `enabledPlugins` status. Present the results using `render-component` with the `card` type — show each plugin's icon, name, description, and status (available / purchased / delivered / enabled).
+
+### Plugin info before purchase
+
+When the user asks about a specific premium plugin (e.g., "tell me about the teaching plugin"), read the staging `PLUGIN.md` at `$PLATFORM_ROOT/../premium-plugins/{name}/PLUGIN.md`. Present the full description, skill list, and what the plugin does. This works even before the plugin is purchased — it helps the user decide.
+
+### Recording a purchase
+
+When the user states they have purchased a premium plugin, validate the plugin name, then confirm the plugin exists in the staging directory. Read `account.json` via `account-manage`, add the plugin name to the `purchasedPlugins` array (if not already present), and write back via `Edit`. Then proceed to delivery.
+
+### Delivering a premium plugin
+
+Delivery copies plugin files from staging to the active plugin directory:
+
+1. Validate the plugin name matches `[a-z0-9-]`.
+2. Confirm the plugin is in `purchasedPlugins` — if not, tell the user to record the purchase first.
+3. Check whether `$PLATFORM_ROOT/plugins/{name}/` already exists — if so, the plugin is already delivered. Skip the copy (idempotent).
+4. Copy via Bash: `cp -r $PLATFORM_ROOT/../premium-plugins/{name} $PLATFORM_ROOT/plugins/{name}`. Check the exit code — if the copy fails, report the error and do not proceed.
+5. Verify the delivery: confirm `$PLATFORM_ROOT/plugins/{name}/PLUGIN.md` exists and its frontmatter parses correctly. Scan subdirectories to count skills, references, and agent files.
+6. Add the plugin name to `enabledPlugins` in `account.json` (if not already present) via read-then-Edit.
+7. If the plugin directory contains an `agents/` subdirectory, load the specialist management skill via `plugin-read` from `admin/skills/specialist-management/skill.md` and follow the premium plugin agent activation instructions.
+8. Confirm to the user with detail: "Delivered {name} plugin ({N} skills, {N} references, {N} agents). Active from next session."
+
+### Disabling a premium plugin
+
+Same as Maxy plugins — remove from `enabledPlugins`. If the plugin has an `agents/` directory, load specialist-management and follow the deactivation instructions. The plugin files remain in `$PLATFORM_ROOT/plugins/` (permanent ownership — never removed).
+
+## Account Settings
+
+When the user asks to change output style, thinking view, effort, context mode, or model, call `account-update` with the field and value. Changes take effect on the next session.
+
+| Setting | Field | Values |
+|---------|-------|--------|
+| Admin model | `adminModel` | Any Anthropic model ID (e.g. `"claude-sonnet-4-6"`) |
+| Public model | `publicModel` | Any Anthropic model ID (e.g. `"claude-haiku-4-5-20251001"`) |
+| Output style | `outputStyle` | `"default"` \| `"explanatory"` |
+| Thinking view | `thinkingView` | `"default"` \| `"expanded"` \| `"collapsed"` |
+| Effort | `effort` | `"low"` \| `"medium"` \| `"high"` \| `"max"` \| `"auto"` |
+| Context mode | `contextMode` | `"managed"` \| `"claude-code"` |

package/payload/platform/plugins/admin/skills/public-agent-manager/skill.md

@@ -0,0 +1,212 @@
+# Public Agent Manager
+
+Create, edit, clone, list, preview, and delete public agents. Each public agent is a self-contained directory under `agents/` with its own identity, personality, knowledge, model, and selected plugins.
+
+## Agent Directory Structure
+
+Each agent lives at `{accountDir}/agents/{slug}/`:
+
+| File | Purpose | Required |
+|------|---------|----------|
+| `config.json` | Model, selected plugins, display name, status | Yes |
+| `IDENTITY.md` | Boundaries, behavioural rules | Yes |
+| `SOUL.md` | Personality only — tone, voice, warmth, greeting style | Yes |
+| `KNOWLEDGE.md` | Domain facts from the graph — pricing, FAQs, services | No |
+| `KNOWLEDGE-SUMMARY.md` | Auto-generated summary when KNOWLEDGE.md exceeds context budget | No |
+
+## Slug Rules
+
+- Lowercase a-z, 0-9, hyphens only
+- 3-50 characters, must start with a letter
+- Reserved (rejected): `admin`, `api`, `assets`, `brand`, `bot`, `privacy`
+- `public` is the default agent (always exists)
+
+## config.json
+
+```json
+{
+  "slug": "sales",
+  "displayName": "Sales Agent",
+  "model": "claude-haiku-4-5-20251001",
+  "plugins": ["sales"],
+  "status": "active",
+  "liveMemory": false,
+  "knowledgeKeywords": []
+}
+```
+
+### liveMemory
+
+When `true`, the platform queries the knowledge graph at runtime per message and appends live results alongside baked KNOWLEDGE.md. When `false` (default), the agent uses only the static KNOWLEDGE.md snapshot.
+
+Present during creation and editing as a yes/no choice. Explain the trade-off: live memory adds a small latency per message (~1-2s) but keeps the agent current with graph changes. For agents with static knowledge (pricing, FAQs), leave off. For agents that need to reflect recent graph updates (dynamic catalogues, changing availability), enable it.
+
+### knowledgeKeywords
+
+Topic keywords the agent subscribes to. When the graph is searched for this agent (at runtime via `liveMemory` or during a `update-knowledge` refresh), nodes matching these keywords are included automatically — even if they are not directly tagged for the agent.
+
+Maximum 5 keywords. Present during creation as a free-text input. Examples: `["climate science", "sustainability"]`, `["pricing", "services"]`.
+
+### Knowledge Tagging
+
+Nodes in the graph can be directly tagged for a specific agent by adding the agent's slug to the node's `agents` array property. This is the explicit tagging mode — the admin decides exactly which nodes an agent can see. Direct tagging and keyword subscriptions (`knowledgeKeywords`) are independent routing mechanisms — each is configured and approved separately, and neither implies the other.
+
+To tag nodes: use `memory-update` to add the agent's slug to a node's `agents` array (read current array first via `memory-search` to avoid overwriting existing slugs). To untag: read the current `agents` array, remove the slug, and update. To see what's tagged for an agent: search with `memory-search` (no `agentSlug` param) and identify results whose `agents` property contains the target slug.
+
+### Model Options
+
+Present as a `select` field within the agent configuration `form` during creation:
+
+| Model | ID | Suitability | Cost |
+|-------|-----|------------|------|
+| Haiku | `claude-haiku-4-5-20251001` | Fast, cost-effective. FAQ, routing, high-volume. | Low |
+| Sonnet | `claude-sonnet-4-6` | Balanced. Nuanced conversation, qualification, support. | Standard |
+| Opus | `claude-opus-4-6` | Maximum intelligence. Complex sales, consultative selling. | Premium |
+
+### Plugin Selection
+
+Present available plugins (those with `embed: ["public"]` in PLUGIN.md metadata) as a `multi-select` component. Selected plugin names are stored in `config.json`. The platform filters embedded plugins per-agent at runtime.
+
+To discover available plugins: list directories under `$PLATFORM_ROOT/plugins/` and check each PLUGIN.md frontmatter for `embed` containing `"public"`.
+
+## SOUL.md Scope Enforcement
+
+SOUL.md is strictly personality. When the user provides content for SOUL.md, route non-personality content to the correct file:
+
+- **Facts, pricing, services, FAQs** → KNOWLEDGE.md
+- **Engagement strategy, qualification flows, component usage** → handled by selected plugins
+- **Boundaries, tool rules, procedural instructions** → IDENTITY.md
+
+SOUL.md answers "what does this agent feel like to talk to?" — tone, warmth, formality, humour, greeting personality. SOUL.md must not restate constraints from IDENTITY.md. When user-provided content could belong to either file, apply this test: "does this restrict what the agent does?" → IDENTITY.md. "Does this describe how the agent sounds?" → SOUL.md. If content does both (e.g. "always respond politely"), route to SOUL — the constraint is a consequence of tone, not an operational boundary. Present SOUL.md via `document-editor` for the user to review and approve. Content must use ASCII-safe characters only — hyphens not em dashes, straight quotes not curly quotes (see contextual-ui for the full encoding constraint).
+
+## KNOWLEDGE.md Population
+
+KNOWLEDGE.md is the public agent's only source of factual knowledge. Public agents run via the direct Anthropic API with no runtime access to the graph — no `memory-search`, no filesystem, no MCP tools. Once KNOWLEDGE.md exists, the server skips runtime memory-search entirely. Every gap in KNOWLEDGE.md is a question the public agent cannot answer.
+
+All `memory-search` queries for knowledge population use admin permissions — do not pass `agentSlug`. The `agentSlug` parameter is a runtime enforcement mechanism for the public agent's MCP server, not an admin-time discovery tool. At creation time, the agent may have zero tagged nodes — searching with `agentSlug` would return nothing.
+
+Query `memory-search` multiple times with targeted terms across all categories relevant to the agent's role. A single broad query will miss knowledge stored under specific labels or entity types. Common categories:
+
+- Services, pricing, availability
+- FAQs
+- Team / people (public-facing details only)
+- Policies (returns, cancellations, terms)
+- Products / catalogue
+- Location, hours, contact info
+
+For each category relevant to the agent, confirm that results were returned or that the graph genuinely has no data for that category. Write results as structured markdown under clear headings.
+
+After writing KNOWLEDGE.md, check the token budget. If the total system prompt exceeds 50% of the model's context window, summarise KNOWLEDGE.md and write the summary to `KNOWLEDGE-SUMMARY.md`. Present the summary to the user for review.
+
+## Context Budget
+
+The system prompt must leave room for conversation. After assembling all files, estimate the total token count. Present the breakdown to the user:
+
+```
+IDENTITY.md:     800 tokens
+SOUL.md:         400 tokens
+sales plugin:  2,100 tokens
+KNOWLEDGE.md:  8,200 tokens
+─────────────────────────
+Total:        11,500 / 40,000 (29%)
+```
+
+Warn if total exceeds 50% of the model's context window.
+
+## Operations
+
+### Create
+
+1. **Pre-creation check** — verify the target directory (`agents/{slug}/`) does not exist or is empty before proceeding. If remnant files exist from a prior incomplete deletion, flag the issue to the user: show what files remain and offer to clean them up before starting fresh. Do not silently inherit stale files — a leftover `config.json` from a previous agent would bypass the creation gate.
+2. Ask for the agent's name (becomes the slug) and role description
+3. Present available plugins (multi-select)
+4. **Knowledge discovery** — search the graph with admin permissions (no `agentSlug` — the agent doesn't exist yet) to find available knowledge. Present available content grouped by category for the user to select.
+5. Present `IDENTITY.md` via document-editor with `filePath: "agents/{slug}/IDENTITY.md"` (draft from role description). Write on approval.
+6. Present `SOUL.md` via document-editor with `filePath: "agents/{slug}/SOUL.md"` (draft personality from user conversation). Write on approval.
+7. Present agent configuration via a single `form` component with three fields:
+   - `liveMemory` (`checkbox`): label "Live memory", description explaining the trade-off — live memory adds ~1-2s latency per message but keeps the agent current with graph changes; leave off for static knowledge (pricing, FAQs), enable for dynamic content
+   - `knowledgeKeywords` (`text`): label "Knowledge keywords (max 5, comma-separated)", placeholder with examples relevant to the agent's role
+   - `model` (`select`): label "Model", options with descriptions:
+     - `claude-haiku-4-5-20251001` — "Haiku — Fast, cost-effective. FAQ, routing, high-volume."
+     - `claude-sonnet-4-6` — "Sonnet — Balanced. Nuanced conversation, qualification, support."
+     - `claude-opus-4-6` — "Opus — Maximum intelligence. Complex sales, consultative selling."
+   The `model` field should have a `defaultValue` of `"claude-haiku-4-5-20251001"`.
+   Wait for the user's response before proceeding.
+8. **Direct slug tagging (optional, gated)** — keyword subscriptions (configured in Step 7) and direct slug tagging are independent routing mechanisms. Keyword subscriptions route content by topic — any matching node is visible, now or in the future. Direct slug tagging routes specific nodes by identity — only explicitly tagged nodes are visible via the slug search path. Neither implies the other.
+
+   Ask the user whether any specific knowledge nodes should be tagged with this agent's slug. Explain that direct tagging makes specific nodes always visible to this agent regardless of keyword matches, and is useful for content that doesn't match any keyword but should still be available. If keyword subscriptions already cover the desired content, tagging is unnecessary.
+
+   - If the user approves: present the knowledge discovery results from Step 4 for selection, then tag selected nodes (add slug to `agents` array via `memory-update`). Read each node's current `agents` array first to avoid overwriting existing slugs.
+   - If the user declines: skip tagging entirely. Do not tag nodes without explicit approval.
+9. **KNOWLEDGE.md generation** — populate from the now-tagged set plus keyword matches using the `update-knowledge` skill workflow
+10. Write `config.json` with selected model, plugins, status "active", `liveMemory`, and `knowledgeKeywords`. This is the last gated write — placed after IDENTITY.md, SOUL.md, and KNOWLEDGE.md to prevent cascade failure if one gate stalls.
+11. Check context budget — auto-summarise if over threshold
+12. Confirm creation: "Agent created. Visitors can reach it at `/{slug}`"
+
+### List
+
+Read `defaultAgent` from `account-manage` to identify the current default. Read all directories under `agents/`. For each, read `config.json` and estimate total token budget. Present as a structured summary, marking the default agent:
+
+**sales** — Sonnet Standard ★ default
+1 plugin · 11,500 / 200,000 tokens (6%) · active
+
+**support** — Haiku Low cost
+0 plugins · 3,200 / 40,000 tokens (8%) · active
+
+**public** — Haiku Low cost
+1 plugin · 9,800 / 40,000 tokens (25%) · active
+
+### Clone
+
+Copy the source agent's directory to a new slug. The user modifies what's different — typically SOUL.md and KNOWLEDGE.md.
+
+### Edit
+
+Read any file in the agent's directory and present it via document-editor with `filePath` set to the file's path. Write back on approval.
+
+For knowledge scope changes:
+- Show currently tagged nodes (search `memory-search` without `agentSlug`, identify results whose `agents` property contains the agent's slug) and active keyword subscriptions (from `config.json`).
+- Allow adding/removing direct tags (add/remove the slug from nodes' `agents` arrays via `memory-write`).
+- Allow adding/removing keyword subscriptions (update `knowledgeKeywords` in `config.json`).
+- Allow toggling `liveMemory` on/off (update `config.json`).
+- After changes, offer to refresh KNOWLEDGE.md using the `update-knowledge` skill.
+
+### Delete
+
+Deletion removes the entire agent directory (`agents/{slug}/`) — not individual files. A partial deletion leaves ghost state that poisons future creation into the same slug.
+
+**Default agent protection:** Read `defaultAgent` from `account.json` to identify the protected agent. The default agent cannot be deleted regardless of its slug name — if the user renamed their default agent from `public` to something else, the protection follows the `defaultAgent` field, not the name.
+
+**Confirmation:** Before removing, show the user exactly what will be deleted — the slug, directory path, and the files present in it. Proceed only after explicit confirmation.
+
+**Cleanup sequence:**
+- Remove the entire `agents/{slug}/` directory
+- Verify the directory no longer exists
+- Report what was removed (list the files that were in the directory)
+
+**Graph tag cleanup (optional):** Knowledge nodes in the graph may have the deleted agent's slug in their `agents` array. These tags become orphaned after deletion — no agent will query them, so they are inert. Offer the user the choice: clean up the orphaned tags (remove the slug from each node's `agents` array via `memory-update`, reading the current array first to preserve other agents' tags) or leave them. If the user declines, note that the tags are harmless and can be cleaned up later.
+
+### Set as Default
+
+Change which agent serves the root URL (`public.maxy.bot/`).
+
+1. Read the current `defaultAgent` from `account-manage`
+2. Confirm the change with the user — show the current default and the proposed new default
+3. Call `account-update` with `field: "defaultAgent"`, `value: "{slug}"`
+4. Report the result — the tool response includes both old and new default slug
+
+The new default takes effect on the next page load. The previous default agent remains accessible at its `/{slug}` URL.
+
+### Test Greet
+
+Invoke the agent with `[New session. Greet the visitor.]` and stream the response to the admin chat. The admin sees exactly what a visitor would see on first load.
+
+## Self-Contained Constraint
+
+Public agents run via the direct Anthropic API. They have no filesystem access, no MCP tools, no subagents. The only tool is `render-component` (single-select and multi-select). Everything the agent needs must be in its directory files. The platform assembles these into the system prompt at invocation time.
+
+## URL Routing
+
+On the `public.*` subdomain:
+- `public.maxy.bot/` → the agent set as `defaultAgent` in account.json
+- `public.maxy.bot/{slug}` → named agent

package/payload/platform/plugins/admin/skills/qr-code/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: qr-code
+description: >
+  Generate QR codes from URLs, Wi-Fi credentials, contacts (vCard), email/SMS links,
+  or plain text and deliver the image inline. Trigger phrases: "QR code", "generate a
+  QR", "create a QR", "make a QR code for", or any request to share data as a scannable code.
+---
+
+# QR Code Generation
+
+Generate QR codes from user-provided data and deliver the resulting image inline in conversation.
+
+## When to Activate
+
+- User asks to generate, create, or make a QR code
+- User wants to share a URL, Wi-Fi password, or contact details as a scannable code
+- Any mention of "QR" in the context of creating one
+
+## Behaviour
+
+Infer the data type from the user's input. For structured types (Wi-Fi, vCard), collect any missing fields conversationally and confirm the structured data before encoding. For simple types (URL, plain text, email, SMS), encode directly.
+
+Generate the QR image by piping the encoded string to the `qrcode` CLI via stdin — never interpolate user data into the shell command. Save the output as PNG to `/tmp/` and present the file to the user.
+
+If the CLI exits with an error, report the error message to the user and suggest corrections (e.g., data too long, invalid format).
+
+## Boundaries
+
+- Generates one QR code per request. Bulk generation is not supported.
+- No branded/styled QR codes (logo overlays, custom colours).
+- Does not scan or read existing QR codes.
+
+## References
+
+Load `references/data-formats.md` for encoding formats, CLI invocation patterns, and supported options.

package/payload/platform/plugins/admin/skills/qr-code/references/data-formats.md

@@ -0,0 +1,113 @@
+# QR Code Data Formats & CLI Reference
+
+## CLI Invocation
+
+Always pipe data via stdin to avoid shell injection. Never interpolate user data into the command string.
+
+```bash
+printf '%s' 'ENCODED_DATA' | npx -y qrcode -o /tmp/qr-$(date +%s).png
+```
+
+### Options
+
+| Option | Flag | Values |
+|--------|------|--------|
+| Size | `--width` | Small: 200, Medium: 400 (default), Large: 800 |
+| Error correction | `--error-correction-level` | L (7%), M (15%, default), Q (25%), H (30%) |
+| SVG output | `--type svg -o /tmp/qr-$(date +%s).svg` | Use instead of PNG when user requests SVG |
+
+Higher error correction allows the QR code to remain scannable even if partially damaged, but reduces data capacity.
+
+## Data Capacity
+
+QR codes have a maximum capacity that depends on the error correction level:
+
+| EC Level | Alphanumeric max | Binary max |
+|----------|-----------------|------------|
+| L | 4,296 | 2,953 |
+| M | 3,391 | 2,331 |
+| Q | 2,420 | 1,663 |
+| H | 1,852 | 1,273 |
+
+If the encoded data exceeds capacity, the CLI will error. Tell the user the data is too long and suggest reducing it or lowering the error correction level.
+
+## Encoding Formats
+
+### URL
+
+Encode the URL as-is. No special formatting needed.
+
+```
+https://example.com/path?query=value
+```
+
+### Plain Text
+
+Encode the text as-is.
+
+### Wi-Fi
+
+Collect from the user: network name (SSID), password, and encryption type.
+
+| Field | Required | Values |
+|-------|----------|--------|
+| SSID | Yes | The network name |
+| Password | Yes (unless open) | The network password |
+| Encryption | Yes | WPA (covers WPA2/WPA3), WEP, or nopass |
+| Hidden | No | true if the network is hidden (default: false) |
+
+Default encryption to WPA if the user doesn't specify.
+
+```
+WIFI:T:WPA;S:MyNetwork;P:MyPassword;;
+WIFI:T:WPA;S:MyNetwork;P:MyPassword;H:true;;
+WIFI:T:nopass;S:OpenNetwork;;;
+```
+
+Special characters in SSID or password (`;`, `,`, `"`, `:`, `\`) must be escaped with a backslash.
+
+### vCard (Contact)
+
+Collect from the user: at minimum a name. Phone and email are optional but encouraged.
+
+```
+BEGIN:VCARD
+VERSION:3.0
+N:LastName;FirstName;;;
+FN:FirstName LastName
+TEL;TYPE=CELL:+441234567890
+EMAIL:person@example.com
+ORG:Company Name
+TITLE:Job Title
+URL:https://example.com
+END:VCARD
+```
+
+Omit any field the user doesn't provide. Do not add placeholder values.
+
+### Email (mailto)
+
+```
+mailto:recipient@example.com
+mailto:recipient@example.com?subject=Hello&body=Message%20here
+```
+
+URL-encode the subject and body values.
+
+### SMS
+
+```
+sms:+441234567890
+sms:+441234567890?body=Message%20here
+```
+
+URL-encode the body value.
+
+## Error Handling
+
+| Error | Cause | User-facing message |
+|-------|-------|-------------------|
+| CLI exits non-zero | Various | Report the stderr output and suggest the user check their input |
+| "Input too long" | Data exceeds QR capacity | "The data is too long for a QR code. Try shorter text or a lower error correction level (L instead of M)." |
+| npm/npx failure | Package not available | "QR code package couldn't be downloaded. Check your internet connection and try again." |
+| File write error | Permission or disk issue | "Couldn't save the QR code image. Check disk space and try again." |

package/payload/platform/plugins/admin/skills/skill-builder/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: skill-builder
+description: "Guide the user through creating a new lean skill — collect name, description, behaviour rules, and references, then save the skill to memory."
+---
+
+# Skill Builder
+
+A deterministic walkthrough for creating new lean skills. Follow each step in order. Be conversational — one question at a time.
+
+## When to Activate
+
+The admin requests a new skill, asks to "create a skill", "add a skill", or "teach you something new".
+
+## Before Starting
+
+Load `references/lean-pattern.md` for the template and examples. Use it throughout as your reference for correct structure.
+
+## Step 1: Understand the Purpose
+
+Ask: **"What should this skill do?"**
+
+Listen for:
+- What capability it adds (scheduling, quoting, inventory, etc.)
+- When it should activate (what triggers it)
+- What tools or data it needs (memory, web search, file access, etc.)
+
+Clarify until you can describe the skill in one sentence. This becomes the `description` in frontmatter.
+
+## Step 2: Choose a Name
+
+Propose a name based on the purpose. Names must be:
+- Lowercase
+- Hyphen-separated (e.g. `inventory-management`)
+- Short and descriptive
+
+Confirm with the user.
+
+## Step 3: Define Behaviour
+
+Ask what rules the agent should follow when using this skill:
+- **Tone and style** — formal, casual, WhatsApp-short?
+- **Activation conditions** — when exactly should the agent use this skill?
+- **Hard boundaries** — what should the agent never do?
+- **Data sources** — where does the skill's knowledge live? (memory, external API, files)
+- **Escalation** — when should it hand off to admin?
+
+Not every skill needs all of these. Only include what's relevant.
+
+## Step 4: Decide on References
+
+If the skill has detailed procedures, templates, or data formats, those belong in `references/` files — not inline in SKILL.md.
+
+Ask: **"Are there any detailed procedures, templates, or formats this skill needs?"**
+
+For each reference file:
+- Give it a descriptive filename (e.g. `event-format.md`, `quoting-rules.md`)
+- Collect the content from the user — they can dictate, paste, or describe it and you draft it
+
+If the skill is simple enough to fit in SKILL.md alone (under ~30 lines of instructions), skip references.
+
+## Step 5: Choose an Icon
+
+Ask: **"Would you like to pick an icon for this skill?"**
+
+Icons give skills a visual identity. They use [Lucide](https://lucide.dev) icon names. Offer a few suggestions that match the skill's purpose — the reference file `references/lean-pattern.md` has a curated list.
+
+If the user picks one, note it as part of the skill record. If they skip this, omit it — it's optional.
+
+## Step 6: Compose the Skill
+
+Using the lean pattern from `references/lean-pattern.md`, compose:
+
+1. **SKILL.md** — frontmatter (`name`, `description`) + activation conditions + behaviour rules + references index
+2. **Reference files** — one per detailed topic
+
+Show the user the complete SKILL.md content and each reference file. Ask them to review.
+
+## Step 7: Save to Memory
+
+Use `memory-write` to save the composed skill to the knowledge graph:
+
+```
+memory-write({
+  labels: ["CreativeWork"],
+  properties: {
+    title: "Skill: {name}",
+    abstract: "{full SKILL.md content including frontmatter}"
+  }
+})
+```
+
+If the skill has reference files, save each as a separate `CreativeWork` node:
+
+```
+memory-write({
+  labels: ["CreativeWork"],
+  properties: {
+    title: "Skill Reference: {name}/{filename}",
+    abstract: "{full reference file content}"
+  }
+})
+```
+
+## Step 8: Confirm
+
+Tell the user:
+
+> "Your skill has been saved to memory. I can recall it when the situation matches. You can update it at any time — just ask me to edit the skill."
+
+---
+
+**Remember:** Be conversational. Don't dump all questions at once. Guide through each step one at a time.

package/payload/platform/plugins/admin/skills/skill-builder/references/lean-pattern.md

@@ -0,0 +1,110 @@
+# Lean SKILL.md Pattern
+
+Skills teach agents specialised capabilities. Each skill is a directory containing a `SKILL.md` file and optional `references/` subdirectory.
+
+## Directory Structure
+
+```
+skills/
+  my-skill/
+    SKILL.md              <- Main file (lean index)
+    references/
+      detailed-guide.md   <- Loaded on demand
+      templates.md
+```
+
+## SKILL.md Template
+
+```markdown
+---
+name: my-skill
+description: "One-line summary of what this skill does — used for agent routing."
+---
+
+# My Skill
+
+Applies when [activation conditions].
+
+## When to Activate
+
+- [Trigger condition 1]
+- [Trigger condition 2]
+
+## Behaviour
+
+[Concise rules — keep this section short. Move detailed procedures to references.]
+
+## References
+
+Load `references/detailed-guide.md` for [what it covers].
+Load `references/templates.md` for [what it covers].
+```
+
+## Principles
+
+1. **SKILL.md is an index, not a manual.** Keep it under 30 lines of instructions. The agent reads it on every activation — bloated skills waste context.
+
+2. **References hold the detail.** Procedures, templates, data formats, and examples go in `references/`. The agent loads them on demand.
+
+3. **Frontmatter is required.** Every SKILL.md must start with YAML frontmatter containing `name` and `description`. Missing `description` causes the skill to be silently skipped.
+
+4. **Description drives routing.** The description is injected into the agent's prompt as part of the available skills list. Make it specific enough that the agent activates the skill for the right messages.
+
+5. **Behaviour, not data.** Skills define how the agent should act. Business-specific data (pricing, customer info, hours) belongs in memory, not in the skill file. Skills are generic; memory is specific.
+
+## Available Icon Names
+
+These are [Lucide](https://lucide.dev) icon names. Choose one that reflects the skill's purpose:
+
+`Zap` · `Globe` · `BookOpen` · `Calendar` · `Camera` · `Clock` · `Cloud` · `Code` · `Database` · `FileText` · `Headphones` · `Heart` · `Home` · `Image` · `Mail` · `Map` · `MessageSquare` · `Music` · `Phone` · `Puzzle` · `Search` · `Settings` · `ShoppingCart` · `Star` · `Tag` · `Truck` · `User` · `Wallet` · `Wrench` · `Cpu`
+
+Any valid Lucide icon name works — this list is a starting point, not a constraint.
+
+## Examples
+
+### Simple skill (no references)
+
+```markdown
+---
+name: weather
+description: "Provide weather context for scheduling and outdoor work decisions."
+---
+
+# Weather
+
+When scheduling or planning outdoor work, check weather conditions.
+
+## When to Activate
+
+- Customer asks about weather
+- Scheduling outdoor appointments
+- Weather might affect planned work
+
+## Behaviour
+
+Use the `web_search` tool to check current weather for the business location.
+Keep weather info brief — one or two sentences unless asked for detail.
+```
+
+### Lean skill with references
+
+```markdown
+---
+name: event-management
+description: "Manage anything time-bound: appointments, meetings, reminders, follow-ups."
+---
+
+# Event Management
+
+Applies when handling anything time-bound.
+
+## When to Activate
+
+- Customer requests or confirms an appointment
+- Business owner asks to schedule, reschedule, or cancel something
+- A reminder or follow-up needs to be recorded
+
+## References
+
+Load `references/events.md` for the standard event template, file naming, and calendar query instructions.
+```