From 0a86d5f781eaa4b251724872a46a4bd15d97cc7d Mon Sep 17 00:00:00 2001 From: Christian Rocha Date: Sun, 19 Apr 2026 15:11:20 -0400 Subject: [PATCH] refactor(skills): strip implementation hints from crush-owned descriptions Descriptions should describe when a skill applies, not how it does its job. Leaving language like "using go doc", "the jq command-line processor", etc. in the trigger encourages the model to guess its way through without reading SKILL.md. --- .agents/skills/builtin-skills/SKILL.md | 2 +- .agents/skills/shell-builtins/SKILL.md | 2 +- internal/skills/builtin/crush-config/SKILL.md | 2 +- internal/skills/builtin/jq/SKILL.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.agents/skills/builtin-skills/SKILL.md b/.agents/skills/builtin-skills/SKILL.md index 991f61866b64ce19133765908aed813cf51ad9c8..4672e499805e431ac8ef9024eaced3f90a057a9a 100644 --- a/.agents/skills/builtin-skills/SKILL.md +++ b/.agents/skills/builtin-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: builtin-skills -description: Guide for adding and modifying builtin skills embedded in the Crush binary. Use when creating a new builtin skill, editing an existing one, or understanding how the embedded skill system works (internal/skills/builtin/). +description: Use when creating a new builtin skill for Crush, editing an existing builtin skill (internal/skills/builtin/), or when the user needs to understand how the embedded skill system works. --- # Builtin Skills diff --git a/.agents/skills/shell-builtins/SKILL.md b/.agents/skills/shell-builtins/SKILL.md index 4ba4c4a2e35e3a7f5321c51ea9a35f5383cbabef..a9914a08aa1b506006fcb7ef35ded092efc7f895 100644 --- a/.agents/skills/shell-builtins/SKILL.md +++ b/.agents/skills/shell-builtins/SKILL.md @@ -1,6 +1,6 @@ --- name: shell-builtins -description: Guide for adding and modifying shell builtin commands in Crush's embedded shell (internal/shell/). Use when creating a new builtin command, editing an existing one, or understanding how commands are intercepted in the mvdan/sh interpreter. +description: Use when creating a new shell builtin command for Crush (internal/shell/), editing an existing one, or when the user needs to understand how commands are intercepted in Crush's embedded shell. --- # Shell Builtins diff --git a/internal/skills/builtin/crush-config/SKILL.md b/internal/skills/builtin/crush-config/SKILL.md index 9520647b7a4669319041a7e9bfb716a2104b714d..e71fbaf4dd10062fb096d93f840c5bbae55bf929 100644 --- a/internal/skills/builtin/crush-config/SKILL.md +++ b/internal/skills/builtin/crush-config/SKILL.md @@ -1,6 +1,6 @@ --- name: crush-config -description: Configure Crush settings including providers, LSPs, MCPs, skills, permissions, and behavior options. Use when the user needs help with crush.json configuration, setting up providers, configuring LSPs, adding MCP servers, or changing Crush behavior. +description: Use when the user needs help configuring Crush — working with crush.json, setting up providers, configuring LSPs, adding MCP servers, managing skills or permissions, or changing Crush behavior. --- # Crush Configuration diff --git a/internal/skills/builtin/jq/SKILL.md b/internal/skills/builtin/jq/SKILL.md index 11f5a03957a9be07adaa9702d57e92b3fb2bfb19..6d7be404fe4455586dad14ee13221b5422b588b8 100644 --- a/internal/skills/builtin/jq/SKILL.md +++ b/internal/skills/builtin/jq/SKILL.md @@ -1,6 +1,6 @@ --- name: jq -description: Process, filter, transform, generate, and construct JSON data using the jq command-line processor. Crush includes a built-in jq implementation (powered by gojq) available in the bash tool. Use when the user needs to query, filter, reshape, extract, create, or construct JSON — including API responses, config files, log output, or any structured data. Also use when generating JSON from scratch with jq -n, or when helping users write or debug jq expressions. +description: Use when the user needs to query, filter, reshape, extract, create, or construct JSON data — including API responses, config files, log output, or any structured data — or when helping the user write or debug JSON transformations. --- # jq — Built-in JSON Processor