How to Develop Claude Skills for Enterprise Compliance and Security

Develop enterprise-grade Claude Skills by combining the Composio skill-creation framework with MCP security best practices, implementing progressive disclosure through lean SKILL.md files, secure tool annotations, environment-based secrets, and structured audit logging.

Enterprise deployment of AI assistants requires strict adherence to compliance frameworks and security protocols. The ComposioHQ/awesome-claude-skills repository provides a structured architecture for building Claude Skills that meet these stringent requirements through the Model Context Protocol (MCP) server guidelines and resource partitioning strategies defined in the codebase.

Understanding the Skill Architecture and Progressive Disclosure

A production-ready Claude Skill resides in a dedicated folder with a specific structure designed to minimize token consumption while maintaining access to heavyweight compliance artifacts. According to skill-creator/SKILL.md, the mandatory SKILL.md file serves as the entry point using a three-level loading system: the first ~100 words (metadata), the full markdown body (≤ 5,000 words) when triggered, and bundled resources loaded only on demand.

The standard directory structure follows this pattern:

skill-name/
├── SKILL.md          # Required metadata & high-level workflow

├── scripts/          # Deterministic code (e.g., PDF rotator)

├── references/       # Policy docs, schemas, compliance checklists

└── assets/           # Templates, icons, fonts used in outputs

This progressive disclosure design principle ensures that sensitive compliance documents stored in references/ do not pollute the context window until explicitly needed, reducing both token costs and exposure surface area.

Implementing Secure Tool Design with MCP Annotations

All executable actions exposed to Claude are defined as MCP tools. The mcp-builder/reference/mcp_best_practices.md file mandates specific naming conventions and annotations to make security intent explicit for both the model and human auditors.

Tool naming conventions require:

• snake_case with a service prefix (e.g., salesforce_create_record)
• Verb-first structure using create, list, update, or delete
• Explicit annotations describing side effects via readOnlyHint, destructiveHint, idempotentHint, and openWorldHint

Here is a compliant tool implementation using FastMCP:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("salesforce_compliance")

