mixdog 1.4.0 → 1.4.2

package/src/defaults/skills/skill-creator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-creator
-description: Create, audit, repair, or simplify a Mixdog Agent Skill and its SKILL.md.
+description: Create, audit, repair, or simplify your Mixdog skills and their SKILL.md.
 when_to_use: 'Create, audit, repair, or edit skills, including activation failures; not ordinary feature work.'
 dependencies:
   tools:
@@ -12,195 +12,90 @@ dependencies:
 
 # Skill Creator
 
-Build a compact operating guide that makes recurring agent work more reliable.
-The result should encode useful decisions and recovery behavior, not narrate
-everything a capable model or a tool schema already knows.
+Manages the skills a user keeps in Mixdog: turning a recurring workflow into a
+skill, repairing one that misfires, and keeping the whole set small and tidy.
+A skill earns its place by changing results — decisions, procedure, recovery
+and a way to prove completion — not by narrating what the model or a tool
+schema already knows.
 
-## Select the right deliverable
+## Pick the deliverable
 
-Before writing files, classify the request:
-
-| Need | Best home |
+| Need | Home |
 |---|---|
-| Reusable judgement or a repeatable procedure using existing tools | Skill |
-| Precise new runtime capability, authentication, streaming, or binary handling | Tool or product code |
-| Repository facts and contributor conventions | Project documentation |
-| A user-specific standing preference or constraint | Memory, with approval |
-| A single task unlikely to recur | Complete the task without a skill |
-
-Do not create a routing-only skill whose main job is listing other skills.
-Improve an existing owner when the requested capability already fits there.
-
-## Choose scope before content
-
-- **Machine-global** — personal workflows useful across Projects.
-- **Plugin** — capability that ships with an independently installed extension.
-- **Built-in** — broadly useful Mixdog behavior with low context and dependency
-  cost. Niche or heavy workflows do not belong here.
-
-Mixdog does not discover project-local `.mixdog/skills` directories. Read
-`references/design.md` before choosing placement or file structure.
-
-## Creation loop
-
-### 1. Recover the real workflow
-
-Use the conversation, successful tool calls, corrections, failure recovery, and
-produced artifacts as evidence. Ask only about gaps that would change the
-design.
-
-Capture:
-
-- one recurring outcome;
-- phrases and situations that should activate the skill;
-- nearby requests that another capability should own;
-- inputs, outputs, dependencies, side effects, and approvals;
-- completion evidence and important failure recovery.
-
-Completion criterion: another agent could identify when to use the skill and
-what successful completion looks like without guessing.
-
-### 2. Check local constraints
-
-Inspect the target skill when modifying one. For a new skill, inspect only the
-runtime rules and nearest comparable skills needed to settle naming, placement,
-and integration.
-
-Treat system instructions and current tool schemas as higher authority than any
-skill. A skill may explain selection and workflow but must not redefine tool
-arguments or permission boundaries.
-
-Completion criterion: every proposed dependency and path exists in the target
-environment or is explicitly part of the implementation.
-
-### 3. Review external candidates when useful
-
-Read `references/source-review.md` when the user asks to find, import, borrow
-from, or compare public skills.
-
-Extract requirements and design lessons rather than copying prose. If exact
-third-party content is genuinely needed, surface its license obligations before
-editing. Prefer a clean local implementation when a small compatible design can
-provide the same behavior.
-
-Completion criterion: the adopt, reimplement, or reject decision is supported
-by compatibility, maintenance, executable-content, and license evidence.
-
-### 4. Draft the smallest complete skill
-
-Read the "Listing line" section of `references/design.md` before writing
-frontmatter; it owns the `description` and `when_to_use` budgets and wording.
-Write instructions and listing text in English, describing user intent
-across languages rather than listing translated keywords. Preserve exact
-literals and language-specific examples when needed.
-
-Write the body in the section order from `references/design.md`: intro,
-boundary or mode selection, prerequisites, procedure with an observable result
-per important step, pitfalls, verification, resource links. Body text never
-routes the skill. Put capabilities, tool usage, prerequisites, operating rules,
-and recovery details here, not in the trigger or UI description. Keep only
-selection conditions in the trigger; the body must stand on its own when loaded.
-
-Move conditional detail into directly referenced files. Add scripts only for
-deterministic work that would otherwise be rebuilt on repeated invocations.
-
-Completion criterion: the listing line fits its budget with the trigger
-intact, and removing any remaining body section would lose judgement,
-execution, recovery, or verification value.
-
-### 5. Validate structure
-
-Run:
-
-```text
-node "${MIXDOG_SKILL_DIR}/scripts/validate-skill.mjs" "<skill-directory>"
-```
-
-Then run checks required by the target repository. The validator catches
-portable structure, code-fence, and path problems and warns when the listing line exceeds
-its budget; the runtime parser remains authoritative for loading behavior.
-
-Completion criterion: validation passes, warnings are reviewed at their
-reported severity, resources resolve, and the folder name matches the manifest.
-
-### 6. Exercise behavior
-
-Read `references/evaluation.md`. Test realistic requests, including an implicit
-positive case, an edge case, and a close negative case. For a modified skill,
-preserve the prior version before editing and compare the same scenarios.
-
-Judge generated artifacts by observable outcomes. Use deterministic assertions
-for mechanical properties and user review for subjective quality.
-
-Completion criterion: required scenarios pass without task-specific harness
-hints, and failures have either been fixed or clearly reported.
-
-### 7. Tighten
-
-Remove duplicated rules, generic advice, stale examples, and branches that did
-not affect evaluation. When adding a corrected rule, replace the obsolete rule
-instead of accumulating exceptions.
-
-Completion criterion: the final skill is smaller or clearer than the draft
-without losing proven behavior.
-
-## Updating an existing skill
-
-- Keep its name and scope unless the user requests a change.
-- Diagnose whether the defect is routing, instructions, resources, integration,
-  or the underlying tool before editing.
-- Preserve warnings, resource bounds, user approvals, and recovery paths.
-- Read only references implicated by the defect.
-- Re-run checks affected by the edit; do not repeat checks already closed by
-  unchanged evidence.
-
-## Auditing the skill set
-
-When asked to audit, review, or tidy skills rather than fix one defect:
-
-1. List every skill directory in scope: machine-global
-   (`<mixdog-data>/skills`), enabled plugin skills, and built-ins
-   (`src/defaults/skills` in the Mixdog repository).
-2. Run `scripts/validate-skill.mjs` on each directory and collect the errors
-   and warnings; they cover the listing line, code fences, and resource paths
-   mechanically.
-3. Read each trigger and body against the audit checklist in
-   `references/design.md`: trigger content, section order, completion
-   results, duplication, and stale instructions.
-4. Report findings as one table (skill, check, current value, proposed fix)
-   before editing. Edit only after the user approves the scope.
-5. Re-run the validator on every edited directory.
-
-Completion criterion: every skill in scope validates; report unresolved
-findings with reasons, without promoting warnings to failures.
-
-## Mixdog loading facts
-
-- Discovery precedence is machine-global, enabled plugin, then built-in.
-- The directory name must equal frontmatter `name`.
-- The model sees one listing line per skill (`references/design.md`
-  "Listing line" owns its form and budget); UI descriptions are not
-  injected, and the body loads once through `Skill`.
-- `${MIXDOG_SKILL_DIR}` resolves to the active skill directory.
-- `metadata.requires` names a mandatory Mixdog built-in feature. Add it only
-  when the skill cannot function without that feature.
-- Optional frontmatter has no effect unless the current runtime implements it.
-- `dependencies.tools` declares tools loaded with the skill, without granting
-  permissions. Use `type: tool` with the exact tool name or `type: mcp` with
-  an existing server name. Keep optional tools out; `allowed-tools` is not
-  interpreted as dependencies. Imported `agents/openai.yaml` dependencies
-  are also read, but never authorize installation or activation.
-
-## Final review
-
-- Is this genuinely a reusable skill rather than another deliverable?
-- Does the trigger say only when to load the skill, strongest situation first?
-- Does every major step end in evidence, not “be careful”?
-- Are platform assumptions, external programs, network access, and secrets
-  visible?
-- Are pitfalls based on plausible or observed failures?
-- Can subjective outputs reach the user for review?
-- Are temporary evaluation files excluded from the shipped skill?
-- Were commit, publish, install, deployment, and restart left to explicit user
-  requests?
-
+| Reusable judgement or a repeatable procedure with existing tools | Skill |
+| A new runtime capability, authentication, streaming, binary handling | Tool or product code |
+| Facts and conventions of one repository | That repository's docs |
+| A standing personal preference or constraint | Memory, with approval |
+| A one-off task | Do the task; no skill |
+
+Never create a skill whose job is to list other skills. When an existing skill
+already owns the outcome, extend it instead.
+
+## Where skills live
+
+- The user's skills: `<mixdog-data>/skills/<name>/SKILL.md`, available in
+  every project.
+- Enabled plugins and Mixdog's built-ins are read in place. A user skill with
+  the same name replaces them and stops following their updates, so pick a new
+  name unless replacing is the point.
+- The folder name equals the frontmatter `name`.
+
+## Create a skill
+
+1. **Recover the workflow.** From the conversation, successful tool calls,
+   corrections and produced artifacts, capture the one recurring outcome; the
+   requests that should select the skill and the nearby requests another skill
+   or tool owns; inputs, side effects and approvals; completion evidence and
+   recovery. Ask only about gaps that change the design. Result: another agent
+   could tell when to use it and what done looks like.
+2. **Draft** with `references/design.md`: the listing line first, then the
+   body in its section order; detail that loads only in some cases goes to
+   `references/`, deterministic repeated work to `scripts/`. Every tool, path
+   and dependency it names exists. Result: the trigger fits its budget, and
+   removing any section would lose judgement, execution, recovery or
+   verification.
+3. **Validate:**
+   `node "${MIXDOG_SKILL_DIR}/scripts/validate-skill.mjs" "<skill-directory>"`.
+   Result: no errors; each warning fixed or kept on purpose.
+4. **Exercise** with `references/evaluation.md`: realistic requests, including
+   an implicit positive and a near-miss negative. Result: the scenarios pass
+   without hints, or the failures are reported.
+5. **Tighten:** delete duplicated rules, generic advice, stale examples and
+   rules no scenario needed; replace an obsolete rule instead of adding an
+   exception. Result: smaller or clearer, with the same proven behaviour.
+
+## Repair or update a skill
+
+- Keep its name and scope unless the user asks otherwise.
+- Classify the defect first (`references/evaluation.md`) and edit the part
+  that owns it: a trigger that never selects the skill is not fixed in the
+  body, and more prose does not fix a broken tool.
+- Keep a copy of the prior version and rerun the same scenarios against both.
+- Keep its approvals, bounds, warnings and recovery paths.
+- Rerun only the checks the edit affects.
+
+## Audit the set
+
+When asked to review or tidy skills rather than fix one:
+
+1. List the skills in scope: the user's (`<mixdog-data>/skills`), enabled
+   plugins, built-ins.
+2. Run the validator on each and collect its errors and warnings.
+3. Read each against the audit checklist in `references/design.md` and give a
+   verdict: **Keep**; **Improve** (name the defect); **Merge** into another
+   (name it); **Retire** (name what covers the need instead).
+4. Report one table — skill, verdict, finding, proposed fix — and edit only
+   what the user approves. Plugin and built-in skills are never edited in
+   place.
+5. Rerun the validator on every edited skill.
+
+Result: every edited skill validates; unresolved findings are reported with
+their reason.
+
+## Resources
+
+- `references/design.md` — read before drafting or auditing: ownership,
+  frontmatter, listing line, body, resources, audit checklist.
+- `references/evaluation.md` — read when exercising a skill or diagnosing a
+  failure.
+- `scripts/validate-skill.mjs` — run on every created or edited skill.

