@maincode-ai/matilda-code 0.21.13 → 0.22.0

package/bundled/mainy/docs/features/skills.md

@@ -1,347 +0,0 @@
-# Agent Skills
-
-> Create, manage, and share Skills to extend Matilda Code's capabilities.
-
-This guide shows you how to create, use, and manage Agent Skills in **Matilda Code**. Skills are modular capabilities that extend the model's effectiveness through organized folders containing instructions (and optionally scripts/resources).
-
-## Prerequisites
-
-- Matilda Code (recent version)
-- Basic familiarity with Matilda Code ([Quickstart](../quickstart.md))
-
-## What are Agent Skills?
-
-Agent Skills package expertise into discoverable capabilities. Each Skill consists of a `SKILL.md` file with instructions that the model can load when relevant, plus optional supporting files like scripts and templates.
-
-### How Skills are invoked
-
-Skills are **model-invoked** — the model autonomously decides when to use them based on your request and the Skill's description. This is different from slash commands, which are **user-invoked** (you explicitly type `/command`).
-
-If you want to invoke a Skill explicitly, use the `/skills` slash command:
-
-```bash
-/skills <skill-name>
-```
-
-Use autocomplete to browse available Skills and descriptions.
-
-### Benefits
-
-- Extend Matilda Code for your workflows
-- Share expertise across your team via git
-- Reduce repetitive prompting
-- Compose multiple Skills for complex tasks
-
-## Create a Skill
-
-Skills are stored as directories containing a `SKILL.md` file.
-
-### Personal Skills
-
-Personal Skills are available across all your projects. Store them in `~/.matilda/skills/`:
-
-```bash
-mkdir -p ~/.matilda/skills/my-skill-name
-```
-
-Use personal Skills for:
-
-- Your individual workflows and preferences
-- Skills you're developing
-- Personal productivity helpers
-
-### Project Skills
-
-Project Skills are shared with your team. Store them in `.matilda/skills/` within your project:
-
-```bash
-mkdir -p .matilda/skills/my-skill-name
-```
-
-Use project Skills for:
-
-- Team workflows and conventions
-- Project-specific expertise
-- Shared utilities and scripts
-
-Project Skills can be checked into git and automatically become available to teammates.
-
-## Write `SKILL.md`
-
-Create a `SKILL.md` file with YAML frontmatter and Markdown content:
-
-```yaml
----
-name: your-skill-name
-description: Brief description of what this Skill does and when to use it
-priority: 10
----
-
-# Your Skill Name
-
-## Instructions
-Provide clear, step-by-step guidance for Matilda Code.
-
-## Examples
-Show concrete examples of using this Skill.
-```
-
-### Field requirements
-
-Matilda Code currently validates that:
-
-- `name` is a non-empty string matching `/^[\p{L}\p{N}_:.-]+$/u` — Unicode letters and digits (CJK / Cyrillic / accented Latin all OK), plus `_`, `:`, `.`, `-`. Whitespace, slashes, brackets and other structurally unsafe characters are rejected at parse time.
-- `description` is a non-empty string
-- `priority` is optional. When present, it must be a finite number. Higher values sort earlier in the `/skills` listing only — slash-command completion (typing `/`) and the `/help` custom commands view stay alphabetical, so a high-priority Skill never reorders built-in commands. Omitted or invalid values are treated as unset, which behaves like `0`.
-
-Recommended conventions:
-
-- Prefer lowercase ASCII with hyphens for shareable names (e.g. `tsx-helper`)
-- Make `description` specific: include both **what** the Skill does and **when** to use it (key words users will naturally mention)
-- Use `priority` sparingly for Skills that should reliably appear before the default alphabetical order in `/skills`. Negative priorities are allowed and sort below unset Skills.
-
-### Optional: gate a Skill on file paths (`paths:`)
-
-For Skills that only matter to specific parts of a codebase, add a `paths:` list of glob patterns. The Skill stays out of the model's available-skills listing until a tool call touches a matching file:
-
-```yaml
----
-name: tsx-helper
-description: React TSX component helper
-paths:
-  - 'src/**/*.tsx'
-  - 'packages/*/src/**/*.tsx'
----
-```
-
-Notes:
-
-- Globs are matched relative to the project root with [picomatch](https://github.com/micromatch/picomatch); files outside the project root never trigger activation.
-- A path-gated Skill **stays activated for the rest of the session** once a matching file is touched. A new session, or a `refreshCache` triggered by editing any Skill file, resets activations.
-- `paths:` only gates **model** discovery, and only at the SkillTool listing level. Unless `user-invocable: false` is set, you can always invoke a path-gated Skill yourself via `/<skill-name>` or the `/skills` picker — that user path runs the Skill body regardless of activation state. The model side, however, stays gated until a matching file is touched: a slash invocation does **not** unlock model-side activation, so if you want the model to chain off your invocation (call `Skill { skill: ... }` itself), also access a file matching the skill's `paths:` first.
-- Combining `paths:` with `disable-model-invocation: true` is allowed but the gate has no effect — the Skill is hidden from the model regardless, so path activation never advertises it.
-
-### Optional: control user and model invocation
-
-Skills are user-invocable by default. To hide a Skill from direct slash-command use while keeping it available for model invocation, set `user-invocable: false`:
-
-```yaml
----
-name: model-only-helper
-description: Helper the model can call when appropriate
-user-invocable: false
----
-```
-
-This removes the Skill from `/<skill-name>` invocation and `/skills` picker results. It does not hide the Skill from the model.
-
-To hide a Skill from model invocation while keeping direct user invocation available, set `disable-model-invocation: true`:
-
-```yaml
----
-name: manual-helper
-description: Helper you invoke manually
-disable-model-invocation: true
----
-```
-
-You can combine both fields, but then the Skill is not reachable through the normal user or model invocation paths.
-
-## Add supporting files
-
-Create additional files alongside `SKILL.md`:
-
-```text
-my-skill/
-├── SKILL.md (required)
-├── reference.md (optional documentation)
-├── examples.md (optional examples)
-├── scripts/
-│   └── helper.py (optional utility)
-└── templates/
-    └── template.txt (optional template)
-```
-
-Reference these files from `SKILL.md`:
-
-````markdown
-For advanced usage, see [reference.md](reference.md).
-
-Run the helper script:
-
-```bash
-python scripts/helper.py input.txt
-```
-````
-
-## View available Skills
-
-Matilda Code discovers Skills from:
-
-- Personal Skills: `~/.matilda/skills/`
-- Project Skills: `.matilda/skills/`
-- Extension Skills: Skills provided by installed extensions
-
-### Extension Skills
-
-Extensions can provide custom skills that become available when the extension is enabled. These skills are stored in the extension's `skills/` directory and follow the same format as personal and project skills.
-
-Extension skills are automatically discovered and loaded when the extension is installed and enabled.
-
-To see which extensions provide skills, check the extension's `matilda-extension.json` file for a `skills` field.
-
-To view available Skills, ask Matilda Code directly:
-
-```text
-What Skills are available?
-```
-
-> **Heads up — model vs. user view.** Asking the model only surfaces Skills the model can currently see. If a Skill uses `paths:` (see "Optional: gate a Skill on file paths" above), it stays out of that listing until a matching file has been touched. The `/skills` slash command shows Skills you can invoke directly; Skills with `user-invocable: false` remain visible on disk and may still be visible to the model.
-
-Or browse the user-invocable list with the slash command (including path-gated Skills that have not activated yet):
-
-```text
-/skills
-```
-
-Or inspect the filesystem:
-
-```bash
-# List personal Skills
-ls ~/.matilda/skills/
-
-# List project Skills (if in a project directory)
-ls .matilda/skills/
-
-# View a specific Skill's content
-cat ~/.matilda/skills/my-skill/SKILL.md
-```
-
-## Test a Skill
-
-After creating a Skill, test it by asking questions that match your description.
-
-Example: if your description mentions "PDF files":
-
-```text
-Can you help me extract text from this PDF?
-```
-
-The model autonomously decides to use your Skill if it matches the request — you don't need to explicitly invoke it.
-
-## Debug a Skill
-
-If Matilda Code doesn't use your Skill, check these common issues:
-
-### Make the description specific
-
-Too vague:
-
-```yaml
-description: Helps with documents
-```
-
-Specific:
-
-```yaml
-description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction.
-```
-
-### Verify file path
-
-- Personal Skills: `~/.matilda/skills/<skill-name>/SKILL.md`
-- Project Skills: `.matilda/skills/<skill-name>/SKILL.md`
-
-```bash
-# Personal
-ls ~/.matilda/skills/my-skill/SKILL.md
-
-# Project
-ls .matilda/skills/my-skill/SKILL.md
-```
-
-### Check YAML syntax
-
-Invalid YAML prevents the Skill metadata from loading correctly.
-
-```bash
-cat SKILL.md | head -n 15
-```
-
-Ensure:
-
-- Opening `---` on line 1
-- Closing `---` before Markdown content
-- Valid YAML syntax (no tabs, correct indentation)
-
-### View errors
-
-Run Matilda Code with debug mode to see Skill loading errors:
-
-```bash
-matilda --debug
-```
-
-## Share Skills with your team
-
-You can share Skills through project repositories:
-
-1. Add the Skill under `.matilda/skills/`
-2. Commit and push
-3. Teammates pull the changes
-
-```bash
-git add .matilda/skills/
-git commit -m "Add team Skill for PDF processing"
-git push
-```
-
-## Update a Skill
-
-Edit `SKILL.md` directly:
-
-```bash
-# Personal Skill
-code ~/.matilda/skills/my-skill/SKILL.md
-
-# Project Skill
-code .matilda/skills/my-skill/SKILL.md
-```
-
-Changes take effect the next time you start Matilda Code. If Matilda Code is already running, restart it to load the updates.
-
-## Remove a Skill
-
-Delete the Skill directory:
-
-```bash
-# Personal
-rm -rf ~/.matilda/skills/my-skill
-
-# Project
-rm -rf .matilda/skills/my-skill
-git commit -m "Remove unused Skill"
-```
-
-## Best practices
-
-### Keep Skills focused
-
-One Skill should address one capability:
-
-- Focused: "PDF form filling", "Excel analysis", "Git commit messages"
-- Too broad: "Document processing" (split into smaller Skills)
-
-### Write clear descriptions
-
-Help the model discover when to use Skills by including specific triggers:
-
-```yaml
-description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or .xlsx data.
-```
-
-### Test with your team
-
-- Does the Skill activate when expected?
-- Are the instructions clear?
-- Are there missing examples or edge cases?