Daniele
c27da4e6ab
Nightly Build / build (push) Successful in 8m6s
Per blueprint/skill-project.md: the old single-namespace, hand-maintained
index is gone, replaced by a read-only, two-scope tree whose index is a
runtime function of its content.
- skills/ index generated at runtime (crates/skald-core/src/skills/:
inventory, install, validate, watch), injected through the new
<!-- SKILLS_LIST --> placeholder in AGENT.md (agents/common/skills.md);
meta.json inject_skills flag removed. 11 chat/task agents carry the
include, the 4 system agents do not.
- Two trees, both read-only in both directions: skills/shared/{id} (the
group's) and skills/{username}/{id} (one member's own, on the stable
userid). The root is closed too: UserFs::SkillMounts + RouteError (alias
probe, plain-denied paths, no home fallback) and a per-user
.skills-root/{userid} container mount with the two scope mounts nested
inside, plus the fifth self-heal axis (skills_mounted).
- Agent verbs: skill_register/skill_delete (Config group, global scope
behind the new skill.manage capability), fetch_repo for public repos,
list_items(type="skills"); reads are plain read_file on the printed
path. Seeded @fs_read skills/* allow.
- Freshness: a digest-gated watcher on the two trees emits
SystemEvent::SkillsChanged, whose subscriber rebuilds the frozen prompt
prefix via Skald::invalidate_prompt_prefix; in-process writers invalidate
directly.
- The build ships no skills: the three bundled skills (ics2json,
mcp-builder, skill-creator) and skills/index.md are removed, skills/ is
instance data (gitignored, not packaged, no longer pruned by update.sh).
- Docs: skills.md, agents.md, shared-folders.md added; docs/index.md and
agents/README.md updated.
89 lines
5.9 KiB
Markdown
89 lines
5.9 KiB
Markdown
# Agents
|
||
|
||
## Adding a new agent: the skills index is opt-in
|
||
|
||
An agent sees the installed skills **only** if its `AGENT.md` carries the
|
||
`<!-- SKILLS_LIST -->` placeholder, normally through
|
||
`<!-- INCLUDE: common/skills.md -->`. There is no `meta.json` flag: the sentinel
|
||
*is* the switch, exactly as it is for `<!-- MCP_LIST -->`.
|
||
|
||
So a new agent starts **without** the index and stays without it until someone
|
||
adds the line. That is the deliberate direction of the default: the opposite one
|
||
— an agent inheriting the index by forgetfulness — is the worse failure, because
|
||
the index is written in the imperative ("you MUST read its SKILL.md") and an
|
||
unattended `type: system` agent has its approvals auto-denied and sometimes no
|
||
tools at all.
|
||
|
||
`common/skills.md` is **one line and deliberately holds no prose**, unlike
|
||
`common/mcp.md`. Every word — the imperative header, the list, the closing rules
|
||
— is produced by the renderer, so that an instance with no skills installed gets
|
||
an empty string instead of a header promising a list that isn't there. (That is
|
||
not hypothetical: the MCP section keeps its prose in the fragment, and its empty
|
||
state once had the model invent a discovery tool to fill the gap.) The fragment
|
||
cannot explain itself in place either — `resolve_includes` copies any line that
|
||
is not an upper-case sentinel straight into the prompt, so a comment there would
|
||
be read by the model.
|
||
|
||
The rule of thumb: a `chat` or `task` agent gets the include, a `system` agent
|
||
does not. Put the line **as low as possible** in the prompt (by convention right
|
||
after `common/mcp.md`) — anything above it survives in the provider's cached
|
||
prefix when a skill is added or removed. `crates/skald-core/src/agents.rs` has a
|
||
test that holds every shipped agent to this.
|
||
|
||
# Agent icons — style guide
|
||
|
||
Each agent in the `agents/` directory can have an icon/avatar declared in the `"icon"` field of its `meta.json`. The backend serves the file via `GET /api/agents/{id}/icon`.
|
||
|
||
## Visual style
|
||
|
||
Icons are generated with **Vector Paintings** LoRA via ComfyUI in a warm, family-friendly style:
|
||
|
||
- **Style**: painterly vector — bold shapes fused with expressive brushstrokes
|
||
- **Technique**: vivid colours, emotion, motion, warm lighting
|
||
- **Format**: square (1024×1024), rendered as a character portrait
|
||
- **Background**: warm, cozy, medium-bright (no dark/no neon)
|
||
- **Subject**: a warm animal character representing the agent's role, with contextual elements (tools, symbols, objects)
|
||
- **Palette**: terracotta, amber, warm gold, coral, soft teal — warm and inviting
|
||
- **Trigger word**: `VectorPaintDaal` must be included at the start of the prompt
|
||
|
||
## Prompt template
|
||
|
||
```
|
||
VectorPaintDaal. A warm friendly {ANIMAL} character with a gentle smile, wearing {CLOTHING/ACCESSORIES}. It holds {OBJECT} and around it float {SYMBOLS}. Warm golden light, cozy atmosphere. {DOMINANT_COLOURS} palette. Expressive bold brushstrokes, painterly vector style. Family-friendly illustration, portrait of a kind {ROLE}.
|
||
```
|
||
|
||
## Per-agent reference
|
||
|
||
### Chat agents — warm animals
|
||
|
||
| Agent | Animal | Role | Elements | Palette |
|
||
|-------|--------|------|----------|---------|
|
||
| **Main Assistant** 🦊 | Fox | General assistant | Glowing threads connecting a heart, star, house | Terracotta, amber, gold |
|
||
| **Project Coordinator** 🦡 | Badger | Family coordinator | Floating threads linking heart, star, house, smiling face; cozy kitchen table | Terracotta, amber, gold, coral |
|
||
| **Researcher** 🐿️ | Squirrel | Curious researcher | Glowing book, magnifying glass, compass, scrolls, stars | Terracotta, amber, soft teal, coral |
|
||
| **Generalist** 🦫 | Beaver | Handy executor | Glowing multitool, wrench, paintbrush, trowel, cooking pot | Terracotta, orange, amber, timber |
|
||
| **Code Explorer** 🕵️ | Meerkat | Curious analyst | Magnifying glass, data trails, sparkling code symbols | Terracotta, amber, deep blue, gold |
|
||
| **Software Architect** 🏗️ | Heron | Thoughtful planner | Floating blueprints, geometric shapes, building blocks | Terracotta, soft teal, amber, pale gold |
|
||
| **Software Engineer** 🔧 | Bear | Focused builder | Glowing wrench, gears, circuit board, hammer, sparks | Terracotta, orange, amber, steel grey |
|
||
| **Spec Writer** 📝 | Owl | Wise scribe | Glowing quill, scrolls, open books, words floating mid-air | Deep indigo, burnished gold, amber, cream |
|
||
| **Tech Lead** 👑 | Stag | Confident strategist | Holographic kanban board, task cards, sub-agent symbols | Warm amber, deep teal, gold, coral |
|
||
| **Business Analyst** 💼 | Magpie | Thoughtful evaluator | Glowing clipboard, floating documents, abacus, data points | Deep indigo, gold, soft teal, amber |
|
||
| **Companion** 🦦 | Otter | Children's friend | Glowing pencil, smiling sun, star, open book, paintbrush | Soft coral, amber, gold, gentle teal |
|
||
|
||
### System agents — insect family
|
||
|
||
System agents (`type: "system"`) are invisible background agents that maintain the platform. They use insect characters to visually distinguish them from chat-facing agents.
|
||
|
||
| Agent | Animal | Role | Elements | Palette |
|
||
|-------|--------|------|----------|---------|
|
||
| **Event triage** 👁️ | Spider 🕷️ | Watchful guardian | Sensor nodes, glowing web, radar arcs, notification symbols (bell, letter, calendar) | Dark purple, amber, soft cyan, warm grey |
|
||
| **Private Memory Lint** 🧹 | Firefly ✨ | Private memory caretaker | Glowing lantern, memory fragments, tiny notes, sparkles | Warm gold, amber, soft teal, gentle green |
|
||
| **Shared Memory Lint** 🧹 | Bee 🐝 | Shared space caretaker | Scroll with guidelines, honey dipper, honeycomb shapes, tiny documents | Warm amber, gold, soft teal, honey |
|
||
|
||
## Adding a new agent icon
|
||
|
||
1. Generate the image using the Vector Paintings prompt template above (include `VectorPaintDaal` at the start)
|
||
2. Save it as `agents/{agent_id}/icon.png`
|
||
3. Add `"icon": "icon.png"` to the agent's `meta.json` (if not already present)
|
||
4. No code changes needed — the backend serves whatever file path is declared in the manifest
|