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