Skills

Skills are reusable instruction bundles that give the agent specialized knowledge about your project, workflow, or domain. Each skill can define instructions, tool access policies, context-loading strategies, and memory behavior — all tailored to a specific task type.

Every turn, the agent sees a compact index of all available skills and can draw on them when relevant. You can also explicitly invoke a skill to inject its full content and activate its strategies.

Skills vs. AGENTS.md

	AGENTS.md	Skills
Purpose	Workspace-level instructions for every turn	Specialized instructions per workflow
Location	Single file at project root	.toporic/skills/<name>/SKILL.md
Loading	Always loaded automatically	On-demand (agent decides, or user invokes)
Tool control	None	tool_policy with allowed/denied lists
Context strategies	None	context_strategy for automatic context loading
Memory strategies	None	memory_strategy for artifact/task recall
Switching	Static	Multiple skills can be swapped per session

Creating a skill

A skill is a directory containing a SKILL.md file with YAML frontmatter. The directory name becomes the skill name.

---
description: "Rust coding conventions for the widget library"
tags: [rust, cargo, async]
version: "1.0"
context_strategy: RelevantCode
memory_strategy: RelatedArtifacts
tool_policy:
  allowed:
    - read_file
    - write_file
    - edit_file
    - run_command
    - search_files
---

## Instructions

- Always use `?` for error propagation.
- Follow naming conventions in `CONTRIBUTING.md`.
- Run `cargo clippy` before every commit.
- Prefer `iter()` over indexed loops.

Frontmatter fields

Field	Required	Type	Description
description	No	string	Short summary shown in the skill index
tags	No	[a, b] or - a / - b	Tags for fuzzy matching when the agent selects a skill
version	No	string	Version identifier (semver or free-form)
context_strategy	No	enum	How to load project context when the skill is invoked
memory_strategy	No	enum	How to recall past artifacts and tasks
tool_policy	No	object	Which tools the agent can use with this skill

Context strategies

Strategy	Behavior
RelevantCode	Runs RAG semantic search using the skill description as query, plus symbol search. Best for coding workflows.
DiffOnly	Runs git diff, git diff --cached, and git log -5 to see recent changes. Best for review workflows.
Documentation	Loads README.md, lists docs directories. Best for research and onboarding.
RepositoryOverview	Lists top-level directory structure and builds a repo map summary. Best for project-wide refactors.
ModuleGraph	Planned — full dependency graph analysis across languages.
None	No automatic context loading.

Memory strategies

Strategy	Behavior
RecentArtifacts	Planned — loads recently produced code and test results.
RelatedArtifacts	Planned — loads artifacts related to the current task via embeddings.
HistoricalTasks	Loads .toporic/tasks/todo.md for past task context. Best for resuming long-running work.
Combined	Planned — combines multiple memory strategies.
None	No historical memory loading.

Tool policies

Control which tools the agent can access when this skill is active.

tool_policy:
  allowed:
    - read_file
    - write_file
    - run_command
  denied:
    - delete_file

• If allowed is set, only those tools are available.
• If only denied is set, all tools except those listed are available.
• If neither is set, all tools are available (default).

Tool policies take effect only when the skill is explicitly invoked — there is no background filtering.

Discovery paths

Skills are discovered from three locations in priority order (highest first):

1. {workspace_root}/.toporic/skills/ — project-local
2. ~/.toporic/skills/ — user-wide
3. /etc/toporic/skills/ — system-wide

A higher-priority skill with the same name completely shadows lower-priority ones. Run toporic init to scaffold .toporic/skills/ in your project.

How skills work

Every turn, Toporic injects a compact skill index into the system prompt:

Available skills (the model may use any when relevant; invoke manually with /skill <name>):
  /coding-agent — File system and shell automation
  /research-agent — Web research and content synthesis
  /assistant-agent — General conversational assistant

The agent uses this index to understand what guidance is available without loading every skill’s full content.

Invoking a skill

Manual invocation

Type the slash command in the TUI input:

/skill rust

The full skill content (instructions, strategies, tool policy) is loaded for the current session. Tool access is updated immediately based on the skill’s tool_policy.

Other slash commands:

Command	Action
/skill list	Show all available skills with descriptions
/skill <name>	Invoke a specific skill

Agent-initiated loading

The agent can load a skill on its own by calling the load_skill tool during execution. When it detects a task would benefit from a specific skill, it loads that skill and its strategies activate for subsequent turns.

Multi-agent skill selection

In multi-worker mode (complex tasks), workers automatically select the most appropriate skill:

1. Explicit mention — task description contains "use <skill-name>"
2. Tag matching — task description keywords match skill tags
3. Role default — Coding workers get coding-agent, Research workers get research-agent, etc.
4. None — worker uses its built-in prompt

Switching or clearing a skill

Use /session --new to start a fresh session with no active skill. Invoke a different skill with /skill <name> to swap.