From 18b6438e3284d2e58c1ecb7174527cdbe1a7cf6f Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Wed, 25 Feb 2026 14:42:23 +0100 Subject: [PATCH] refactor: trim SKILL.md to <500 words, move detail to references Move detailed sections to reference files for on-demand loading: - Troubleshooting (PATH issues, installation blocked) to references/troubleshooting.md - Missing tool resolution phases to references/resolution-workflow.md - Hyperfine detail already covered in references/preferred-tools.md SKILL.md reduced from 910 to 480 words. Signed-off-by: Sebastian Mendel --- skills/cli-tools/SKILL.md | 188 ++++-------------- .../references/resolution-workflow.md | 49 +++++ .../cli-tools/references/troubleshooting.md | 61 ++++++ 3 files changed, 144 insertions(+), 154 deletions(-) create mode 100644 skills/cli-tools/references/resolution-workflow.md create mode 100644 skills/cli-tools/references/troubleshooting.md diff --git a/skills/cli-tools/SKILL.md b/skills/cli-tools/SKILL.md index 5df8160..4ab87a0 100644 --- a/skills/cli-tools/SKILL.md +++ b/skills/cli-tools/SKILL.md @@ -7,6 +7,15 @@ description: "Use when commands fail with 'command not found', when installing m Manage CLI tool installation, environment auditing, and updates. +## Triggers + +**Reactive** (auto-install): +``` +bash: : command not found +``` + +**Proactive** (audit): "check environment", "what's missing", "update tools" + ## Capabilities 1. **Reactive**: Auto-install missing tools on "command not found" @@ -19,101 +28,30 @@ When multiple tools can accomplish the same task, prefer the modern alternative | Instead of... | Use... | Why | Skill | |--------------|--------|-----|-------| -| `grep` on code | `rg` (ripgrep) | 10x faster, respects .gitignore, better regex | file-search | -| `find` | `fd` | 5x faster, simpler syntax, respects .gitignore | file-search | -| `grep` on PDFs/docs | `rga` (ripgrep-all) | Searches inside PDFs, Office, archives, SQLite | file-search | -| `cloc` / `wc -l` | `tokei` or `scc` | 10-100x faster, accurate language detection | file-search | -| `grep`/`awk` on JSON | `jq` | Structured extraction, handles nesting/escaping | data-tools | -| `sed`/`awk` on YAML | `yq` | Syntax-aware, preserves comments and formatting | data-tools | -| `sed` on JSON | `jq` or `dasel` | Correct escaping, handles nested paths | data-tools | -| `awk`/Python on CSV | `qsv` | Handles quoting, headers, 100x faster on large files | data-tools | -| `sed` on TOML/XML | `dasel` | Universal format support, in-place editing | data-tools | -| `diff` on code | `difft` (difftastic) | Syntax-aware, ignores formatting-only changes | git-workflow | -| `git commit --fixup` | `git absorb` | Auto-detects correct parent commit | git-workflow | -| Manual security grep | `semgrep --config auto` | Pre-built OWASP/CWE rulesets, AST-aware | security-audit | -| `time` for benchmarks | `hyperfine` | Statistical analysis, warmup runs, comparison | (this skill) | -| `cat` for viewing | `bat` | Syntax highlighting, line numbers, git integration | - | - -### hyperfine - Command Benchmarking - -Statistical benchmarking tool. Use instead of ad-hoc `time` measurements. - -```bash -# Benchmark a command (10 runs with warmup) -hyperfine 'fd -e py' - -# Compare two commands -hyperfine 'find . -name "*.py"' 'fd -e py' - -# With warmup and minimum runs -hyperfine --warmup 3 --min-runs 20 'rg pattern' - -# Export results -hyperfine --export-markdown bench.md 'command1' 'command2' -``` - -**When to use:** When optimizing commands, comparing tool performance, or proving one approach is faster than another. Provides mean, stddev, min, max, and comparison percentages. - -## Triggers - -**Reactive** (auto-install): -``` -bash: : command not found -``` - -**Proactive** (audit): "check environment", "what's missing", "update tools" +| `grep` on code | `rg` (ripgrep) | 10x faster, respects .gitignore | file-search | +| `find` | `fd` | 5x faster, simpler syntax | file-search | +| `grep` on PDFs/docs | `rga` (ripgrep-all) | Searches inside PDFs, archives | file-search | +| `cloc` / `wc -l` | `tokei` or `scc` | 10-100x faster, accurate | file-search | +| `grep`/`awk` on JSON | `jq` | Structured extraction | data-tools | +| `sed`/`awk` on YAML | `yq` | Syntax-aware, preserves comments | data-tools | +| `sed` on JSON | `jq` or `dasel` | Correct escaping | data-tools | +| `awk`/Python on CSV | `qsv` | Handles quoting, 100x faster | data-tools | +| `sed` on TOML/XML | `dasel` | Universal format support | data-tools | +| `diff` on code | `difft` (difftastic) | Syntax-aware diffs | git-workflow | +| `git commit --fixup` | `git absorb` | Auto-detects parent commit | git-workflow | +| Manual security grep | `semgrep --config auto` | AST-aware, OWASP rulesets | security-audit | +| `time` for benchmarks | `hyperfine` | Statistical analysis, comparison | (this skill) | +| `cat` for viewing | `bat` | Syntax highlighting, git integration | - | ## Workflows ### Missing Tool Resolution -#### Phase 1: Diagnostic (BEFORE attempting install) - -1. **Check if tool exists elsewhere:** - ```bash - which # Is it installed but not in PATH? - command -v # Alternative check - type -a # Show all locations - ``` - -2. **Why might it be missing?** - - **PATH issue**: Tool installed but shell can't find it (check `~/.local/bin`, `/usr/local/bin`) - - **Version conflict**: Multiple versions installed, wrong one active - - **Shell state**: Installed in current session but shell hash table stale (`hash -r`) - - **Package manager isolation**: Installed via pip/npm/cargo but not in global PATH +1. Diagnose: check if tool exists elsewhere (`which`, `command -v`, `type -a`) +2. Install: lookup in `references/binary_to_tool_map.md`, run `scripts/install_tool.sh install` +3. Verify: confirm with `which ` and ` --version`, retry original command -3. **If tool exists but not in PATH:** - ```bash - # Find the binary - find /usr -name "" 2>/dev/null - find ~/.local -name "" 2>/dev/null - - # Add to PATH temporarily - export PATH="$PATH:/path/to/tool/directory" - ``` - -#### Phase 2: Installation - -1. Extract tool name from error -2. Lookup in `references/binary_to_tool_map.md` (e.g., `rg` → `ripgrep`) -3. Install: `scripts/install_tool.sh install` - -#### Phase 3: Verification (AFTER install) - -1. **Confirm installation succeeded:** - ```bash - which # Should show path - --version # Should show version - ``` - -2. **If "command not found" persists after install:** - ```bash - hash -r # Clear shell's command hash - source ~/.bashrc # Reload shell configuration - # Or start a new shell session - ``` - -3. **Retry original command** +See `references/resolution-workflow.md` for detailed diagnostic and verification steps. ### Environment Audit @@ -134,73 +72,15 @@ scripts/check_environment.sh audit . Core CLI, Languages, Package Managers, DevOps, Linters, Security, Git Tools -## Troubleshooting - -### PATH Issues - -When a tool installs but still shows "command not found": - -1. **Check where it was installed:** - ```bash - # Common install locations - ls -la ~/.local/bin/ - ls -la ~/.cargo/bin/ - ls -la ~/.npm-global/bin/ - ls -la /usr/local/bin/ - ``` - -2. **Ensure PATH includes common directories:** - ```bash - # Add to ~/.bashrc or ~/.zshrc - export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH" - ``` - -3. **Reload shell configuration:** - ```bash - source ~/.bashrc # or ~/.zshrc - hash -r # Clear command cache - exec $SHELL # Restart shell - ``` - -### Installation Blocked (Permission/System Restrictions) - -When system prevents normal installation, use these alternatives: - -1. **Docker (no install required):** - ```bash - # Run tool in container - docker run --rm -v "$PWD:/work" -w /work - - # Create alias for convenience - alias ='docker run --rm -v "$PWD:/work" -w /work ' - ``` - -2. **Manual binary download:** - ```bash - # Download release binary directly - curl -L -o ~/.local/bin/ - chmod +x ~/.local/bin/ - ``` - -3. **Compile from source:** - ```bash - git clone - cd - make && make install PREFIX=~/.local - ``` - -4. **Use package manager with user scope:** - ```bash - pip install --user - npm install -g --prefix ~/.npm-global - cargo install # Installs to ~/.cargo/bin - ``` - ## References -- `references/binary_to_tool_map.md` - Binary to catalog mapping -- `references/project_type_requirements.md` - Project type requirements -- `references/preferred-tools.md` - Detailed comparison and usage patterns for preferred tools +| Reference | Use when... | +|-----------|-------------| +| `references/binary_to_tool_map.md` | Mapping binary names to catalog entries | +| `references/project_type_requirements.md` | Checking what tools a project type needs | +| `references/preferred-tools.md` | Detailed usage patterns and examples for preferred tools | +| `references/resolution-workflow.md` | Full diagnostic/install/verify workflow for missing tools | +| `references/troubleshooting.md` | PATH issues, permission problems, installation blocked | --- diff --git a/skills/cli-tools/references/resolution-workflow.md b/skills/cli-tools/references/resolution-workflow.md new file mode 100644 index 0000000..4c19920 --- /dev/null +++ b/skills/cli-tools/references/resolution-workflow.md @@ -0,0 +1,49 @@ +# Missing Tool Resolution Workflow + +## Phase 1: Diagnostic (BEFORE attempting install) + +1. **Check if tool exists elsewhere:** + ```bash + which # Is it installed but not in PATH? + command -v # Alternative check + type -a # Show all locations + ``` + +2. **Why might it be missing?** + - **PATH issue**: Tool installed but shell can't find it (check `~/.local/bin`, `/usr/local/bin`) + - **Version conflict**: Multiple versions installed, wrong one active + - **Shell state**: Installed in current session but shell hash table stale (`hash -r`) + - **Package manager isolation**: Installed via pip/npm/cargo but not in global PATH + +3. **If tool exists but not in PATH:** + ```bash + # Find the binary + find /usr -name "" 2>/dev/null + find ~/.local -name "" 2>/dev/null + + # Add to PATH temporarily + export PATH="$PATH:/path/to/tool/directory" + ``` + +## Phase 2: Installation + +1. Extract tool name from error +2. Lookup in `binary_to_tool_map.md` (e.g., `rg` -> `ripgrep`) +3. Install: `scripts/install_tool.sh install` + +## Phase 3: Verification (AFTER install) + +1. **Confirm installation succeeded:** + ```bash + which # Should show path + --version # Should show version + ``` + +2. **If "command not found" persists after install:** + ```bash + hash -r # Clear shell's command hash + source ~/.bashrc # Reload shell configuration + # Or start a new shell session + ``` + +3. **Retry original command** diff --git a/skills/cli-tools/references/troubleshooting.md b/skills/cli-tools/references/troubleshooting.md new file mode 100644 index 0000000..576e498 --- /dev/null +++ b/skills/cli-tools/references/troubleshooting.md @@ -0,0 +1,61 @@ +# Troubleshooting + +## PATH Issues + +When a tool installs but still shows "command not found": + +1. **Check where it was installed:** + ```bash + # Common install locations + ls -la ~/.local/bin/ + ls -la ~/.cargo/bin/ + ls -la ~/.npm-global/bin/ + ls -la /usr/local/bin/ + ``` + +2. **Ensure PATH includes common directories:** + ```bash + # Add to ~/.bashrc or ~/.zshrc + export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH" + ``` + +3. **Reload shell configuration:** + ```bash + source ~/.bashrc # or ~/.zshrc + hash -r # Clear command cache + exec $SHELL # Restart shell + ``` + +## Installation Blocked (Permission/System Restrictions) + +When system prevents normal installation, use these alternatives: + +1. **Docker (no install required):** + ```bash + # Run tool in container + docker run --rm -v "$PWD:/work" -w /work + + # Create alias for convenience + alias ='docker run --rm -v "$PWD:/work" -w /work ' + ``` + +2. **Manual binary download:** + ```bash + # Download release binary directly + curl -L -o ~/.local/bin/ + chmod +x ~/.local/bin/ + ``` + +3. **Compile from source:** + ```bash + git clone + cd + make && make install PREFIX=~/.local + ``` + +4. **Use package manager with user scope:** + ```bash + pip install --user + npm install -g --prefix ~/.npm-global + cargo install # Installs to ~/.cargo/bin + ```