Skill Development Best Practices
Skill Development Best Practices
This guide provides comprehensive best practices for developing secure, maintainable AI agent skills across OpenClaw, Claude Code, Cursor, and VS Code platforms.
Security-First Architecture
1. Principle of Least Privilege
Design Pattern: Request only the minimum permissions needed for your skill to function.
# WRONG - Over-privileged skill
permissions:
- full_system_access
- network:all
- filesystem:write
# CORRECT - Minimal permissions
permissions:
- filesystem:read:/documents
- network:outbound:https://api.example.com
- user:identity
Implementation Checklist:
- List all required permissions before development
- Remove unused permissions before publishing
- Use specific paths instead of wildcards
- Implement runtime permission checks
2. Input Validation & Sanitization
Defense Pattern: Validate all user inputs at multiple layers.
import re
from typing import Optional
class SecureSkill:
def __init__(self):
self.max_input_length = 1024
self.forbidden_commands = ['rm', 'dd', 'format', 'del']
def validate_file_path(self, path: str) -> bool:
"""Validate file path to prevent directory traversal"""
# Prevent path traversal attacks
normalized = os.path.normpath(path)
if ".." in normalized:
return False
# Check against allowed directories
allowed_dirs = ['/documents', '/projects']
return any(normalized.startswith(d) for d in allowed_dirs)
def sanitize_command(self, cmd: str) -> Optional[str]:
"""Sanitize shell commands"""
for forbidden in self.forbidden_commands:
if re.search(rf'\b{forbidden}\b', cmd, re.IGNORECASE):
return None
# Additional validation
if len(cmd) > self.max_input_length:
return None
return cmd.strip()
def process_user_input(self, user_input: str) -> bool:
"""Multi-layer input validation"""
# Layer 1: Length check
if len(user_input) > self.max_input_length:
raise ValueError("Input too long")
# Layer 2: Character validation
if not re.match(r'^[a-zA-Z0-9\s\-_\.]+$', user_input):
raise ValueError("Invalid characters")
# Layer 3: Semantic validation
return True
3. Error Handling & Information Disclosure
Security Pattern: Don’t leak sensitive information in error messages.
# WRONG - Information disclosure
def process_file(filename):
try:
with open(filename) as f:
return process(f)
except Exception as e:
return f"Error: {e}" # Reveals system paths, internals
# CORRECT - Safe error handling
def process_file(filename):
try:
validate_file_path(filename)
with open(filename) as f:
return process(f)
except FileNotFoundError:
logger.warning(f"File not found: {filename}")
return "Unable to process file"
except Exception as e:
logger.error(f"Processing error", exc_info=True)
return "An error occurred processing your request"
4. Secure Data Storage
Implementation Pattern: Never store sensitive data in plaintext.
import secrets
import json
from cryptography.fernet import Fernet
class SecureStorage:
def __init__(self):
self.cipher_key = os.environ.get('SKILL_CIPHER_KEY')
if not self.cipher_key:
raise ValueError("SKILL_CIPHER_KEY not configured")
self.cipher = Fernet(self.cipher_key.encode())
def store_credential(self, credential_type: str, value: str):
"""Encrypt and store credentials securely"""
encrypted = self.cipher.encrypt(value.encode())
storage = {
'type': credential_type,
'data': encrypted.decode(),
'timestamp': datetime.now().isoformat(),
'salt': secrets.token_hex(16)
}
# Store to secure location
self._save_to_vault(credential_type, storage)
def retrieve_credential(self, credential_type: str):
"""Retrieve and decrypt credentials"""
storage = self._load_from_vault(credential_type)
return self.cipher.decrypt(storage['data'].encode()).decode()
Development Workflow
Quality Assurance Process
┌─────────────────────────────────────────────┐
│ 1. Design & Planning │
│ - Security requirements │
│ - Permission scope │
│ - Data flow diagram │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 2. Secure Implementation │
│ - Code review checklist │
│ - Input validation testing │
│ - Permission minimization │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 3. Security Testing │
│ - Unit tests for input validation │
│ - Integration tests │
│ - Static analysis scanning │
│ - Penetration testing │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 4. Code Review │
│ - Security review │
│ - Permission audit │
│ - Documentation check │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 5. Publication & Monitoring │
│ - Sign skill with ed25519 │
│ - Publish to registry │
│ - Monitor for abuse │
└─────────────────────────────────────────────┘
Pre-Publish Checklist
- All inputs are validated and sanitized
- Error messages don’t leak sensitive info
- No hardcoded credentials or API keys
- Sensitive data is encrypted at rest
- Permissions are minimized
- Security review completed
- Tests cover security scenarios
- Static analysis passes
- Documentation is complete
- Signature keys are secure
Pre-Mutation Receipts for Installers and Hooks
Skill and plugin installers increasingly wire several agent surfaces at once: settings files, hooks, commands, MCP servers, subagents, rules, and instruction files. Treat that installer as a supply-chain boundary, not as ordinary setup glue. Before the first write, emit a small receipt that can be reviewed, logged, or declined.
A useful receipt is privacy-safe: it records what will be wired, not raw prompts, secrets, source code, full transcripts, or command output.
{
"schema": "agent.install.plan.v1",
"installer": "example-skill-installer",
"target_platforms": ["Claude Code", "OpenClaw"],
"resources_planned": {
"skills": ["security-review"],
"hooks": ["PreToolUse: secret-file guard"],
"mcp_servers": ["github"],
"instruction_files": ["AGENTS.md"],
"settings_files": [".claude/settings.json"]
},
"external_commands_planned": ["npm install --package-lock-only"],
"network_after_install": ["api.github.com"],
"backups_planned": [".claude/settings.json.bak"],
"writes_started": false,
"next_safe_action": "review plan, then run installer with --apply"
}
Implementation guidance:
- Provide a
--planor--dry-runmode that exits before writing. - Show the effective mode (
plan,apply,repair) and require an explicit transition to mutation. - Map every post-install change back to a planned write in the receipt.
- Exclude secrets, environment dumps, raw prompts, transcripts, customer data, source code, and raw tool output.
- Store the receipt with the skill inventory or approval record for later audit.
Platform-Specific Guidelines
OpenClaw Skills
Best Practice: Use SKILL.md structure with clear sections.
# skill.md
---
name: "Data Analyzer"
version: "1.0.0"
publisher: "trusted-publisher"
permissions:
- filesystem:read:/data
- network:outbound
---
## Description
Analyzes data files and generates reports.
## Security Considerations
- Only processes files in /data directory
- Does not execute arbitrary code
- All external requests use HTTPS
## Installation
Install from trusted sources only.
## Usage
```{instruction}
Analyze data with validation: \`data_analyzer --validate --input <file>\`
### Claude Code Skills
**Best Practice**: Leverage Claude's built-in security features.
```json
{
"name": "secure-tool",
"version": "1.0.0",
"tools": [
{
"name": "process_data",
"description": "Process user data securely",
"parameters": {
"data_path": {
"type": "string",
"description": "Path to data file",
"pattern": "^/allowed/paths/.*$"
}
}
}
],
"security": {
"require_user_confirmation": ["filesystem:write", "network:outbound"],
"sandbox": true,
"resource_limits": {
"memory_mb": 512,
"timeout_seconds": 30
}
}
}
Cursor & VS Code Extensions
Best Practice: Implement workspace trust verification.
{
"name": "secure-extension",
"version": "1.0.0",
"engine": {
"vscode": "^1.70.0"
},
"permissions": ["workspace"],
"security": {
"requireWorkspaceTrust": true,
"requireSignature": true,
"supportedEnvironments": ["desktop"]
}
}
Code Review Checklist
Security Review Template
# Security Code Review Checklist
## Authentication & Authorization
- [ ] All user inputs are validated
- [ ] Authorization checks are in place
- [ ] Least privilege principle is followed
- [ ] No hardcoded credentials
## Input Validation
- [ ] All inputs validated for type and length
- [ ] Injection attacks prevented
- [ ] Path traversal attacks prevented
- [ ] Command injection attacks prevented
## Data Protection
- [ ] Sensitive data encrypted at rest
- [ ] Encrypted in transit (HTTPS)
- [ ] No data logging of sensitive info
- [ ] Proper data retention policies
## Error Handling
- [ ] Errors logged securely
- [ ] No sensitive info in error messages
- [ ] Graceful failure modes
- [ ] User-friendly error messages
## Dependencies
- [ ] All dependencies reviewed
- [ ] No known vulnerabilities
- [ ] Pinned versions used
- [ ] Supply chain verified
## Security Testing
- [ ] Unit tests for security paths
- [ ] Integration tests complete
- [ ] Security scanning passed
- [ ] Manual testing performed
Performance & Sustainability
Monitoring Best Practices
import logging
import metrics
class SkillMonitoring:
def __init__(self):
self.logger = logging.getLogger('skill-monitor')
def log_execution(self, skill_name, duration, success):
"""Log skill execution metrics"""
metrics.histogram(
'skill.execution.duration_ms',
duration,
tags={'skill': skill_name, 'success': success}
)
def track_security_event(self, event_type, details):
"""Track security-relevant events"""
self.logger.warning(
f"Security event: {event_type}",
extra={'details': details, 'timestamp': datetime.now()}
)
metrics.increment(
'skill.security_events',
tags={'event_type': event_type}
)
Building Community Trust
Transparency Best Practices
- Clear Documentation
- Document all permissions explicitly
- Explain why each permission is needed
- Provide code examples
- Regular Updates
- Keep dependencies current
- Apply security patches promptly
- Publish changelog entries
- Community Engagement
- Respond to issues quickly
- Accept security contributions
- Provide security contact info
- Certification Compliance
- Pass security audits
- Maintain OWASP AST10 compliance
- Display trust badges
Last updated: March 2026
Example
Put whatever you like here: news, screenshots, features, supporters, or remove this file and don’t use tabs at all.
Leadership & Founding Members
Project Leadership
Current Leaders
Ken Huang
Hammad Atta
Fabio Cerullo
Aonan Guan
Bhavya Gupta
Niv Hoffman
Iftach Orr
Akram Sheriff
AIVSS Distinguished Review Board
The OWASP AIVSS project’s Distinguished Review Board comprises world-renowned cybersecurity leaders, former government officials, and industry pioneers who provide strategic guidance and expert oversight for the AI Vulnerability Scoring System framework. We thank them for their guidance, several of whom have also supported this project’s work.
Rob Joyce
Advisor to PwC and OpenAI, Former Special Assistant to the President and Cybersecurity Coordinator
Jason Clinton
Deputy CISO, Anthropic
Amy R. Steagall
Chief Information Security Officer, Stanford University
Martin Stanley
AI Risk Management Framework Lead, NIST
Apostol Vassilev
Research Supervisor, NIST
Andrew Coyne
CISO, Banner Health, Former CISO, Mayo Clinic
Kevin Rocque
Managing Director/Executive Vice President, Global Technology Risk Officer, TD Bank
Jeff Williams
Former Global OWASP Chair, Founder and CTO, Contrast Security
Michael Tran Duff
University Chief Information Security and Data Privacy Officer, Harvard University
Emil Bender Lassen
Standards Lead, AIUC-1
Agentic Skills Top 10 Founding Members
Founding members of the OWASP Agentic Skills Top 10 project itself — project leads, co-leads, and additional contributors — listed alphabetically. Several also contribute to the sibling OWASP AIVSS project listed above.
Ken Huang
Project Lead, Agentic Skills Top 10
Hammad Atta
Co-Lead, Agentic Skills Top 10
Manish Bhatt
Security Researcher, AWS
Fabio Cerullo
Co-Lead, Agentic Skills Top 10
David Girard
Senior Director, AI Security & AI Alliances, Trend Micro
Aonan Guan
Co-Lead, Agentic Skills Top 10
Bhavya Gupta
Co-Lead, Agentic Skills Top 10
Pamela Gupta
Founder & CEO, OutSecure / Trusted AI
Idan Habler
Staff AI/ML Security Researcher, Intuit
Niv Hoffman
CTO, Air Security
Charles Iheagwara
AI/ML Security Leader, AstraZeneca
Sushmitha Janapareddy
Director - Security Integrations, American Express
Edward Lee
Vice President, Lead AI Security, JP Morgan
KJ Lian
Senior Manager, Data & AI (Public Sector), AWS
Vineeth Sai Narajala
Application Security, AWS
Iftach Orr
Co-Lead, Agentic Skills Top 10
Kanna Sekar
Cyber Security, Google
Akram Sheriff
Co-Lead, Agentic Skills Top 10
Dennis Xu
Research VP, AI, Gartner
OWASP AIVSS Founding Members
The OWASP AIVSS (Agentic AI Vulnerability Scoring System) project is a sibling OWASP initiative focused on scoring the severity of agentic AI vulnerabilities. Its founding members are recognized here as OWASP founding members in the agentic AI security space; many of them have also contributed directly to the Agentic Skills Top 10 project’s research and review process.
Sunil Agrawal
Chief Information Security Officer, Glean
David Ames
Partner, PwC
Michael Bargury
Founder and CTO, Zenity
Joshua Beck
Application Security Architect, SAS
Manish Bhatt
Security Researcher, Amazon Kuiper Security
Mark Breitenbach
Security Engineer, Dropbox
Anat Bremler-Barr
Professor of Computer Science, Tel Aviv University
Siah Burke
HIPAA Security Officer, Siah.ai
David Campbell
AI Security, Scale AI
Ying-Jung Chen
AI safety researcher, PhD, Georgia Institute of Technology
Anton Chuvakin
Security Solution Strategy, Google
Jason Clinton
CISO, Anthorphic
Adam Dawson
Staff AI Security Researcher, Dreadnode
Leon Derczynski
Principal Research Scientist, NVIDIA
Walker Lee Dimon
AI Security Researcher, MITRE
Marissa Dotter
AI Security Researcher, MITRE
Dan Goldberg
ISO Market Lead, Omnicom
David Haber
CEO, Lakera
Idan Habler
Staff AI/ML Security Researcher, Intuit
Jason Haddix
Founder, Arcanum Information Security
Keith Hoodlet
Director of AI/ML & AppSec, Trail of Bits
Ken Huang
AIVSS Project Lead, OWASP
Chris Hughes
CEO, Aquia
Charles Iheagwara
AI/ML Security Leader, AstraZeneca
Krystal Jackson
Researcher, Center for Long-Term Cybersecurity, UC Berkeley
Sushmitha Janapareddy
Director - Security Integrations, American Express
Rob Joyce
Former Cybersecurity Director of NSA, Advisor to PwC, PwC
Diana Kelley
CISO, Noma Security
Prashant Kulkarni
Lead AI Security Research Engineer, Google Cloud
Mahesh Lambe
Founder, MIT, Unify Dynamics
Edward Lee
Vice President, Lead AI Security, JP Morgan
Nate Lee
CEO, Cloudsec.ai
Vishwas Manral
CEO, Precize.ai
Daniela Muhaj
Executive-in-Residence for Research & Development, AI 2030
Vineeth Sai Narajala
Application Security, AWS
Om Narayan
AI Security Researcher, AWS
Varun Pant
Engineering and Product Leader, AI applications at the Automated Reasoning Group, AWS
Advait Patel
Senior Site Reliability Engineer (DevSecOps + Cloud + AIOps), Broadcom, IEEE
Alex Polyakov
CEO, adversa.ai
Ramesh Raskar
Professor & Director, MIT Media Lab
Ron F. Del Rosario
VP-Head of AI Security, SAP
Tal Shapira
Co-Founder & CTO, Reco AI
Akram Sheriff
Senior AI/ML Software Engineering Leader, Cisco
Samantha Siau
Security and Compliance, Anthropic
Kevin Simmonds
Partner on AI Offensive Security, PWC
Martin Stanley
NIST AI RMF Lead, Independent
Omar A. Turner
General Manager of Security, Microsoft
Apostol Vassilev
AI Research Team Supervisor, NIST
Matthew Versaggi
AI Fellow, White House Presidential Innovation Fellow
David Webb
Agency Cybersecurity Officer, Cybersecurity and Infrastructure Security Agency
Dennis Xu
Research VP, AI, Gartner
Xiaochen Zhang
Executive Director and Chief Responsible AI Officer, AI 2030
Recognition
We extend our gratitude to all founding members who have contributed to establishing this crucial framework for AI security assessment. Their vision and dedication have been instrumental in shaping the Agentic Skills Top 10 project.
Get Involved
Interested in contributing to the Agentic Skills Top 10 project? We welcome new contributors and leaders. Please see our Contribution Guidelines for more information on how to get involved.