Conversation
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 <info@sebastianmendel.de>
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
There was a problem hiding this comment.
Pull request overview
Refactors the cli-tools skill documentation to keep SKILL.md under the writing-skills token budget by moving detailed troubleshooting and missing-tool resolution guidance into on-demand reference docs.
Changes:
- Adds new reference docs for troubleshooting (
PATH, permission/system restrictions) and a detailed missing-tool resolution workflow. - Trims
skills/cli-tools/SKILL.mdto a concise workflow summary and expands its references section to link to the new docs. - Condenses the “Preferred Tools” section to a short comparison table, removing long per-tool examples.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| skills/cli-tools/references/troubleshooting.md | New reference doc for PATH and restricted-install scenarios. |
| skills/cli-tools/references/resolution-workflow.md | New detailed diagnostic/install/verify workflow for missing tools. |
| skills/cli-tools/SKILL.md | Shortens core skill doc and points readers to reference files for details. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 2. **Ensure PATH includes common directories:** | ||
| ```bash | ||
| # Add to ~/.bashrc or ~/.zshrc | ||
| export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH" |
There was a problem hiding this comment.
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.
| export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH" | |
| export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$HOME/.npm-global/bin:$PATH" |
| ## Phase 2: Installation | ||
|
|
||
| 1. Extract tool name from error | ||
| 2. Lookup in `binary_to_tool_map.md` (e.g., `rg` -> `ripgrep`) |
There was a problem hiding this comment.
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).
| 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`) |
| # Find the binary | ||
| find /usr -name "<tool>" 2>/dev/null | ||
| find ~/.local -name "<tool>" 2>/dev/null |
There was a problem hiding this comment.
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.
| # 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 |
Summary
references/troubleshooting.md- PATH issues, installation blocked, permission problemsreferences/resolution-workflow.md- Full diagnostic/install/verify workflow for missing toolsContext
Per writing-skills standards, SKILL.md should be under 500 words. Detailed content belongs in reference files loaded on demand.