diff --git a/Home.md b/Home.md index e791962..3141b51 100644 --- a/Home.md +++ b/Home.md @@ -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. diff --git a/REPL.md b/REPL.md index 40d4fd9..59e1cd6 100644 --- a/REPL.md +++ b/REPL.md @@ -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 ` | Load a skill into the current context (validates policy + compatibility, then refreshes scope) | +| `.skill unload ` | Unload a loaded skill, releasing any MCP servers it pulled in | +| `.skill ` | 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 ` (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 ` - 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 ` | Install everything the repo provides | -| `.install remote #` | Pin to a tag, branch, or commit (e.g. `#v1.0.0`, `#main`) | -| `.install remote --filter ` | Restrict to one of `agents`, `roles`, `macros`, `functions`, `mcp_config` | -| `.install remote --force` | Skip all conflict prompts; overwrite local files unconditionally | +| Command | Description | +|-------------------------------------------------|-------------------------------------------------------------------------------------| +| `.install remote ` | Install everything the repo provides | +| `.install remote #` | Pin to a tag, branch, or commit (e.g. `#v1.0.0`, `#main`) | +| `.install remote --filter ` | Restrict to one of `agents`, `roles`, `skills`, `macros`, `functions`, `mcp_config` | +| `.install remote --force` | Skip all conflict prompts; overwrite local files unconditionally | The CLI equivalent is `coyote --install-from ` (with `--filter` and `--install-force` accepting the same values). diff --git a/Sharing-Configurations.md b/Sharing-Configurations.md index 126eefe..63515ed 100644 --- a/Sharing-Configurations.md +++ b/Sharing-Configurations.md @@ -53,6 +53,9 @@ Coyote recognizes these top-level directories. Anything outside them is ignored. │ └── scripts/ # Optional graph-node scripts ├── roles/ │ └── .md # Markdown with YAML frontmatter + prompt body +├── skills/ +│ └── / # One subdirectory per skill +│ └── SKILL.md # YAML frontmatter + body ├── macros/ │ └── .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 --filter agents diff --git a/Skills.md b/Skills.md new file mode 100644 index 0000000..9695deb --- /dev/null +++ b/Skills.md @@ -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: + +``` +/skills/ +└── / + └── 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 ` or `--role `). | +| 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 ` | Load a skill. Validates policy + compatibility, then refreshes the tool scope. | +| `.skill unload ` | Unload a loaded skill. Releases any MCP servers it pulled in. | +| `.edit skill ` | Open an existing skill in `$EDITOR` (fails if the skill doesn't exist). | +| `.skill ` | 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 --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 ` | If the skill exists, load it and proceed to REPL or one-shot. If missing, scaffold + edit. | +| `coyote --skill --skill [...]` | 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 --filter skills` | Install only `skills/` from a remote repo. | + +`coyote --skill ` 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 ` 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: + +``` +/ +└── skills/ + └── / + └── SKILL.md +``` + +installs with: + +```shell +coyote --install-from https://github.com// +# or just the skills/: +coyote --install-from https://github.com// --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. diff --git a/_Sidebar.md b/_Sidebar.md index e83fea6..ae42e13 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -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