Agent Skills

​

Overview

1. Index in the system prompt: Xum lists available skills (name + description).
2. Tool-based loading: the agent calls tools to load a full skill when needed.

npx skills add https://github.com/anthropics/skills --skill frontend-design

​

Where skills live

• Project: .xum/skills/<skill-name>/SKILL.md
• Project (cross-tool): .agents/skills/<skill-name>/SKILL.md
• Global (Xum-specific): ~/.xum/skills/<skill-name>/SKILL.md
• Universal (cross-tool): ~/.agents/skills/<skill-name>/SKILL.md
• Built-in: shipped with Xum

​

Claude Code compatibility (experiment)

• Workspace-local: .claude/skills/<skill-name>/SKILL.md
• Global: ~/.claude/skills/<skill-name>/SKILL.md

​

Agent Plugins

• Workspace-local: .xum/plugins/<plugin>/ and .agents/plugins/<plugin>/
• Global: ~/.xum/plugins/<plugin>/ and ~/.agents/plugins/<plugin>/

​

Component review

1. Open Settings → Plugins. Each plugin that needs a review shows needs review, and a notice at the top explains what does not load until you review it.
2. Select Review on the plugin. The review lists each skill, MCP server, workflow script, agent and slash command with the fields you approve.
3. Select Approve components to load them. You can also run Review Plugin Components… from the command palette.

​

Plugin skill namespaces

• A bare name keeps the precedence above. If you have a global tdd skill, tdd loads your skill and pstack:tdd loads the skill from the pstack plugin.
• A qualified name only loads a skill from the named plugin. It never falls back to a project, global, or built-in skill. If a project plugin and a global plugin have the same plugin name, the project plugin wins.
• If two plugins ship the same skill name, the bare name loads the first one, and each stays reachable as alpha:tdd and beta:tdd.
• When a plugin skill loses its bare name to another skill, the model’s skill index lists it under its qualified name. Plugin skills that win their bare name are listed only once, under the bare name.
• A qualified name with no match (for example nope:tdd or pstack:missing) fails with Agent skill not found: <name>.

• agent_skill_read, /skill, and $skill put a one-line note at the top of the plugin skill. The note maps each shadowed sibling to its qualified name, for example tdd -> pstack:tdd.
• agent_skill_read_file adds the same note in a pluginSkillNote field when it reads a file of a plugin skill. The file content does not change.
• The note lists only skills of the same plugin, at most 30. Xum adds no note when no sibling is shadowed.
• Bare-name lookups keep the precedence above. The note does not change which skill a name loads.

​

Skill layout

.xum/skills/
  my-skill/
    SKILL.md
    references/
      ...

​

Bundled files and the skill directory

• The agent_skill_read result includes skillDir, the absolute path of the skill’s directory. Plugin skills also get pluginRoot, the absolute path of the plugin. Both paths are valid where the workspace’s bash runs, so the agent can run a bundled script or pass the path to a sub-agent.
• Xum replaces these placeholders in the skill body. They use the same names as Claude Code, so skills written for Claude Code work unchanged:
  • ${CLAUDE_SKILL_DIR}: the skill’s directory.
  • ${CLAUDE_PLUGIN_ROOT}: the plugin’s directory. Xum replaces it only in plugin skills.

---
name: release-notes
description: Draft release notes from merged PRs
---

Run `sh "${CLAUDE_SKILL_DIR}/scripts/collect.sh"` and summarize its output.

​

SKILL.md format

• name: must match the directory name (see Display names)
• description: short summary shown in Xum’s skills index

• license
• compatibility
• metadata (string key/value map)
• disable-model-invocation (boolean) — set to true to omit a skill from the system prompt index (see Unadvertised skills below). This spelling is shared with other agent tools such as Claude Code, so portable skills work unchanged.
• advertise (boolean) — Xum-specific equivalent: advertise: false behaves like disable-model-invocation: true. If both are set, the opt-out wins.
• user-invocable (boolean) — set to false to hide a skill from user-facing invocation surfaces (see Controlling who invokes a skill).
• argument-hint (string) — short hint describing the arguments a skill expects (for example [issue-number]), shown next to the skill in invocation UIs (see Skill arguments).
• when_to_use (string) — extra model-facing guidance appended to the skill’s entry in the skills index. The kebab-case spelling when-to-use is also accepted; the underscore spelling wins if both are set.
• paths (list or comma-separated string) — globs that limit the skill to matching files (see Path-scoped skills).