@mcp.tool(
    annotations={
        "title": "Create Salesforce Record",
        "readOnlyHint": False,
        "destructiveHint": False,
        "idempotentHint": False,
        "openWorldHint": True,
    }
)
async def salesforce_create_record(
    object_type: str,
    data: dict,
) -> str:
    """
    Create a new record in Salesforce.
    - Validates `object_type` against an allowed whitelist.
    - Sanitizes all string fields to prevent injection.
    - Uses the `SALESFORCE_API_KEY` environment variable for auth.
    """
    # Whitelist validation prevents unauthorized object creation

    allowed = {"Account", "Contact", "Opportunity"}
    if object_type not in allowed:
        raise ValueError("Disallowed object type")

    # Secure credential retrieval from environment

    import os, requests
    token = os.getenv("SALESFORCE_API_KEY")
    if not token:
        raise RuntimeError("Missing API key")

    resp = requests.post(
        f"https://api.salesforce.com/v1/{object_type.lower()}",
        json=data,
        headers={"Authorization": f"Bearer {token}"},
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()["id"]

Enforcing Input Validation and Access Control

Enterprise security requires rigorous input validation before any tool execution. The MCP best practices mandate schema-driven validation using Pydantic or Zod, plus sanitization of file system access to reject path traversal attacks like ../.

Critical security measures include:

• Parameter schema validation against JSON schemas defined in references/
• Path sanitization to prevent unauthorized file system access
• Environment-based secrets management using process.env.API_KEY or similar variables, never hard-coded credentials

The example above demonstrates whitelist validation for object_type and secure retrieval of the SALESFORCE_API_KEY environment variable, following the enterprise pattern of never embedding credentials in source code.

Managing Compliance Documentation in the references/ Directory

Enterprise compliance requires maintaining up-to-date policies (GDPR, HIPAA, internal data-handling rules) without overwhelming the model context. Store these as markdown files under references/ and load them only when specific validation steps require enforcement.

Example compliance file structure:

references/
├── gdpr_policy.md
├── hipaa_requirements.md
└── internal_security_guidelines.md

Reference these policies within SKILL.md using conditional loading:

---
name: salesforce-compliance
description: >
  Handles Salesforce record creation while enforcing enterprise data-handling
  policies such as GDPR and internal security guidelines.
---

## Workflow

1. Load `references/gdpr_policy.md` to verify that data fields do not contain personal
   identifiers unless explicitly permitted.
2. Call the `salesforce_create_record` tool defined in `scripts/`.
3. Log the operation with user ID and sanitized payload.
4. Return the newly created record ID.

This approach ensures that heavyweight compliance artifacts remain outside the active context until the specific workflow step requiring policy verification is reached.

Building Audit Trails and Rate Limiting

All enterprise tools must emit structured logs to secure logging sinks. The MCP best practices specify an audit-trail pattern requiring:

• Tool name and caller identity logging
• Input parameter recording (with PII redaction as needed)
• Outcome status and timestamp capture
• Rate limiting per-user or per-API key to prevent abuse

Implement the audit logging function as follows:

import json, os
from datetime import datetime

def audit_log(tool_name, user_id, params, result):
    log_entry = {
        "timestamp": datetime.utcnow().isoformat() + "Z",
        "tool": tool_name,
        "user": user_id,
        "params": params,          # Redact PII before logging

        "result": result,
        "environment": os.getenv("DEPLOYMENT_ENV", "dev")
    }
    # Send to secure logger (CloudWatch, Splunk, etc.)

    print(json.dumps(log_entry))  # Replace with production logger

# Insert at the end of each tool implementation

audit_log("salesforce_create_record", user_id, sanitized_params, record_id)

Packaging and Validating Enterprise-Ready Skills

Before distribution, validate your skill using scripts/package_skill.py. This script checks:

• YAML front-matter completeness in SKILL.md
• Directory structure compliance (SKILL.md, scripts/, references/, assets/)
• Presence of security annotations on each tool

Initialize a new skill using the repository's bootstrap script:

# From the repository root:

python scripts/init_skill.py salesforce-compliance --path ./skills

This creates a skeleton directory with placeholder references/ and scripts/ subdirectories, ensuring your enterprise skill starts with the correct compliance-ready structure.

Summary

• Progressive disclosure via the three-level loading system in SKILL.md keeps token consumption low while providing access to heavy compliance documents stored in references/.
• Secure MCP tool design requires snake_case naming with service prefixes, verb-first structure, and explicit annotations (destructiveHint, readOnlyHint) as defined in mcp-builder/reference/mcp_best_practices.md.
• Environment-safe secrets management mandates using os.getenv() or process.env for API keys, never hard-coding credentials in scripts.
• Input validation must include whitelist checking, schema validation, and path traversal prevention before executing any business logic.
• Audit logging requires structured JSON output with timestamps, user IDs, and redacted parameters sent to secure logging sinks.
• Packaging validation through scripts/package_skill.py ensures compliance metadata and directory structure meet enterprise standards before deployment.

Frequently Asked Questions

What is progressive disclosure in Claude Skills?

Progressive disclosure is an architectural pattern defined in skill-creator/SKILL.md that loads skill resources in three stages: metadata (~100 words), full instructions (≤ 5,000 words), and on-demand references. This prevents sensitive compliance documents from occupying the context window until explicitly required by the workflow, reducing both token costs and data exposure.

How should enterprises handle secrets in Claude Skills?

Enterprises must never embed credentials in code. Instead, use environment variables (e.g., SALESFORCE_API_KEY) accessed via os.getenv() in Python or process.env in Node.js, with placeholder entries in .env files. The mcp-builder/reference/mcp_best_practices.md file explicitly prohibits hard-coded secrets and recommends validation that environment variables exist before tool execution.

Why are MCP tool annotations important for compliance?

MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) provide machine-readable metadata about side effects, enabling automated compliance checking and human audit reviews. According to the MCP best practices, these annotations help security teams quickly assess whether a tool might violate data-handling policies without reading the full implementation code.

How do you validate a Claude Skill before enterprise deployment?

Run scripts/package_skill.py to validate YAML front-matter completeness, verify the required directory structure (SKILL.md, scripts/, references/), and confirm that all tools include security annotations. This packaging script ensures the skill meets the structural and metadata requirements necessary for the Claude Skills marketplace and enterprise governance standards.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}