package/src/defaults/skills/skill-creator/references/design.md

@@ -1,203 +1,111 @@
 # Skill design
 
-Use this reference after deciding that the requested outcome belongs in a
-skill.
+## One owner
 
-## Start from behavior
+Before writing, name the result the skill makes more reliable, the decisions
+the agent misses without it, the evidence that proves completion, the failures
+that need recovery, and the nearby request it must leave alone.
 
-Define the behavior before naming files:
+Extend an existing skill that owns the outcome; create a new one only for a
+distinct trigger, workflow and verification. Avoid skills that redirect to
+other skills, several skills competing for one request, one skill covering a
+whole technology, and product features written as prose.
 
-- What recurring result should become more reliable?
-- Which decisions does the agent currently miss?
-- What evidence proves completion?
-- Which failures need recovery rather than a hard stop?
-- Which adjacent task must remain outside this skill?
-
-A skill earns its context cost by supplying judgement or procedure that changes
-results. Generic encouragement and tool documentation do not qualify.
-
-## Pick one owner
-
-Prefer extending an existing skill when it already owns the outcome. Create a
-new skill when it has a distinct trigger, workflow, and verification boundary.
-
-Avoid:
-
-- umbrella skills that merely redirect to narrower skills;
-- several skills competing for the same user intent;
-- one skill that attempts to cover an entire profession or technology family;
-- product features represented as prose because implementing code is harder.
-
-## Choose where it lives
-
-| Scope | Use when |
-|---|---|
-| Machine-global | The user wants the workflow available across Projects |
-| Plugin | The workflow depends on and ships with an extension |
-| Built-in | The workflow is broadly useful, stable, and inexpensive to expose |
-
-A workflow specific to one repository may be better owned by project
-documentation than by a machine-global skill.
+System instructions and tool schemas outrank a skill: it explains when and how
+to use tools, never redefines their arguments or permissions.
 
 ## Frontmatter
 
