Skills

Skills

A skill is a reference document — a how-to that a Personas can point to in its skills: frontmatter list. Skills are not auto-injected into the model's context; they're material the persona's body can quote or summarize.

Source: src/main/config-loader.ts. Defaults: resources/defaults/skills/. User overrides: <userData>/clusterspace-data/config/skills/.

---

The 2 defaults

terminal-automation

Patterns for running shell automation through the AI tools:

• Sequential flows — declare_step → write_to_terminal → wait → verify_step
• Parallel flows — coordinating two panes via wait_for_agent / complete_task
• Error detection — patterns to watch for in wait_for_output
• Timeout strategy — different wait_timeout_ms for shell vs Claude Code vs interactive
• Terminal-type modes — when to set terminal_type to shell / claude_code / interactive so completion patterns match

claude-code-interaction

Patterns specific to orchestrating Claude Code CLI instances from another AI:

• How to read Claude Code's prompts (>, ?, [Y/n], "What would you like…")
• Why Claude Code operations need long timeouts (typical 60–120 seconds)
• How to detect when Claude Code is "thinking" vs idle
• When to use write_to_terminal vs wait_for_output
• Error patterns (Error:, Tokens:, etc.)

---

Skill file format

---
id: terminal-automation
name: "Terminal Automation"
domain: tool_integration
description: "Patterns for sequential and parallel terminal flows"
prerequisites:
  - shell_familiarity
  - basic_unix
---

## Patterns

### Sequential
1. declare_step with explicit success_criteria
2. write_to_terminal (press_enter=true, appropriate wait_timeout_ms)
3. read tail of output via the returned tool result
4. verify_step (passed: true|false, observation)

### Parallel
…

The frontmatter is advisory; the body is the doc that humans (and personas) read.

---

How skills are actually used

There is no runtime "skill loading" — the model never sees a skill document automatically just because a persona lists it. Skills become operative only when:

1. The persona's body inlines or summarizes the skill content (then the model sees it as part of the system prompt), or
2. You author a tool that returns the skill markdown on request (the model can call it and receive the skill content as a tool result), or
3. A human reads the skill while authoring a persona and bakes the patterns into the persona's body

This is intentional — skills are designed for persona authors, not for the model directly. They let multiple personas reference the same patterns without duplication.

---

Loading order

Same as personas:

1. Built-in defaults from resources/defaults/skills/
2. User overrides from <userData>/clusterspace-data/config/skills/
3. User overrides win on name collision

Reload requires app restart.

---

See also

• Personas — how personas reference skills
• Writing-Personas — practical authoring guide
• Plugin-Authoring — write a tool that exposes skill content to the model on request