Tool Integration in Skills: Connecting to External Systems
Learn how to design skills that guide Claude's tool usage. Master when to invoke tools, how to interpret results, and tool-aware skill patterns.
Tool Integration in Skills: Connecting to External Systems
Skills are not limited to text processing. Claude has access to tools: reading and writing files, executing shell commands, interacting with Git, and connecting to external services via MCP. Skills can guide how Claude uses these tools.
Effective tool integration means knowing when to use tools, how to use them appropriately, and how to interpret their results. This guide covers tool-aware skill design, from basic file operations to complex multi-tool workflows.
Understanding Tool Access
Available Tools
Claude Code provides access to several tool categories:
Filesystem:
- Read files
- Write files
- Create directories
- Search files
Shell:
- Execute commands
- Run scripts
- Process output
Git:
- Status and diff
- Commit and branch
- Log and history
MCP (Model Context Protocol):
- External APIs
- Databases
- Custom services
How Skills Influence Tool Use
Skills guide tool usage by:
- When to use tools - Conditions that trigger tool usage
- Which tools to prefer - Selection among options
- How to invoke tools - Parameters and patterns
- Interpreting results - Making sense of tool output
- Error handling - Recovering from tool failures
When to Use Tools
Tool Decision Framework
Guide Claude on when tools add value:
## Tool Usage Guidelines
### Use Filesystem Tools When
- Need to verify current code state before suggesting changes
- Must check if files exist before referencing them
- Need to read configuration to understand project setup
- Verifying changes after making edits
### Use Shell Tools When
- Running tests to validate changes
- Checking installed dependencies
- Building the project to catch errors
- Running linters or formatters
### Do NOT Use Tools When
- Question can be answered from conversation context
- User is asking hypothetical questions ("what if...")
- Tool output would not change the answer
- A faster approach exists without tools
### Prefer Conversation Over Tools When
- Previous messages contain needed information
- User has provided the relevant code
- Working with general concepts, not specific code
Avoiding Unnecessary Tool Calls
## Efficiency Guidelines
### Before Using a Tool, Ask
1. Do I already have this information?
2. Has the user provided what I need?
3. Will tool output change my answer?
4. Is there a simpler approach?
### Common Unnecessary Tool Uses
**Reading files already in context:**
If user pasted code, do not re-read the file.
**Checking things you just did:**
After writing a file, you know its content.
**Running commands for information you have:**
If you know the project uses React, do not run commands to verify.
### When Tools ARE Necessary
**Verification:**
After making changes, verify they work.
**Discovery:**
Finding files, checking project structure.
**Execution:**
Running tests, builds, or other processes.
Filesystem Tool Patterns
Reading Files Effectively
## File Reading Guidelines
### Before Reading
1. Check if content is already in conversation
2. Consider if partial read is sufficient
3. Verify file path makes sense for project
### Reading Patterns
**Targeted Reading:**
Read specific files when you know what you need.
Read: src/components/UserProfile.tsx Purpose: Understand current implementation before suggesting changes
**Discovery Reading:**
Start broad, then narrow down.
- Read package.json (understand project type)
- Read relevant config (tsconfig, eslint, etc.)
- Read specific source files
**Minimal Reading:**
Read only what is necessary.
Do: Read the function being discussed Don't: Read the entire 2000-line file
### After Reading
- Reference specific line numbers
- Quote relevant code sections
- Connect findings to user's question
Writing Files Safely
## File Writing Guidelines
### Before Writing
1. Understand current file content (read first unless new file)
2. Confirm the write serves user's goal
3. Plan minimal, targeted changes
### Writing Patterns
**Edit Existing Files:**
- Read current content
- Identify specific lines to change
- Make targeted modifications
- Preserve surrounding code
- Verify syntax is valid
**Create New Files:**
- Verify parent directory exists
- Follow project naming conventions
- Include standard headers/imports
- Match project code style
**Destructive Changes:**
For deleting content or files:
- Confirm with user if significant
- Explain what will be removed
- Consider backup/undo path
### After Writing
- Verify file syntax (run linter if available)
- Confirm change achieves intended goal
- Inform user of what was modified
Shell Tool Patterns
Command Execution Guidelines
## Shell Command Guidelines
### Safe Commands (Run Freely)
- Read-only operations: `ls`, `cat`, `grep`, `find`
- Status checks: `git status`, `npm list`
- Project tools: `npm test`, `npm run lint`
### Caution Commands (Consider Before Running)
- Installation: `npm install` (modifies node_modules)
- Builds: `npm run build` (may take time)
- Git operations: `git commit` (permanent)
### Dangerous Commands (Avoid or Confirm)
- Deletion: `rm`, especially `rm -rf`
- System modification: changing permissions, configs
- Network: uploading, external API calls
- Destructive git: `git reset --hard`, force push
### Command Patterns
**Chaining Commands:**
```bash
# Good: Related commands chained
npm install && npm test
# Avoid: Unrelated commands chained
npm test && rm -rf node_modules # Dangerous mix
Output Handling:
# Capture output for analysis
npm test 2>&1 | head -50
# Limit output for large results
find . -name "*.ts" | head -20
### Interpreting Command Output
```markdown
## Command Output Interpretation
### Test Output
PASS src/utils.test.ts (5 tests) FAIL src/api.test.ts (2 tests) ✕ should handle errors (15ms) ✕ should validate input (8ms)
Interpretation:
- 2 failing tests in api.test.ts
- Both related to error/validation handling
- Next step: Examine specific test failures
### Build Output
Warning: unused variable 'temp' in UserService.ts:45 Error: Cannot find module './config'
Interpretation:
- Warning is informational (can address later)
- Error blocks build (must fix import path)
- Priority: Fix error first
### Linter Output
UserService.ts:45:10 error Unexpected any. @typescript-eslint/no-explicit-any UserService.ts:52:1 warning Missing return type @typescript-eslint/explicit-function-return-type
Interpretation:
- 1 error (blocks if strict mode)
- 1 warning (should address but not blocking)
- Both in same file, can fix together
Git Tool Patterns
Git Operations
## Git Usage Guidelines
### Status and Diff
Always check before committing:
```bash
git status # What is changed
git diff # What specifically changed
git diff --staged # What will be committed
Branching
# Feature branches
git checkout -b feature/add-user-validation
# Fix branches
git checkout -b fix/resolve-null-pointer
# Never commit directly to main
Committing
# Conventional commit format
git commit -m "type(scope): description"
# Types: feat, fix, docs, style, refactor, test, chore
# Scope: Component or area affected
# Description: Imperative mood, present tense
Safety Rules
- Never
git reset --hardwithout confirming - Never
git push --forcewithout warning - Always check
git statusbefore destructive operations - Prefer
git stashover discarding changes
## MCP Integration
### Using MCP Servers
```markdown
## MCP Server Usage
### Available MCP Servers
Check project configuration for available MCP connections:
- Database access
- External APIs
- Custom tools
### MCP Patterns
**Discovery:**
- Check which MCP servers are configured
- Understand available tools from each server
- Use appropriate tool for the task
**Invocation:**
mcp_call( server="database", tool="query", arguments={ "sql": "SELECT * FROM users LIMIT 10", "database": "production" } )
**Result Handling:**
- Check for errors before using data
- Validate data structure matches expectations
- Handle pagination for large results
### Security Considerations
- Never expose credentials in tool calls
- Check permissions before querying sensitive data
- Log sensitive operations appropriately
Tool Workflows
Sequential Tool Patterns
## Sequential Workflow: Code Change
1. **Understand Current State**
- Read relevant files
- Check git status
2. **Make Changes**
- Edit files with targeted modifications
- Create new files if needed
3. **Verify Changes**
- Run linter
- Run tests
- Check build
4. **Report Results**
- Summarize what changed
- Report any issues
- Suggest next steps
### Example Flow
read(src/UserService.ts) → understand current implementation
edit(src/UserService.ts, changes) → apply modifications
shell(npm run lint) → check for style issues
shell(npm test) → verify tests pass
git diff → show what changed
report to user → summarize changes and test results
Parallel Tool Patterns
## Parallel Workflow: Project Analysis
When tools are independent, execute together:
Parallel: ├── read(package.json) → understand dependencies ├── read(tsconfig.json) → understand config ├── shell(git log -5 --oneline) → recent history └── find(*.test.ts) → test file locations
All results → comprehensive project overview
### When to Parallelize
- Reading multiple independent files
- Running non-conflicting status commands
- Gathering context from various sources
### When NOT to Parallelize
- Write operations (order matters)
- Commands that depend on each other
- Operations that might conflict
Conditional Tool Patterns
## Conditional Workflow: Error Recovery
-
Try: shell(npm test)
-
If fails: → Read test file to understand failure → Analyze error message → Suggest fix
-
If passes: → Continue to next step → Report success
### Decision Points
**Test Failure:**
If test fails with:
- Import error → Check package.json, suggest install
- Type error → Read source, suggest fix
- Assertion error → Compare expected vs actual
**Build Failure:**
If build fails with:
- Syntax error → Show location, suggest fix
- Type error → Analyze types, suggest correction
- Missing module → Check imports, suggest fix
Error Handling
Tool Failure Patterns
## Error Handling
### Filesystem Errors
**File Not Found:**
Error: ENOENT: no such file or directory
Response:
- Verify path is correct
- Check if file was moved/deleted
- Search for similar filenames
- Ask user for correct path
**Permission Denied:**
Error: EACCES: permission denied
Response:
- Cannot modify this file with current permissions
- May need elevated access
- Consider alternative approaches
### Shell Errors
**Command Not Found:**
Error: npm: command not found
Response:
- Required tool not installed
- Check if using correct environment
- Suggest installation steps
**Non-Zero Exit:**
Exit code: 1
Response:
- Command failed, but may have useful output
- Parse error message for details
- Suggest corrective action
### Recovery Strategies
1. **Retry with modifications**
Different path, different command
2. **Fallback approach**
Alternative tool or method
3. **Inform and ask**
Report error, ask user for guidance
4. **Graceful degradation**
Proceed without that tool's input
Tool-Aware Skill Examples
Code Review Skill with Tools
# Code Review Skill
## Tool Usage
### Before Review
-
git diff (or read PR diff) → Understand what changed
-
git log -5 --oneline → Context of recent changes
-
Read changed files if needed → Full context for complex changes
### During Review
- Reference specific file:line locations
- Use read_file only if more context needed
- Check test files if test coverage is a concern
### After Review
If suggesting changes:
- Verify file still matches expected state
- Make targeted edits
- Run npm test to verify
- Report results
Documentation Skill with Tools
# Documentation Generation Skill
## Tool Usage
### Discovery Phase
- Read source file to document
- Read existing docs (if any)
- Check for JSDoc comments in code
### Generation Phase
- Generate documentation content
- Write to appropriate file
- Verify formatting is correct
### Verification Phase
- Read written file
- Check links are valid (if linking)
- Run docs linter if available
Summary
Tool integration transforms skills from text-only guidance into powerful, action-oriented capabilities. Effective tool integration:
- Knows when to use tools - Not too eager, not too reluctant
- Uses tools appropriately - Right tool for the task
- Handles results intelligently - Interprets output, recovers from errors
- Sequences tools effectively - Logical workflows
- Maintains safety - Avoids destructive operations
Skills that integrate tools well extend Claude from an advisor into an assistant that can take action, verify results, and complete real tasks.
This concludes the AI Skills guide series. You now have a comprehensive understanding of skill design, from basic concepts through advanced techniques. Start building skills that transform how you work with AI.