-Required:
+- `name`: lowercase letters, digits and hyphens, no leading, trailing or
+  repeated hyphen, at most 64 characters, equal to the folder name.
+- `description`: one plain capability sentence for the UI, at most 100
+  characters. The model never sees it.
+- `when_to_use`: the trigger (Listing line below).
+- `dependencies.tools`: tools loaded with the skill. `type: tool` takes an
+  exact tool name, `type: mcp` a connected server's name. A missing or
+  disabled tool is reported, never installed or enabled, and nothing grants
+  permissions. Leave optional tools out.
 
-- `name`: lowercase letters, digits, and hyphens; no edge or repeated hyphen;
-  at most 64 characters; identical to the parent directory.
-- `description`: one sentence naming the capability.
+  ```yaml
+  dependencies:
+    tools:
+      - type: tool
+        value: office
+  ```
 
-Recommended:
+- `metadata.requires`: a Mixdog built-in feature the skill cannot work without.
 
-- `when_to_use`: the trigger line — phrases and situations that should select
-  the skill, then the boundary against the nearest neighbour.
-
-Optional portable fields include `license`, `compatibility`, `metadata`, and
-`allowed-tools`. A parsed field is not automatically an implemented feature.
-Confirm runtime support before assigning it operational meaning.
-
-Declare mandatory tools in `dependencies.tools`, either in `SKILL.md`
-frontmatter or an imported `agents/openai.yaml`:
-
-```yaml
-dependencies:
-  tools:
-    - type: tool
-      value: office
-    - type: mcp
-      value: existing-server
-```
-
-`mcp` resolves the available tools of an already connected server. Missing,
-disabled, and policy-blocked tools are reported, never installed or enabled.
-
-The skill editor keeps tool-link overrides in Mixdog's data directory so
-updating a downloaded skill does not erase local links or rewrite its source.
-An empty override disconnects all tools; restoring the declaration removes
-the override. Changing the instruction text still requires an editable skill.
+Other fields have no effect in Mixdog.
 
 ## Listing line
 