​

Display names

• Invoke the skill as /poteto-mode.
• The agent loads it with agent_skill_read({ name: "poteto-mode" }).
• A plugin skill is also reachable as <plugin>:poteto-mode.

​

Controlling who invokes a skill

​

Unadvertised skills

• Are not listed in the system prompt (reducing token overhead)
• Can still be invoked via /{skill-name} slash command or agent_skill_read({ name: "skill-name" })
• Still appear in Xum’s UI lists (for example / slash suggestions) and in ACP clients’ command lists
• Are useful for: skills meant only for sub-agents, advanced users, or internal orchestration

​

Path-scoped skills

---
name: ts-rules
description: TypeScript conventions for this repo.
paths: ["**/*.ts", "**/*.tsx"]
---

• Syntax: a YAML list, or one comma-separated string (paths: "src/**/*.ts, *.{ts,tsx}"). In the string form, a comma inside {} belongs to the glob, and patterns with [ or ( (character classes, extglobs) need the list form.
• Matching: each glob is relative to the workspace root. **/*.ts matches foo.ts and src/foo.ts. Files in dot folders (for example .github/) match too. Files outside the workspace never match.
• Trigger: a successful file_read or file_edit_* call on a matching file. Calls made from inside code_execution do not trigger it.
• What the model gets: the tool result gets a path_skills field with the skill name and description, and asks the model to read the skill with agent_skill_read. Xum does not insert the skill body. Each skill surfaces at most once per context window. Xum skips it if the model already read the skill in that window.
• Limits: at most 3 skills surface per tool call, and only the first 100 model-invocable path-scoped skills can activate.
• Index: path-scoped skills are not in the model-facing skills index. They stay readable by name and invocable with /{skill-name}.
• disable-model-invocation: true wins: a skill with both keys never surfaces on its own. It loads only when invoked explicitly.
• Invalid patterns: an empty list, an unclosed bracket, an empty entry, a negated pattern (!…), a backslash (use /), an absolute path, or a .. segment makes the whole skill invalid. Xum shows it with the error in the skills indicator and loads the other skills.

​

Example: deep-review skill

---
name: deep-review
description: Sub-agent powered code reviews spanning correctness, tests, consistency, and fit
advertise: false
---

# Deep Review Mode

Provide an **excellent code review** by defaulting to **parallelism**.

You should use sub-agents to review the change from multiple angles (correctness, tests, consistency, UX, performance, safety). Each sub-agent should have a focused mandate and return actionable findings with file paths.

## Step 0: Establish the review surface

Before reviewing, gather context:

- Identify the change scope: `git diff --name-only` (or the file list the user provides).
- Skim the diff for intent and risk: `git diff`.
- Note which layers are touched:
  - UI (React/components/styles)
  - Main process / backend services
  - IPC boundary / shared types
  - Tooling/scripts
  - Docs
  - Tests

If the change is large, split review by module and prioritize **high-risk** paths.

## Spawn the right sub-agents (change-type aware)

Spawn **2–5** sub-agents depending on scope. Tailor them to the change.

### Suggested sub-agent set

- **Correctness & edge cases** (always)
  - Goal: find logic bugs, missing error handling, race conditions, broken invariants.
- **Tests & verification** (always)
  - Goal: evaluate test coverage, propose missing tests, suggest commands to validate.
- **Consistency & architecture** (usually)
  - Goal: ensure changes match existing patterns, abstractions, and boundaries.
- **UX & accessibility** (when UI changed)
  - Goal: keyboard flows, a11y, visual consistency, empty/loading/error states.
- **Performance & reliability** (when hot paths / streaming / IO changed)
  - Goal: latency, unnecessary work, blocking calls, memory growth, resilience.
- **Docs & developer experience** (when docs/scripts/public API changed)
  - Goal: clarity, correctness, navigation updates, link integrity.

## Synthesize into a single excellent review

When sub-agent results arrive, produce a consolidated review with:

1. **Summary** (what changed + overall risk)
2. **Issues**
3. **Questions** (unknown intent; ask for clarification)
4. **Suggested validation plan** (commands + manual checks)

Issues should have a severity in form of:

| Severity | Description                              | Example                                                                                       |
| -------- | ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| P0       | Change must not be merged until resolved | Change would permanently break core workflows if merged.                                      |
| P1       | Change should not be merged              | New code will not work as expected due to severe bugs                                         |
| P2       | Consideration required before merging    | The change creates inconsistency / fragility                                                  |
| P3       | Minor issue                              | The change introduces a minor issue that may be addressed later                               |
| P4       | Long-term issue                          | The change raises concerns about long-term maintainability or may break under rare conditions |

### Review rubric

Use this rubric to avoid blind spots:

- **Correctness**: invariants, edge cases, error handling, races
- **Fitness**: does it meet the user goal, and does it match product constraints?
- **Tests**: coverage of new logic, regression tests, deterministic behavior
- **Consistency**: patterns, naming, types, boundaries, IPC typing
- **Maintainability**: complexity, duplication, readability
- **Performance**: hot paths, streaming, excessive re-renders/IO
- **Safety**: secrets, path traversal, injection risks, filesystem safety
- **DX**: logs, error messages, debuggability

## Anti-patterns

- **Single-threaded review** of a large change (spawn sub-agents).
- **Vague feedback** (“looks good”) without actionable items and file paths.
- **Non-verifiable suggestions** (always include a validation plan).
- **Scope creep** disguised as review (focus on minimal changes unless risk demands more).

​

Skill arguments

• $ARGUMENTS — the full argument text (123 high)
• $1 … $9 — whitespace-tokenized positional arguments ($1 is 123); absent positions become empty strings

• Tokenization is simple whitespace splitting; there are no shell quoting rules.
• Placeholders are substituted everywhere in the body, including code blocks.
• Only a single digit is consumed: $10 means $1 followed by a literal 0.
• If the body contains no placeholders, nothing changes: the arguments simply remain visible in your message (for example “Using skill deploy: 123”).
• Substitution applies only to slash invocations. Inline $skill-name references and model-initiated agent_skill_read loads receive the body without argument substitution (Xum still replaces the skill directory placeholders).

​

Dynamic context injection (experiment)

---
name: summarize-changes
description: Summarize uncommitted changes and flag risks
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above and list any risks you notice.

• Directives must occupy the whole line; mid-line !`...` is ignored.
• Directives run after argument substitution, so !`git log $1` sees resolved arguments.
• Commands run sequentially in the workspace directory, with a 10-second timeout and a 16KB output cap per command, and at most 10 directives per skill. A failing command injects its output plus an [exit code N] note instead of aborting the invocation.
• Directives run only when you invoke a skill (/{skill-name} or a $skill-name reference). Skills the model loads via agent_skill_read never run directives — the model cannot trigger command execution this way.
• Enabling the experiment requires flipping the toggle in Settings yourself; remote experiment rollout can never switch it on.

​

Current limitations

• Slash command invocation supports only a single skill as the first token (for example /{skill-name} or /{skill-name} ...).
• Skill bodies may be truncated when injected to avoid accidental mega-prompts.
• allowed-tools is not enforced by Xum (it is tolerated in frontmatter, but ignored).

​

Further reading

• Agent Skills overview
• What are skills? (progressive disclosure)
• Agent Skills specification
  • Directory structure
  • SKILL.md format
  • Frontmatter fields
  • Optional directories
  • Progressive disclosure
• Integrate skills into your agent (tool-based vs filesystem-based)
• Example skills (GitHub)
• skills-ref validation library (GitHub)