Skip to content

refactor: trim SKILL.md for token efficiency #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
CybotTM merged 1 commit into from
Feb 25, 2026
Merged

refactor: trim SKILL.md for token efficiency #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
188 changes: 34 additions & 154 deletions skills/cli-tools/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: <tool>: command not found
```

**Proactive** (audit): "check environment", "what's missing", "update tools"

## Capabilities

1. **Reactive**: Auto-install missing tools on "command not found"
Expand All @@ -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: <tool>: 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 <tool> # Is it installed but not in PATH?
command -v <tool> # Alternative check
type -a <tool> # 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 <tool> install`
3. Verify: confirm with `which <tool>` and `<tool> --version`, retry original command

3. **If tool exists but not in PATH:**
```bash
# Find the binary
find /usr -name "<tool>" 2>/dev/null
find ~/.local -name "<tool>" 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 <tool> install`

#### Phase 3: Verification (AFTER install)

1. **Confirm installation succeeded:**
```bash
which <tool> # Should show path
<tool> --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

Expand All @@ -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/<tool>
ls -la ~/.cargo/bin/<tool>
ls -la ~/.npm-global/bin/<tool>
ls -la /usr/local/bin/<tool>
```

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 <tool-image> <tool> <args>

# Create alias for convenience
alias <tool>='docker run --rm -v "$PWD:/work" -w /work <tool-image> <tool>'
```

2. **Manual binary download:**
```bash
# Download release binary directly
curl -L <release-url> -o ~/.local/bin/<tool>
chmod +x ~/.local/bin/<tool>
```

3. **Compile from source:**
```bash
git clone <repo-url>
cd <repo>
make && make install PREFIX=~/.local
```

4. **Use package manager with user scope:**
```bash
pip install --user <tool>
npm install -g <tool> --prefix ~/.npm-global
cargo install <tool> # 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 |

---

Expand Down
49 changes: 49 additions & 0 deletions skills/cli-tools/references/resolution-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Missing Tool Resolution Workflow

## Phase 1: Diagnostic (BEFORE attempting install)

1. **Check if tool exists elsewhere:**
```bash
which <tool> # Is it installed but not in PATH?
command -v <tool> # Alternative check
type -a <tool> # 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 "<tool>" 2>/dev/null
find ~/.local -name "<tool>" 2>/dev/null
Comment on lines +20 to +22
Copy link

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Running find /usr -name "<tool>" can be very slow on many systems and may give a poor troubleshooting experience. Consider narrowing the search to common bin locations (e.g., /usr/local/bin, /opt, $HOME/.local/bin) and/or adding guidance like -maxdepth and when sudo is needed, rather than defaulting to a full /usr scan.

Suggested change
# Find the binary
find /usr -name "<tool>" 2>/dev/null
find ~/.local -name "<tool>" 2>/dev/null
# Find the binary in common locations (avoids slow full-disk scans)
find /usr/local/bin /usr/bin /opt -maxdepth 3 -type f -name "<tool>" 2>/dev/null
find "$HOME/.local/bin" -maxdepth 1 -type f -name "<tool>" 2>/dev/null

Copilot uses AI. Check for mistakes.

# 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`)
Copy link

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The workflow references binary_to_tool_map.md without the references/ prefix, while other docs (e.g., SKILL.md) refer to references/binary_to_tool_map.md. To avoid confusion about expected working directory, consider using the same explicit path here (or a proper relative markdown link).

Suggested change
2. Lookup in `binary_to_tool_map.md` (e.g., `rg` -> `ripgrep`)
2. Lookup in [binary_to_tool_map.md](./binary_to_tool_map.md) (e.g., `rg` -> `ripgrep`)

Copilot uses AI. Check for mistakes.
3. Install: `scripts/install_tool.sh <tool> install`

## Phase 3: Verification (AFTER install)

1. **Confirm installation succeeded:**
```bash
which <tool> # Should show path
<tool> --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**
61 changes: 61 additions & 0 deletions skills/cli-tools/references/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/<tool>
ls -la ~/.cargo/bin/<tool>
ls -la ~/.npm-global/bin/<tool>
ls -la /usr/local/bin/<tool>
```

2. **Ensure PATH includes common directories:**
```bash
# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
Copy link

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the PATH troubleshooting section, the example PATH export omits ~/.npm-global/bin even though the preceding checks (and later npm --prefix ~/.npm-global) suggest that as a common install location. Consider adding :$HOME/.npm-global/bin to the example so users who follow the doc don’t still hit "command not found" for npm-installed tools.

Suggested change
export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$HOME/.npm-global/bin:$PATH"

Copilot uses AI. Check for mistakes.
```

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 <tool-image> <tool> <args>

# Create alias for convenience
alias <tool>='docker run --rm -v "$PWD:/work" -w /work <tool-image> <tool>'
```

2. **Manual binary download:**
```bash
# Download release binary directly
curl -L <release-url> -o ~/.local/bin/<tool>
chmod +x ~/.local/bin/<tool>
```

3. **Compile from source:**
```bash
git clone <repo-url>
cd <repo>
make && make install PREFIX=~/.local
```

4. **Use package manager with user scope:**
```bash
pip install --user <tool>
npm install -g <tool> --prefix ~/.npm-global
cargo install <tool> # Installs to ~/.cargo/bin
```