-The model never sees the body until it calls `Skill()`. Selection happens on
-one listing line per skill:
+The model sees one line per skill and loads the body only by calling `Skill`:
 
 ```text
 - <name>: <when_to_use> [tools: <linked tool names>]
 ```
 
-The runtime cuts the trigger at 100 characters on a word boundary, and when
-many skills share the listing budget it shrinks every trigger evenly toward
-60; text past the cut never routes the skill. The tool suffix comes from effective dependencies, not
-handwritten trigger text; `mcp:<server>` denotes a server's tools. Keep these
-three responsibilities separate:
-
-| Field | Job | Budget | Write | Avoid |
-|---|---|---|---|---|
-| `description` | UI-only summary | ≤ 100 chars | One plain capability sentence | Operating rules or selection conditions found nowhere else |
-| `when_to_use` | When to load the skill | ≤ 100 chars, core in the first 60 | English descriptions of user intents across languages, implicit situations, then `not …` naming the neighbouring owner | How to use it — procedures, rules, constraints, commands, tool arguments; translated keyword lists |
-| Body | Loaded operating instructions | As needed | Capability, prerequisites, procedure, constraints, recovery, and verification | Depending on UI copy to supply an instruction |
+The trigger is cut at 100 characters on a word boundary, and shrinks evenly
+toward 60 when many skills share the listing; text past the cut never selects
+the skill. The tool suffix comes from `dependencies`, never from the trigger.
 
