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 --plan or --dry-run mode 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

  1. Clear Documentation
    • Document all permissions explicitly
    • Explain why each permission is needed
    • Provide code examples
  2. Regular Updates
    • Keep dependencies current
    • Apply security patches promptly
    • Publish changelog entries
  3. Community Engagement
    • Respond to issues quickly
    • Accept security contributions
    • Provide security contact info
  4. 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

Ken Huang

Hammad Atta

Hammad Atta

Fabio Cerullo

Fabio Cerullo

Aonan Guan

Aonan Guan

Bhavya Gupta

Bhavya Gupta

Niv Hoffman

Niv Hoffman

Iftach Orr

Iftach Orr

Akram Sheriff

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

Rob Joyce

Advisor to PwC and OpenAI, Former Special Assistant to the President and Cybersecurity Coordinator

Jason Clinton

Jason Clinton

Deputy CISO, Anthropic

Amy R. Steagall

Amy R. Steagall

Chief Information Security Officer, Stanford University

Martin Stanley

Martin Stanley

AI Risk Management Framework Lead, NIST

Apostol Vassilev

Apostol Vassilev

Research Supervisor, NIST

Andrew Coyne

Andrew Coyne

CISO, Banner Health, Former CISO, Mayo Clinic

Kevin Rocque

Kevin Rocque

Managing Director/Executive Vice President, Global Technology Risk Officer, TD Bank

Jeff Williams

Jeff Williams

Former Global OWASP Chair, Founder and CTO, Contrast Security

Michael Tran Duff

Michael Tran Duff

University Chief Information Security and Data Privacy Officer, Harvard University

Emil Bender Lassen

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

Ken Huang

Project Lead, Agentic Skills Top 10

Hammad Atta

Hammad Atta

Co-Lead, Agentic Skills Top 10

Manish Bhatt

Manish Bhatt

Security Researcher, AWS

Fabio Cerullo

Fabio Cerullo

Co-Lead, Agentic Skills Top 10

David Girard

David Girard

Senior Director, AI Security & AI Alliances, Trend Micro

Aonan Guan

Aonan Guan

Co-Lead, Agentic Skills Top 10

Bhavya Gupta

Bhavya Gupta

Co-Lead, Agentic Skills Top 10

Pamela Gupta

Pamela Gupta

Founder & CEO, OutSecure / Trusted AI

Idan Habler

Idan Habler

Staff AI/ML Security Researcher, Intuit

Niv Hoffman

Niv Hoffman

CTO, Air Security

Charles Iheagwara

Charles Iheagwara

AI/ML Security Leader, AstraZeneca

Sushmitha Janapareddy

Sushmitha Janapareddy

Director - Security Integrations, American Express

Edward Lee

Edward Lee

Vice President, Lead AI Security, JP Morgan

KJ Lian

KJ Lian

Senior Manager, Data & AI (Public Sector), AWS

Vineeth Sai Narajala

Vineeth Sai Narajala

Application Security, AWS

Iftach Orr

Iftach Orr

Co-Lead, Agentic Skills Top 10

Kanna Sekar

Kanna Sekar

Cyber Security, Google

Akram Sheriff

Akram Sheriff

Co-Lead, Agentic Skills Top 10

Dennis Xu

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

Sunil Agrawal

Chief Information Security Officer, Glean

David Ames

David Ames

Partner, PwC

Michael Bargury

Michael Bargury

Founder and CTO, Zenity

Joshua Beck

Joshua Beck

Application Security Architect, SAS

Manish Bhatt

Manish Bhatt

Security Researcher, Amazon Kuiper Security

Mark Breitenbach

Mark Breitenbach

Security Engineer, Dropbox

Anat Bremler-Barr

Anat Bremler-Barr

Professor of Computer Science, Tel Aviv University

Siah Burke

Siah Burke

HIPAA Security Officer, Siah.ai

David Campbell

David Campbell

AI Security, Scale AI

Ying-Jung Chen

Ying-Jung Chen

AI safety researcher, PhD, Georgia Institute of Technology

Anton Chuvakin

Anton Chuvakin

Security Solution Strategy, Google

Jason Clinton

Jason Clinton

CISO, Anthorphic

Adam Dawson

Adam Dawson

Staff AI Security Researcher, Dreadnode

Leon Derczynski

Leon Derczynski

Principal Research Scientist, NVIDIA

Walker Lee Dimon

Walker Lee Dimon

AI Security Researcher, MITRE

Marissa Dotter

Marissa Dotter

AI Security Researcher, MITRE

Dan Goldberg

Dan Goldberg

ISO Market Lead, Omnicom

David Haber

David Haber

CEO, Lakera

Idan Habler

Idan Habler

Staff AI/ML Security Researcher, Intuit

Jason Haddix

Jason Haddix

Founder, Arcanum Information Security

Keith Hoodlet

Keith Hoodlet

Director of AI/ML & AppSec, Trail of Bits

Ken Huang

Ken Huang

AIVSS Project Lead, OWASP

Chris Hughes

Chris Hughes

CEO, Aquia

Charles Iheagwara

Charles Iheagwara

AI/ML Security Leader, AstraZeneca

Krystal Jackson

Krystal Jackson

Researcher, Center for Long-Term Cybersecurity, UC Berkeley

Sushmitha Janapareddy

Sushmitha Janapareddy

Director - Security Integrations, American Express

Rob Joyce

Rob Joyce

Former Cybersecurity Director of NSA, Advisor to PwC, PwC

Diana Kelley

Diana Kelley

CISO, Noma Security

Prashant Kulkarni

Prashant Kulkarni

Lead AI Security Research Engineer, Google Cloud

Mahesh Lambe

Mahesh Lambe

Founder, MIT, Unify Dynamics

Edward Lee

Edward Lee

Vice President, Lead AI Security, JP Morgan

Nate Lee

Nate Lee

CEO, Cloudsec.ai

Vishwas Manral

Vishwas Manral

CEO, Precize.ai

Daniela Muhaj

Daniela Muhaj

Executive-in-Residence for Research & Development, AI 2030

Vineeth Sai Narajala

Vineeth Sai Narajala

Application Security, AWS

Om Narayan

Om Narayan

AI Security Researcher, AWS

Varun Pant

Varun Pant

Engineering and Product Leader, AI applications at the Automated Reasoning Group, AWS

Advait Patel

Advait Patel

Senior Site Reliability Engineer (DevSecOps + Cloud + AIOps), Broadcom, IEEE

Alex Polyakov

Alex Polyakov

CEO, adversa.ai

Ramesh Raskar

Ramesh Raskar

Professor & Director, MIT Media Lab

Ron F. Del Rosario

Ron F. Del Rosario

VP-Head of AI Security, SAP

Tal Shapira

Tal Shapira

Co-Founder & CTO, Reco AI

Akram Sheriff

Akram Sheriff

Senior AI/ML Software Engineering Leader, Cisco

Samantha Siau

Samantha Siau

Security and Compliance, Anthropic

Kevin Simmonds

Kevin Simmonds

Partner on AI Offensive Security, PWC

Martin Stanley

Martin Stanley

NIST AI RMF Lead, Independent

Omar A. Turner

Omar A. Turner

General Manager of Security, Microsoft

Apostol Vassilev

Apostol Vassilev

AI Research Team Supervisor, NIST

Matthew Versaggi

Matthew Versaggi

AI Fellow, White House Presidential Innovation Fellow

David Webb

David Webb

Agency Cybersecurity Officer, Cybersecurity and Infrastructure Security Agency

Dennis Xu

Dennis Xu

Research VP, AI, Gartner

Xiaochen Zhang

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.