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:

1. When to use tools - Conditions that trigger tool usage
2. Which tools to prefer - Selection among options
3. How to invoke tools - Parameters and patterns
4. Interpreting results - Making sense of tool output
5. 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.

1. Read package.json (understand project type)
2. Read relevant config (tsconfig, eslint, etc.)
3. 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:**

1. Read current content
2. Identify specific lines to change
3. Make targeted modifications
4. Preserve surrounding code
5. Verify syntax is valid

**Create New Files:**

1. Verify parent directory exists
2. Follow project naming conventions
3. Include standard headers/imports
4. Match project code style

**Destructive Changes:**

For deleting content or files:

1. Confirm with user if significant
2. Explain what will be removed
3. 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 --hard without confirming
• Never git push --force without warning
• Always check git status before destructive operations
• Prefer git stash over 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:**

1. Check which MCP servers are configured
2. Understand available tools from each server
3. 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

1. Try: shell(npm test)

2. If fails: → Read test file to understand failure → Analyze error message → Suggest fix

3. 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

1. git diff (or read PR diff) → Understand what changed

2. git log -5 --oneline → Context of recent changes

3. 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:

1. Verify file still matches expected state
2. Make targeted edits
3. Run npm test to verify
4. Report results

Documentation Skill with Tools

# Documentation Generation Skill

## Tool Usage

### Discovery Phase

1. Read source file to document
2. Read existing docs (if any)
3. Check for JSDoc comments in code

### Generation Phase

1. Generate documentation content
2. Write to appropriate file
3. Verify formatting is correct

### Verification Phase

1. Read written file
2. Check links are valid (if linking)
3. Run docs linter if available

Summary

Tool integration transforms skills from text-only guidance into powerful, action-oriented capabilities. Effective tool integration:

1. Knows when to use tools - Not too eager, not too reluctant
2. Uses tools appropriately - Right tool for the task
3. Handles results intelligently - Interprets output, recovers from errors
4. Sequences tools effectively - Logical workflows
5. 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.