skill-auto-select

# Skill Auto-Select Design a Skill (or a whole Plugin) so an LLM agent can reliably discover it, decide it is the right one, and invoke it. Mirrors the design of Codex's `codex-rs/skills/` runtime, which is what this very Plugin is mimicking. ## When to use Activate when designing: - A new skill's frontmatter (`name`, `description`, `short_description`, `interface`, `dependencies`, `policy`). - A skill marketplace or registry where multiple skills may collide on name. - A path-based discovery surface (logical discovery path vs canonical path). - An explicit-vs-implicit invocation model (structured input vs `$name` mention vs shell command invocation). ## When NOT to use - Skills that are bundled, not selectable (e.g. always-on system skills). Use a different distribution model. - One-shot scripts that should never be auto-selected. Use task skills (`error-recovery-strategy`, `plan-stream-emit`). ## Process ### 1. Write the 11-field SkillMetadata Every skill should expose at minimum these fields: | Field | Type | Purpose | |---|---|---| | `name` | `String` (≤ 64 chars) | Canonical name, used in mentions and uniqueness checks. | | `description` | `String` (≤ 128 chars) | One-line purpose, used by LLM to decide "is this for me?". | | `short_description` | `Option<String>` | UI label, used in lists. | | `interface` | `Option<SkillInterface>` | UI metadata (`display_name`, `icon`, `brand_color`, `default_prompt`). | | `dependencies` | `Option<SkillDependencies>` | Declared external tools (MCP / function / etc). | | `policy` | `Option<SkillPolicy>` | `allow_implicit_invocation` (default `true`), `products`. | | `path_to_skills_md` | `AbsolutePathBuf` | Host-side canonical path. | | `scope` | `SkillScope` | Source: `User` / `System` / `Plugin` / etc. | | `plugin_id` | `Option<String>` | If from a marketplace plugin. | | `remote_plugin_id` | `Option<String>` | If remote. | | (system) | `enabled` | Computed from `disabled_paths`. | In your frontmatter, the **only fields that matter for LLM matching** are `name` and `description`. The other fields matter for the runtime. ### 2. Write a keyword-greppable description (v0.6.1 format) ```yaml description: | <one-sentence purpose>. USE WHEN: <comma-separated concrete signals and keywords>. TRIGGER PHRASES: <user-original-language phrases the user might say>. SKIP WHEN: <anti-patterns where this skill does not apply>. ``` Why: - The LLM matches on real signals (`ECONNREFUSED`, `permission denied`, `retries exceeded`, "上下文满了" / "出错了" / "重试"), not abstract prose. - `USE WHEN` and `TRIGGER PHRASES` are greppable substrings; `SKIP WHEN` reduces false positives. - Bilingual (English + Chinese) descriptions match user language directly. ### 3. Adopt three-layer matching When a user types `$skill-name` or `[$skill-name](path)`: ```text Layer 1 — canonical path: /path/to/skills/SKILL.md Layer 2 — discovery path: skill://skill-name/SKILL.md (logical) Layer 3 — plain name: skill-name (only if unambiguous) ``` Rules: - Layer 1 wins if path matches canonical. - Layer 2 wins if path matches discovery path AND Layer 1 missed. - Layer 3 wins ONLY if `skill_count == 1 && connector_count == 0` (uniqueness check via `name_counts`). - If a structured `UserInput::Skill` already matched some name, **block** that name from Layer 3 (`blocked_plain_names`). Complexity target: `O(T + (N_s + N_t) * S)` time, `O(S + M)` space (T = text length, S = skill count, M = mentions per input). With ~20 skills and 1KB text, this is sub-millisecond. ### 4. Provide explicit invocation syntax Two syntaxes, both supported: ```text $skill-name # plain [$skill-name](skill://path/SKILL.md) # linked ``` Exclude environment variables from being mistaken for skills (`is_common_env_var($HOME)` → true, skip). Support the 5 tool mention kinds with 4 path prefixes: ```text app://app-id/... mcp://server/tool plugin://plugin-id/... skill://skill-name/... SKILL.md (literal filename) ``` ### 5. Detect implicit invocation in shell commands Before doing the explicit three-layer match, also detect when a shell command references a skill script or document: ```rust detect_implicit_skill_invocation_for_command(outcome, command, workdir) ``` - Tokenize (Windows: PowerShell; Unix: shlex). - Look for `python` / `node` / `bash` / `sh` / `pwsh` invocations. - Look for `Read` operations on `scripts/` or `references/`. - Match by path (scripts dir → skill) and by doc (read path → skill). ### 6. Cache the loaded snapshot Use a `SkillRootSnapshotCache<Root>` trait so the loader can re-use a parsed snapshot: ```rust pub trait SkillRootSnapshotCache<Root>: Send + Sync { fn get(&self, root: &Root) -> Option<LoadedSkillRoot>; fn insert(&self, root: Root, snapshot: LoadedSkillRoot); } ``` `SkillRootSnapshots` is `Arc<dyn SkillRootSnapshotCache<Root>>` with identity-based `Hash` / `Eq` (uses `Arc::ptr_eq`). Cache key safety: clones share the same `Arc`, so identity equality holds. ### 7. Load with errors-as-data `LoadedSkillRoot { skills, errors: Vec<SkillError>, ... }` — never let one bad skill kill the whole root. Collect errors and surface them at the top. ## Output contract A skill that follows this design: - Has a 64-char-max `name` and a greppable 128-char-max `description`. - Supports both `$name` plain and `[$name](path)` linked mention. - Three-layer matching with uniqueness check on plain name. - Implicit invocation detection in shell commands. - Cached snapshot with identity-based hashing. - Errors collected per-skill, never aborting the whole root. ## Common pitfalls - **Plain name on a duplicate** → ambiguous; ignored. Always provide a path or qualify with the structured form. - **Description too abstract** → LLM cannot match. Use the 4-line `USE WHEN / TRIGGER PHRASES / SKIP WHEN` format with concrete keywords. - **Bypassing the uniqueness check** → two skills fire from one mention. Always require `skill_count == 1`. - **Forgetting `is_common_env_var`** → `$HOME` / `$PATH` become "skill mentions". Filter them. - **Loading all skills on every mention** → slow. Use `SkillRootSnapshotCache`. - **Frontmatter name > 64 chars** → rejected by parser. Count your characters. - **Skills with `description: ""` → MissingField error**. Description is mandatory. ## Example — minimal frontmatter ```yaml --- name: my-skill description: | Detect a specific failure mode in the running session and recover. USE WHEN: ECONNREFUSED, permission denied, retries exceeded, "can't connect" / "出错了" / "重试" / "权限". TRIGGER PHRASES: "recover", "retry failed", "switch tool", "ask me", "出错了", "重试". SKIP WHEN: short task, in middle of dictating. license: Apache-2.0 compatibility: Requires MiniMax Code with Agent Plugins 1.0 support. metadata: author: you version: "0.1.0" --- # My Skill ... the actual instructions ... ``` ## Verification checklist - [ ] Frontmatter has `name` (≤ 64) and `description` (≤ 128, ≥ 1, non-empty after `sanitize_single_line`). - [ ] Description uses the 4-line `USE WHEN / TRIGGER PHRASES / SKIP WHEN` format. - [ ] Description is bilingual if your users write in multiple languages. - [ ] Three-layer matching is implemented: canonical path → discovery path → unique plain name. - [ ] `name_counts` is built once per selection and consulted for uniqueness. - [ ] `is_common_env_var` filters out `$HOME` / `$PATH` etc. - [ ] Implicit invocation detection tokenizes per-platform (PowerShell vs shlex). - [ ] Snapshot cache is identity-based (`Arc::ptr_eq`). - [ ] Load errors are collected per-skill, never abort the root.