-Put the strongest trigger first in `when_to_use`. A boundary is worth writing
-only when a neighbouring skill or plain tool could plausibly win the request.
+| Field | Job | Write | Avoid |
+|---|---|---|---|
+| `when_to_use` | When to load the skill; core in the first 60 characters | The user intents and situations, strongest first, in English for every language, then `not …` naming the nearest other owner | How to do it: steps, rules, commands, tool arguments; translated keyword lists |
+| Body | Everything after selection | Capability, prerequisites, procedure, recovery, verification | Relying on the trigger or the UI description for an instruction |
 
-Example:
+Never summarise the procedure in the trigger: a model that reads a workflow
+there may follow it instead of loading the body. Add the `not …` boundary only
+when a nearby skill or a plain tool could plausibly win the request.
 
 ```yaml
-description: Deploy Mixdog to the installed app, VPS, or a live release.
-when_to_use: 'Deploy, redeploy, or update the installed app, VPS, or a live release; not builds or tests alone.'
+when_to_use: 'Deploy or update the installed app or a live release; not builds or tests alone.'
 ```
 
 ## Body
 
-The body loads once, after selection, so it owns everything the listing line
-left out. Use only the sections the workflow needs, in this order:
+Only the sections the workflow needs, in this order:
 
-1. **Intro** — two or three sentences: what the skill produces, what it does
-   not do, and the key dependency stance.
+1. **Intro** — two or three sentences: what it produces and what it does not.
 2. **Boundary or mode selection** — the decision that picks a path or hands
    the request to another owner.
-3. **Prerequisites** — exact tools, features, environment, and approvals.
+3. **Prerequisites** — exact tools, environment and approvals.
 4. **Procedure** — numbered steps; each important step ends with the
-   observable result that proves it is done, and an irreversible step names
-   the user checkpoint before it.
+   observable result that proves it, and an irreversible step names the user
+   checkpoint before it.
 5. **Pitfalls** — observed failures and their recovery, not generic caution.
 6. **Verification** — the check that proves the outcome.
-7. **Resource links** — each `references/` or `scripts/` file with the
-   condition for reading or running it.
+7. **Resource links** — each file with the condition for reading or running it.
 
-Write in the imperative. Explain why a rule exists when the reason changes
-behaviour; drop rules the model already follows without being told.
+Write in the imperative; give a reason only when it changes behaviour, and drop
+rules the model already follows. About 100 lines for a simple workflow, about
+200 for a complex one, never over 500. Split by loading condition, not by
+length.
 
-Size: about 100 lines for a simple workflow, about 200 for a complex one, and
-below 500 in every case. Split content because it has a different loading
-condition, not simply because the file became long.
+## Resources
 
