Agent Skills Security Best Practices

Agent Skills are convenient, but blindly trusting skills from external sources is risky.

This article covers best practices for using Agent Skills securely.

Understanding the Risks

What Skills Can Do

SKILL.md content instructs AI. Malicious skills pose these risks:

• Inappropriate operations: File deletion, sensitive data exposure
• scripts/ execution: Arbitrary code execution
• Data leakage: Instructions to send project info externally

High-Risk Scenarios

• Downloading skills from unknown sources
• Skills containing scripts/ directories
• Skills connecting to external APIs

Identifying Trustworthy Skills

Verification Checklist

1. Source Reliability

• Is it from an official repository (like anthropics/skills)?
• Is the author trustworthy (past activity, other contributions)?
• Star and fork counts (not absolute, but indicative)

2. Code Review

Always review content before installing:

Copy# Check SKILL.md contents
cat path/to/skill/SKILL.md

# If scripts/ exists, review contents
ls path/to/skill/scripts/
cat path/to/skill/scripts/*.sh

3. Permission Check

Verify what the skill tries to execute:

• File operations (read, write, delete)
• External communication (API calls, data transmission)
• System commands (scripts/ contents)

Handling scripts/ Directories

Risks

The scripts/ directory contains executable scripts. While useful, this enables arbitrary code execution.

Countermeasures

1. Be Cautious with scripts/

Copy# Check if scripts/ exists
ls -la path/to/skill/

# Review contents
cat path/to/skill/scripts/*

2. Don't Use Scripts You Don't Understand

If you can't understand a script, either skip the skill or remove scripts/:

Copyrm -rf path/to/skill/scripts/

3. Enable Execution Confirmation

Claude Code settings can require confirmation before script execution.

Team Policies

Skill Approval Process

Review skills before team adoption:

1. Propose: Share desired skill with team
2. Review: Check SKILL.md and scripts/ contents
3. Approve: Security lead approval
4. Deploy: Only use approved skills

Allowlist Approach

Manage trusted skills via allowlist:

Copy# allowed-skills.txt
anthropics/code-review
anthropics/pr-template
internal/our-custom-skill

Prohibit non-allowlisted skills.

Regular Reviews

Periodically review installed skills:

• Check skill update contents
• Remove unused skills
• Monitor for new vulnerabilities

Creating Secure Skills

When creating skills, keep security in mind.

Principle of Least Privilege

Request only necessary operations:

Copy# ❌ Too broad
description: Can operate on all files in the project

# ⭕ Limited
description: Review TypeScript files in src/ directory

Don't Include Secrets

Never put API keys or credentials in SKILL.md:

Copy# ❌ Dangerous
API_KEY=sk-xxxxx

# ⭕ Reference environment variables
Use environment variable $API_KEY

Document scripts/ Clearly

If including scripts/, document clearly:

Copy#!/bin/bash
# This script runs tests
# Side effects: None
# Permissions needed: Read-only

npm test

Incident Response

When Finding Suspicious Skills

1. Stop usage: Delete or disable the skill
2. Check impact: Review logs for unauthorized operations
3. Report: Report to the skill's source (GitHub, etc.)

Regular Security Checks

Copy# List installed skills
ls -la ~/.claude/skills/

# Find skills with scripts/
find ~/.claude/skills -name "scripts" -type d

Summary

Key points for secure Agent Skills usage:

1. Verify source: Trustworthy author/repository?
2. Review content: Check SKILL.md and scripts/
3. scripts/ caution: Don't use scripts you don't understand
4. Team rules: Establish approval process and allowlists

Stay security-conscious while leveraging Agent Skills.

Related Articles

• How to Create Your Own Skills - Create secure skills
• How to Share Skills with Your Team - Team policies
• 10 Best Agent Skills for Developers - Trusted skills
• What Are Agent Skills? - Understand the basics