refactor(skills): strip implementation hints from crush-owned descriptions

Christian Rocha created 1 week ago

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.

Change summary

.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(-)

Detailed changes

.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

.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

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

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