-## Bundled resources
-
-### References
-
-Put detailed rules or domain material in `references/`. Link each file directly
-from `SKILL.md` and state the condition for reading it. Do not create chains in
-which one reference points the agent to another.
-
-### Scripts
-
-Use `scripts/` for deterministic repeated work. Every executable should:
-
-- validate inputs before side effects;
-- operate on explicit paths;
-- bound time, memory, retries, and output;
-- return actionable errors and a non-zero failure status;
-- avoid hidden network, installation, deletion, or credential behavior;
-- work on every claimed platform or declare the limitation;
-- have a behavioral test separate from the prose.
-
-Reference executable paths through `${MIXDOG_SKILL_DIR}` so installation
-location does not matter.
-
-### Assets
-
-Use `assets/` for templates and static material consumed by outputs. Guidance
-belongs in Markdown, not in files that the agent will not load as instructions.
-
-## Portability audit
-
-Inspect prose and scripts for:
-
-- POSIX-only commands or paths on Windows;
-- Windows-only shell syntax on other platforms;
-- machine-specific absolute paths;
-- undeclared external programs and environment variables;
-- assumptions about a vendor CLI, model, or authentication state;
-- output paths that overwrite user files by default.
-
-Prefer portable implementation first. Restrict compatibility only when the
-dependency cannot reasonably be removed.
-
-## Editing discipline
-
-- Preserve identity and public behavior unless change is requested.
-- Replace outdated guidance instead of appending exceptions.
-- Keep safety and recovery behavior during simplification.
-- Do not duplicate a rule across the body, reference, script help, and tool
-  schema; choose the component that owns it.
-- End with a pass that removes instructions that did not influence outcomes.
+- `references/` — detailed rules read only in some cases. Link each directly
+  from `SKILL.md` with its read condition; no file points to another.
+- `scripts/` — deterministic work that would otherwise be redone each time.
+  Validate inputs before side effects, use explicit paths, bound time, output
+  and retries, fail with an actionable message and a non-zero status, and do
+  no hidden network, installs, deletion or credential access. Give it a
+  behavioural test, and call it through `${MIXDOG_SKILL_DIR}`.
+- `assets/` — templates and static material the output uses; guidance stays
+  in Markdown.
 
 ## Audit checklist
 
-Apply to every skill when asked to audit, review, or tidy the skill set.
-
 | Check | Failure looks like | Fix |
 |---|---|---|
-| Field separation | UI `description` over 100 chars, `when_to_use` over 100, or operating details present only in metadata | Keep the UI summary short, selection conditions in the trigger, and all execution details in the body |
-| Trigger presence | `when_to_use` empty while a neighbour competes | Add the phrases users actually write and the `not …` boundary |
-| Trigger content | `when_to_use` says how rather than when: rules, constraints, commands, tool names or arguments | Move them to the body; keep the request situations and the `not …` boundary |
-| Body order | Sections out of the order above, a `When to use` section in the body, steps without a completion result | Reorder; delete body triggers (they never route); add the observable result |
-| Resources | A referenced file missing, a chain of references, a script without an input check | Fix the path, flatten the chain, add validation |
-| Duplication | The same rule in the body, a reference, and a script help text | Keep it in the owner; delete the copies |
-| Staleness | Paths, tools, or flags that no longer exist | Replace or remove; never leave an instruction that cannot succeed |
-
-Run `scripts/validate-skill.mjs` on each directory; it reports the listing-line,
-code-fence, and resource checks mechanically, and the rest is a read of the body against
-this reference.
-
+| Fields | `description` or `when_to_use` over 100 characters; an instruction found only in metadata | Short UI summary, selection in the trigger, execution in the body |
+| Trigger | Empty while a neighbour competes; says how instead of when | The phrases users write plus the `not …` boundary; move the how to the body |
+| Body | Out of order, a "when to use" section, steps without a result | Reorder, delete body triggers, add the observable result |
+| Resources | A missing file, a chain of references, a script without input checks | Fix the path, flatten, validate inputs |
+| Side effects | External programs, network, secrets or irreversible steps (commit, deploy, publish, restart) not visible or not waiting for the user | Name them in prerequisites; checkpoint before the step |
+| Duplication | One rule in the body, a reference and a script's help | Keep it in its owner, delete the copies |
+| Staleness | Paths, tools or flags that no longer exist | Replace or remove |
+| Value | A rule or section that no scenario needed | Delete it |
+
+The validator checks fields, fences and resource paths; the rest is a read
+against this table.