Dark-Alex-17/coyote
1
0
Fork 0
Code Issues Pull Requests Actions 9 Packages Projects Releases Wiki Activity

docs: added documentation for the new skill system

Alex Clarke
2026-06-01 16:35:44 -06:00
parent 967ce8cf5c
commit 1bdfa16507
5 changed files with 322 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Home.md
+1
@@ -39,6 +39,7 @@ Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration g
* [RAG](RAG): Retrieval-Augmented Generation for enhanced information retrieval and generation.
* [Sessions](Sessions): Manage and persist conversational contexts and settings across multiple interactions.
* [Roles](Roles): Customize model behavior for specific tasks or domains.
* [Skills](Skills): Modular knowledge or capability packs the LLM can load and unload mid-conversation. Multiple skills compose; instructions stack, tools and MCPs union.
* [Agents](Agents): Leverage AI agents to perform complex tasks and workflows, including sub-agent spawning, teammate messaging, and user interaction tools.
* [Graph Agents](Graph-Agents): Define an agent as a declarative, YAML-driven workflow. A directed graph of typed nodes (LLM calls, scripts, approvals, user input, RAG retrieval, sub-agent spawns).
* [Todo System](TODO-System): Built-in task tracking for improved agent reliability with smaller models.
REPL.md
+25 -6
@@ -74,6 +74,22 @@ cannot be persisted to a file and saved.
![prompt-role](./images/roles/prompt-role.gif)
## `.skill` - Skill management
Skills are modular knowledge or capability packs the LLM can load and unload mid-conversation. Multiple skills can be
loaded at once; their instructions stack and their tools/MCP servers union with the active role/agent/session.
| Command | Description |
|------------------------|---------------------------------------------------------------------------------------------------|
| `.skill loaded` | List currently-loaded skills in this session |
| `.skill load <name>` | Load a skill into the current context (validates policy + compatibility, then refreshes scope) |
| `.skill unload <name>` | Unload a loaded skill, releasing any MCP servers it pulled in |
| `.skill <name>` | Open the skill in `$EDITOR`. Creates a scaffolded `SKILL.md` if missing |
To edit an existing skill without the create-if-missing fallback, use `.edit skill <name>` (see the [.edit](#edit-modify-configuration-files) section).
For more information about skills, including frontmatter fields, visibility/enforcement, auto-unload behavior, and the
bundled built-in skills, see the [skills documentation](Skills).
## `.session` - Session management
Use the following commands to manage sessions in Coyote:
@@ -222,6 +238,7 @@ configuration in your preferred text editor. It lets you modify the following co
* `.edit session` - Modify the active session's configuration
* `.edit agent-config` - Modify the active agent's configuration
* `.edit rag-docs` - Add or remove documents from the active RAG
* `.edit skill <name>` - Modify an existing skill by name
## `.delete` - Delete configurations from Coyote
The `.delete` command allows you to delete entities in Coyote without having to directly run `rm -rf` on the configuration
@@ -230,6 +247,7 @@ directory or file corresponding to the target entity. You can use it to delete t
* `.delete role` - Delete select roles
* `.delete session` - Delete select sessions
* `.delete macro` - Delete select macros
* `.delete skill` - Delete select skills
* `.delete rag` - Delete select RAGs
* `.delete agent-data` - Delete select agent's configurations and all tools
@@ -243,6 +261,7 @@ when an update ships improved built-ins you want to adopt.
|-----------------------|----------------------------------------------------------------------|
| `.install agents` | Reinstall the built-in agents |
| `.install macros` | Reinstall the built-in macros |
| `.install skills` | Reinstall the built-in skills |
| `.install functions` | Reinstall the built-in tool functions (leaves your `mcp.json` alone) |
| `.install mcp_config` | Replace `mcp.json` with the bundled template (see warning below) |
@@ -260,12 +279,12 @@ only overwrite Coyote's built-in assets and leave your custom ones alone.
The `.install remote` command installs agents, roles, macros, tools, and MCP servers from any git repository whose
layout mirrors Coyote's user config directory. This is the primary mechanism for sharing and reusing Coyote configurations.
| Command | Description |
|--------------------------------------------------------------------|------------------------------------------------------------|
| `.install remote <git-url>` | Install everything the repo provides |
| `.install remote <git-url>#<ref>` | Pin to a tag, branch, or commit (e.g. `#v1.0.0`, `#main`) |
| `.install remote <git-url> --filter <category>` | Restrict to one of `agents`, `roles`, `macros`, `functions`, `mcp_config` |
| `.install remote <git-url> --force` | Skip all conflict prompts; overwrite local files unconditionally |
| Command | Description |
|-------------------------------------------------|-------------------------------------------------------------------------------------|
| `.install remote <git-url>` | Install everything the repo provides |
| `.install remote <git-url>#<ref>` | Pin to a tag, branch, or commit (e.g. `#v1.0.0`, `#main`) |
| `.install remote <git-url> --filter <category>` | Restrict to one of `agents`, `roles`, `skills`, `macros`, `functions`, `mcp_config` |
| `.install remote <git-url> --force` | Skip all conflict prompts; overwrite local files unconditionally |
The CLI equivalent is `coyote --install-from <git-url>` (with `--filter` and `--install-force` accepting the same values).
Sharing-Configurations.md
+12 -8
@@ -53,6 +53,9 @@ Coyote recognizes these top-level directories. Anything outside them is ignored.
│ └── scripts/ # Optional graph-node scripts
├── roles/
│ └── <role-name>.md # Markdown with YAML frontmatter + prompt body
├── skills/
│ └── <skill-name>/ # One subdirectory per skill
│ └── SKILL.md # YAML frontmatter + body
├── macros/
│ └── <macro-name>.yaml # Positional/rest variables + REPL command steps
└── functions/
@@ -96,14 +99,15 @@ the ref from being interpreted as a CLI flag or escaping the repo via path trave
Restrict the install to a single asset category with `--filter`:
| Filter | Installs |
|----------------|------------------------------------------------|
| *(omitted)* | `agents/`, `roles/`, `macros/`, `functions/tools/`, and merges `functions/mcp.json` |
| `agents` | `agents/` only |
| `roles` | `roles/` only |
| `macros` | `macros/` only |
| `functions` | `functions/tools/` only (does **not** include `mcp.json`) |
| `mcp_config` | `functions/mcp.json` only (merged) |
| Filter | Installs |
|--------------|------------------------------------------------------------------------------------------------|
| *(omitted)* | `agents/`, `roles/`, `skills/`, `macros/`, `functions/tools/`, and merges `functions/mcp.json` |
| `agents` | `agents/` only |
| `roles` | `roles/` only |
| `skills` | `skills/` only |
| `macros` | `macros/` only |
| `functions` | `functions/tools/` only (does **not** include `mcp.json`) |
| `mcp_config` | `functions/mcp.json` only (merged) |
```sh
coyote --install-from <git-url> --filter agents
Skills.md
+277
@@ -0,0 +1,277 @@
Skills are modular knowledge or capability packs that an LLM can load and unload mid-conversation. Think of them as
roles' lightweight cousins: where a [Role](Roles) defines the assistant's identity (single-active, switched explicitly by
the user), a skill is a capability the model layers onto whatever role/agent/session is already active.
Multiple skills can be loaded at once. They compose, meaning their instructions stack, their tool whitelists union, and
their declared MCP servers get acquired automatically.
Common uses:
- **Methodology overlays** ("how to do git surgery", "how to review code").
- **Toolkit unlocks** that grant a small bundle of tools or MCP servers without changing the active role.
- **One-shot helpers** that auto-unload after the model finishes a task (see [auto_unload](#auto-unload)).
---
# Skill Definition
Skills in Coyote are directories under your Coyote configuration's `skills/` directory, each containing a `SKILL.md`
file. To find your skills directory:
```shell
coyote --info | grep 'skills_dir' | awk '{print $2}'
```
The on-disk layout:
```
<coyote-config-dir>/skills/
└── <skill-name>/
└── SKILL.md # YAML frontmatter + body
```
**Example:** A skill that teaches the model git conventions and grants shell access for running git commands.
`skills/git-master/SKILL.md`:
```markdown
---
description: Atomic commits, rebase methodology, conflict resolution.
enabled_tools: execute_command
---
You are operating on a git repository. Apply these conventions strictly. Use the `execute_command` tool to run git
commands.
## Atomic commits
Each commit represents one logical change. If the commit message needs the word "and," the change is too large; split
it.
## Commit messages
- Subject line: imperative mood, ≤50 characters, no trailing period.
- Blank line.
- Body: explain WHY, not WHAT.
```
To see complete examples, look at the [bundled built-in skills](https://github.com/Dark-Alex-17/coyote/tree/main/assets/skills).
## Frontmatter
The YAML frontmatter at the top of `SKILL.md` is where you declare the skill's metadata and what extra capabilities it
grants when loaded. All fields are optional.
| Field | Default | Description |
|-----------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `description` | empty | Short one-line description shown to the model when it lists available skills. Make it specific: this is what helps the model decide when to load. |
| `enabled_tools` | none | Comma-separated tool names that become available while the skill is loaded. Union with the active role/agent/session's tools. Tools must exist in [visible tools](Tools). |
| `enabled_mcp_servers` | none | Comma-separated MCP server names. Skills can reference servers from your `mcp.json`; those servers are auto-acquired on load and released on unload via reference counting. |
| `auto_unload` | `false` | If `true`, the skill is automatically removed from the registry at the end of every turn where the model produced a final response (no more tool calls). |
## Body
Everything after the frontmatter is the **skill body**; i.e. the instructional content that gets injected into the model's
system prompt while the skill is loaded. This is where the methodology, conventions, or workflow guidance lives.
Bodies stack in load order: if you load `git-master`, then `ai-slop-remover`, the system prompt contains the active
role's prompt followed by `git-master`'s body followed by `ai-slop-remover`'s body, separated by blank lines.
There is no length limit, but keep skill bodies focused. If you find yourself writing a manual, split it into multiple
skills the model can load in combination.
---
# Skills vs. Roles
| | Skill | Role |
|--------------|-------------------------------------------------------------------------------|----------------------------------------------------------|
| Activation | Model-driven (via the `skill__load` tool) or user-driven (via `.skill load`). | User-driven (via `.role <name>` or `--role <name>`). |
| Cardinality | Multiple loaded at once; bodies stack, tools/MCPs union. | One active at a time; switching exits the previous role. |
| Lifecycle | Loaded mid-conversation; can auto-unload at turn end. | Active for the whole session until explicitly exited. |
| Mental model | "Add this capability to my context." | "Be this kind of assistant." |
Use a role when you want to *be* a SQL expert or a resume builder. Use a skill when you want to *temporarily augment*
your current context with git knowledge, frontend conventions, or any other modular capability.
---
# Managing Skills
## REPL commands
| Command | Effect |
|---------------------------------------------|--------------------------------------------------------------------------------------------------|
| `.skill loaded` | List currently-loaded skills in this session. |
| `.skill load <name>` | Load a skill. Validates policy + compatibility, then refreshes the tool scope. |
| `.skill unload <name>` | Unload a loaded skill. Releases any MCP servers it pulled in. |
| `.edit skill <name>` | Open an existing skill in `$EDITOR` (fails if the skill doesn't exist). |
| `.skill <name>` | Open the skill in `$EDITOR`. Creates a scaffolded `SKILL.md` if missing. |
| `.delete skill` | Interactive prompt to choose installed skills to delete. |
| `.install skills` | Reinstall all bundled built-in skills, overwriting existing copies after confirmation. |
| `.install remote <git-url> --filter skills` | Install only `skills/` from a remote repo. See [Sharing Configurations](Sharing-Configurations). |
## CLI flags
| Flag | Effect |
|-----------------------------------------------|--------------------------------------------------------------------------------------------|
| `coyote --list-skills` | Print installed skill names, one per line. |
| `coyote --skill <NAME>` | If the skill exists, load it and proceed to REPL or one-shot. If missing, scaffold + edit. |
| `coyote --skill <A> --skill <B> [...]` | Pre-load multiple skills in argument order. All must exist; fails fast if any is missing. |
| `coyote --install skills` | Reinstall all bundled built-in skills. |
| `coyote --install-from <url> --filter skills` | Install only `skills/` from a remote repo. |
`coyote --skill <name>` composes naturally with `--role`, `--agent`, and a one-shot prompt:
```shell
coyote --role frontend --skill git-master "rebase main into this branch and resolve conflicts"
```
This activates the `frontend` role, loads the `git-master` skill on top, and runs the prompt with both in effect.
---
# Visibility and Enforcement
Skills respect a layered visibility/enforcement model. You can scope which skills are available globally and per-context.
## Global config
In your `config.yaml`:
```yaml
skills_enabled: true # master switch (default true)
visible_skills: [git-master, code-review, ai-slop-remover] # the universe; omit for "all installed"
enabled_skills: [git-master, ai-slop-remover] # default-active subset in the blank context
```
- **`skills_enabled: false`** at the global level turns skills off entirely. The `skill__list`/`skill__load`/`skill__unload`
tools are not exposed to the model. Equivalent to skills not existing.
- **`visible_skills`** declares the universe — the set of skills allowed to be referenced by any context. If omitted,
all installed skills are eligible.
- **`enabled_skills`** is the default-active subset in the no-role/no-agent/no-session context. Skills outside this list
are not loadable in the default REPL.
## Role, agent, and session overrides
Each of these contexts can independently set `skills_enabled` and `enabled_skills`. Precedence:
- **`skills_enabled`:** Any level setting `false` wins. Once disabled at any level, the master switch is off for that
context.
- **`enabled_skills`:** Most-specific-wins: `session > agent > role > global`. The first level that sets `enabled_skills`
to `Some([...])` is the effective list for that turn.
Example role that opts into a different skill set than the global default:
```markdown
---
name: frontend-dev
enabled_skills: git-master, ai-slop-remover, frontend-ui-ux
---
You are a frontend specialist.
```
When this role is active, the model sees exactly those three skills in `skill__list`. Any other installed skill is
filtered out of the response and cannot be loaded. `skill__load` rejects it with `"Skill 'X' is not enabled in this context"`.
## Validation
Three validation points enforce these rules:
| Where | What is checked | Severity |
|------------------------|---------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| **Config load** | Every name in any `enabled_skills` exists on disk AND is in global `visible_skills` (when `visible_skills` is set). | **Hard error**. Refuses to start with the offending name + level. |
| **Runtime list/build** | For each enabled skill: declared tools require function calling; declared MCPs require MCP support. | **Filter + warn**. Incompatible skills are dropped from `skill__list`. |
| **`skill__load` call** | Skill is in the effective enabled set AND compatible with current feature flags. | **Tool error to model** with a distinct message per failure mode. |
---
# Auto-unload
Skills with `auto_unload: true` in their frontmatter are removed from the registry at the end of each turn. Specifically,
after the model produces a final response with no further tool calls. They survive through multi-step tool-using rounds
within a single turn, but the next user message starts with the registry cleaned.
Use this for one-shot capabilities the model needs for a focused task and shouldn't carry into unrelated next turns.
```yaml
---
description: Untangle a complex git rebase.
enabled_tools: execute_command
auto_unload: true
---
```
After the model finishes a rebase request, the skill quietly removes itself. The user's next question won't have rebase
context in its system prompt.
**MCP server caching.** When an `auto_unload` skill declared MCP servers in its `enabled_mcp_servers`, those server
processes are kept running until the next role/agent/session switch (when the full tool scope rebuilds). This is
intentional: if the skill is reloaded later in the same session, the MCP server is already warm and the reload is
instantaneous. The model can't invoke those servers in subsequent turns because they're no longer in the effective MCP
whitelist — but their processes stay cached for fast re-load.
---
# Built-in Skills
Coyote ships with four built-in skills, installed automatically on first run:
| Skill | Granted tools | Purpose |
|-------------------|--------------------------------------------------------------------------|-------------------------------------------------------------------------|
| `git-master` | `execute_command` | Atomic commits, rebase methodology, conflict resolution, investigation. |
| `code-review` | `fs_read, fs_grep, fs_glob, fs_cat, fs_ls` | Correctness/tests/clarity/coupling/footguns review checklist. |
| `ai-slop-remover` | none (knowledge-only) | Detect and remove AI slop from code and prose. |
| `frontend-ui-ux` | `fs_read, fs_write, fs_patch, fs_grep, fs_glob, fs_cat, fs_ls, fs_mkdir` | Designer-turned-developer crafting UI/UX even without mockups. |
Each is intentionally short — they're starter templates. Fork them via `.skill <name>` to customize.
To reinstall the bundled built-ins (e.g., to restore a built-in you've modified):
```shell
coyote --install skills
# or in the REPL:
.install skills
```
This overwrites every bundled skill in your skills directory after a confirmation prompt. Local skills you created
yourself are left untouched.
---
# Sharing Skills
Skills install via the same [Sharing Configurations](Sharing-Configurations) flow as other Coyote assets. A remote repo
laid out as:
```
<repo>/
└── skills/
└── <skill-name>/
└── SKILL.md
```
installs with:
```shell
coyote --install-from https://github.com/<owner>/<repo>
# or just the skills/:
coyote --install-from https://github.com/<owner>/<repo> --filter skills
```
See [Sharing Configurations](Sharing-Configurations) for the full layout, ref pinning, conflict resolution, and secrets
handling. Skills follow the standard per-file conflict prompts.
---
# Programmatic Tools
When skills are enabled, the model has three tools available for managing them itself:
| Tool | Parameters | Effect |
|-----------------|----------------|-----------------------------------------------------------------------------------------|
| `skill__list` | none | Returns each available skill's name, description, granted tools/MCPs, and loaded state. |
| `skill__load` | `name: string` | Loads a skill after validating policy + compatibility. Refreshes the tool scope. |
| `skill__unload` | `name: string` | Unloads a loaded skill. Releases its MCP server handles. |
These are how the model discovers and uses skills mid-conversation. You can disable this discovery channel by setting
`skills_enabled: false` at any level; the three tools then disappear from the model's function list entirely.
_Sidebar.md
+7
@@ -48,6 +48,13 @@
- [RAG](RAG)
- [Macros](Macros)
- [Roles](Roles)
- [Skills](Skills)
- [Frontmatter](Skills#frontmatter)
- [Skills vs. Roles](Skills#skills-vs-roles)
- [Managing Skills](Skills#managing-skills)
- [Visibility and Enforcement](Skills#visibility-and-enforcement)
- [Auto-unload](Skills#auto-unload)
- [Built-in Skills](Skills#built-in-skills)
- [TODO System](TODO-System)
## Configuration