Skills

Skills are Markdown files with optional YAML frontmatter parsed by crates/core/src/skills/frontmatter.rs.

Skill Locations

Discovery order (first match wins by name):

Project directory-style: .swarmie/skills/<name>/SKILL.md
Project flat legacy: .skills/<name>.md
User directory-style: ~/.swarmie/skills/<name>/SKILL.md
System skills: $SWARMIE_HOME/skills/.system/<name>/SKILL.md
Admin skills: /etc/swarmie/skills/<name>/SKILL.md

Implemented in SkillsManager (crates/core/src/skills/manager.rs).

Frontmatter Schema

Supported frontmatter keys (SkillFrontmatter):

Key	Type	Purpose
`name`	string	Display/command name override.
`description`	string	Skill description.
`user-invocable`	bool	Enables slash invocation as `/skill-name ...`.
`disable-model-invocation`	bool	Hide from model-driven skill execution.
`allowed-tools`	array(string)	Skill tool allowlist hint.
`model`	string	Skill-specific model preference.
`context`	string	`fork` for subagent execution context.
`agent`	string	Subagent type when using fork context.
`argument-hint`	string	UI hint shown in pickers.
`hooks`	table	Optional hooks config on skill.
`policy`	table	Includes `allow-implicit-invocation`.
`interface`	table	`display-name`, `short-description`, `default-prompt`.
`dependencies`	table	Tool dependency metadata.
`permissions`	table	Skill network/file-system permissions metadata.
`unsafe`	bool	Reserved/no-op sandbox marker.

Example Skill

---
name: review
description: Review patch for risks
user-invocable: true
argument-hint: "<path>"
interface:
  short-description: Focused code review
dependencies:
  tools:
    - type: mcp
      value: github
permissions:
  network: true
  file-system:
    read: ["src", "docs"]
    write: []
---
 
Review the diff in $ARGUMENTS and summarize risks.

Arguments

substitute_arguments() supports:

$ARGUMENTS (full argument string)
$ARGUMENTS[0]..[9]
$0..$9 shorthand

Defined in crates/core/src/skills/loader.rs.

`/skills` Picker

TUI integration:

/skills opens the Manage Skills dialog.
Core sends Op::SkillsList and returns Event::AvailableSkills.
Space toggles enabled state in the picker.
Enter sends Op::SkillVisibility { name, enabled } diffs for changed skills.
Disabled skill paths are persisted in ~/.swarmie/config.toml under [skills].disabled.

Relevant files:

crates/tui/src/input/slash.rs
crates/tui/src/app/update/commands.rs
crates/tui/src/app/update/pickers.rs
crates/tui/src/app/update/modals.rs
crates/core/src/submission/op_handlers.rs
crates/core/src/skills/manager.rs

Built-in System Skills

Swarmie embeds and installs system skills:

skill-creator
skill-installer