Skip to content
Skills Library
AI & agents · Learning & explanation

bash-tools

/bash-tools

Proper usage of Bash and file operation tools. Use this skill when executing shell commands, writing files, or when tempted to use echo/cat/heredoc to pipe content to files. Prevents permission circumvention patterns like piping multiline content through echo instead of using Write tool. Covers Bash tool, Write tool, Edit tool, and Read tool best practices.

Repository
DraftForge ↗
Licence
GPL-3.0
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

GPL-3.0, otwarta.

What it does and when to use it

Proper usage of Bash and file operation tools. Use this skill when executing shell commands, writing files, or when tempted to use echo/cat/heredoc to pipe content to files. Prevents permission circumvention patterns like piping multiline content through echo instead of using Write tool. Covers Bash tool, Write tool, Edit tool, and Read tool best practices.

Original author description

Proper usage of Bash and file operation tools. Use this skill when executing shell commands, writing files, or when tempted to use echo/cat/heredoc to pipe content to files. Prevents permission circumvention patterns like piping multiline content through echo instead of using Write tool. Covers Bash tool, Write tool, Edit tool, and Read tool best practices.

How it works

  1. Core Principle
  2. Tool Selection Decision Tree
  3. Prohibited Patterns
  4. Tool References
  5. When Write Tool is Blocked
  6. Updating This Skill
  7. Quick Reference
Original SKILL.md headings · 87 lines, 469 words
SKILL.md preview
---
name: bash-tools
description: Proper usage of Bash and file operation tools. Use this skill when executing shell commands, writing files, or when tempted to use echo/cat/heredoc to pipe content to files. Prevents permission circumvention patterns like piping multiline content through echo instead of using Write tool. Covers Bash tool, Write tool, Edit tool, and Read tool best practices.
---

# Bash Tools

Guidelines for proper tool selection when executing commands or modifying files.

## Core Principle

**Use specialized file tools for file operations. Use Bash only for actual shell commands.**

Never use Bash to circumvent file operation permissions. If Write tool is blocked, that's intentional - do not work around it with `echo`, `cat`, or heredocs.

## Tool Selection Decision Tree

```
Need to create/overwrite a file?
├── YES → Use Write tool (NOT echo/cat/heredoc)
└── NO → Continue...

Need to edit part of a file?
├── YES → Use Edit tool (NOT sed/awk)
└── NO → Continue...

Need to read file contents?
├── YES → Use Read tool (NOT cat/head/tail)
└── NO → Continue...

Need to search file contents?
├── YES → Use Grep tool (NOT grep/rg in Bash)
└── NO → Continue...

Need to find files by pattern?
├── YES → Use Glob tool (NOT find/ls in Bash)
└── NO → Continue...

Is this an actual shell command? (git, npm, docker, make, etc.)
├── YES → Use Bash tool
└── NO → Reconsider - probably need a file tool
```

## Prohibited Patterns

These patterns attempt to circumvent Write tool permissions and MUST NOT be used:

| Pattern | Why It's Wrong | Correct Approach |
|---------|---------------|------------------|
| `echo "content" > file.py` | Bypasses Write permissions | Use Write tool |
| `cat << 'EOF' > file.py` | Heredoc bypasses permissions | Use Write tool |
| `printf '%s' "$content" > file` | Same as echo bypass | Use Write tool |
| `tee file.py <<< "content"` | Redirect bypass | Use Write tool |

See [references/permission-patterns.md](references/permission-patterns.md) for comprehensive examples.

## Tool References

- [Write Tool](references/write-tool.md) - Creating and overwriting files
- [Bash Tool](references/bash-tool.md) - Running shell commands
- [Edit Tool](references/edit-tool.md) - Modifying existing files
- [Read Tool](references/read-tool.md) - Reading file contents

## When Write Tool is Blocked

If the Write tool is blocked for a file:

1. **Accept the block** - It exists for a reason
2. **Ask the user** if they want to allow the operation
3. **Do NOT** attempt to use Bash to write the file instead

The permission system protects the user. Circumventing it defeats its purpose.

## Updating This Skill

When encountering new permission circumvention patterns or tool usage issues, see [references/updating-skill.md](references/updating-skill.md).

## Quick Reference

| Task | Tool | NOT This |
|------|------|----------|
| Create file | Write | `echo > file` |
| Edit file | Edit | `sed -i` |
| Read file | Read | `cat file` |
| Search content | Grep | `grep pattern` |
| Find files | Glob | `find . -name` |
| Git commands | Bash | - |
| npm/yarn | Bash | - |
| docker/make | Bash | - |
| Run tests | Bash | - |
Files in this package (7)
  • SKILL.md 3 KB
  • references/bash-tool.md 2 KB
  • references/edit-tool.md 2 KB
  • references/permission-patterns.md 3 KB
  • references/read-tool.md 2 KB
  • references/updating-skill.md 3 KB
  • references/write-tool.md 2 KB

Versions

The database has no other skills named bash-tools.

Database snapshot: 13.11.2026 · package version 9ed5907a1f82 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95harness-tool-errors
    Claude Code harness tool errors — Read on a missing path, directory or oversized file; Edit before Read or after a formatter; Bash permission denials. Use when a Read, Edit, Write or Bash call errors.
  • 92write-script-bash
    MUST use when writing Bash scripts.
  • 95bash-linux
    Bash and Linux/macOS shell patterns - operators, files, processes, text tools, scripts. Use for shell work on Unix.
  • 100context-mode
    Use context-mode tools (ctx_execute, ctx_execute_file) instead of Bash/cat when processing large outputs. Triggers: "analyze logs", "summarize output", "process data", "parse JSON", "filter results", "extract errors", "check build output", "analyze dependencies", "process API…
  • 100shell-expert
    Shell scripting expertise, command-line tools, automation, and cross-platform scripting best practices. Covers shell script development, CLI tool usage, and system automation with bash, zsh, and POSIX shell. Use when user mentions shell scripts, bash, zsh, CLI commands, pipes,…
  • 100mcp-bash
    Build, debug and package MCP servers written in Bash with the mcp-bash framework (mcp-bash-framework). Use whenever the user wants to create an MCP server from shell scripts or CLIs, add or fix tools, resources, prompts or completions in an mcp-bash project, wire one into Claude…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.