Skills for enterprise

This guide is for enterprise admins and architects who need to govern Agent Skills across an organization. It covers how to vet, evaluate, deploy, and manage Skills at scale. For authoring guidance, see best practices. For architecture details, see the Skills overview.

Security review and vetting

Deploying Skills in an enterprise requires answering two distinct questions:

1. Are Skills safe in general? See the security considerations section in the overview for platform-level security details.
2. How do I vet a specific Skill? Use the risk assessment and review checklist below.

Risk tier assessment

Evaluate each Skill against these risk indicators before approving deployment:

Review checklist

Before deploying any Skill from a third party or internal contributor, complete these steps:

1. Read all Skill directory content. Review SKILL.md, all referenced markdown files, and any bundled scripts or resources.
2. Verify script behavior matches stated purpose. Run scripts in a sandboxed environment and confirm outputs align with the Skill's description.
3. Check for adversarial instructions. Look for directives that tell Claude to ignore safety rules, hide actions from users, exfiltrate data through responses, or alter behavior based on specific inputs.
4. Check for external URL fetches or network calls. Search scripts and instructions for network access patterns (http, requests.get, urllib, curl, fetch).
5. Verify no hardcoded credentials. Check for API keys, tokens, or passwords in Skill files. Credentials should use environment variables or secure credential stores, never appear in Skill content.
6. Identify tools and commands the Skill instructs Claude to invoke. List all bash commands, file operations, and tool references. Consider the combined risk when a Skill uses both file-read and network tools together.
7. Confirm redirect destinations. If the Skill references external URLs, verify they point to expected domains.
8. Verify no data exfiltration patterns. Look for instructions that read sensitive data and then write, send, or encode it for external transmission, including through Claude's conversational responses.

Evaluating Skills before deployment

Skills can degrade agent performance if they trigger incorrectly, conflict with other Skills, or provide poor instructions. Require evaluation before any production deployment.

What to evaluate

Establish approval gates for these dimensions before deploying any Skill:

Evaluation requirements

Require Skill authors to submit evaluation suites with 3-5 representative queries per Skill, covering cases where the Skill should trigger, should not trigger, and ambiguous edge cases. Require testing across the models your organization uses (Haiku, Sonnet, Opus), since Skill effectiveness varies by model.

For detailed guidance on building evaluations, see evaluation and iteration in best practices. For general evaluation methodology, see develop test cases.

Using evaluations for lifecycle decisions

Evaluation results signal when to act:

• Declining trigger accuracy: Update the Skill's description or instructions
• Coexistence conflicts: Consolidate overlapping Skills or narrow descriptions
• Consistently low output quality: Rewrite instructions or add validation steps
• Persistent failures across updates: Deprecate the Skill

Skill lifecycle management

Organizing Skills at scale

Recall limits

As a general guideline, limit the number of Skills loaded simultaneously to maintain reliable recall accuracy. Each Skill's metadata (name and description) competes for attention in the system prompt. With too many Skills active, Claude may fail to select the right Skill or miss relevant ones entirely. Use your evaluation suite to measure recall accuracy as you add Skills, and stop adding when performance degrades.

Note that API requests support a maximum of 8 Skills per request (see Using Skills with the API). If a role requires more Skills than a single request supports, consider consolidating narrow Skills into broader ones or routing requests to different Skill sets based on task type.

Start specific, consolidate later

Encourage teams to start with narrow, workflow-specific Skills rather than broad, multi-purpose ones. As patterns emerge across your organization, consolidate related Skills into role-based bundles.

Example progression:

• Start: formatting-sales-reports, querying-pipeline-data, updating-crm-records
• Consolidate: sales-operations (when evals confirm equivalent performance)

Naming and cataloging

Use consistent naming conventions across your organization. The naming conventions section in best practices provides formatting guidance.

Maintain an internal registry for each Skill with:

• Purpose: What workflow the Skill supports
• Owner: Team or individual responsible for maintenance
• Version: Current deployed version
• Dependencies: MCP servers, packages, or external services required
• Evaluation status: Last evaluation date and results

Role-based bundles

Group Skills by organizational role to keep each user's active Skill set focused:

• Sales team: CRM operations, pipeline reporting, proposal generation
• Engineering: Code review, deployment workflows, incident response
• Finance: Report generation, data validation, audit preparation

Each role-based bundle should contain only the Skills relevant to that role's daily workflows.

Distribution and version control

Source control

Store Skill directories in Git for history tracking, code review via pull requests, and rollback capability. Each Skill directory (containing SKILL.md and any bundled files) maps naturally to a Git-tracked folder.

API-based distribution

The Skills API provides workspace-scoped distribution. Skills uploaded via the API are available to all workspace members. See Using Skills with the API for upload, versioning, and management endpoints.

Versioning strategy

• Production: Pin Skills to specific versions. Run the full evaluation suite before promoting a new version. Treat every update as a new deployment requiring full security review.
• Development and testing: Use latest versions to validate changes before production promotion.
• Rollback plan: Maintain the previous version as a fallback. If a new version fails evaluations in production, revert to the last known-good version immediately.
• Integrity verification: Compute checksums of reviewed Skills and verify them at deployment time. Use signed commits in your Skill repository to ensure provenance.

Cross-surface considerations

Maintain Skill source files in Git as the single source of truth. If your organization deploys Skills across multiple surfaces, implement your own synchronization process to keep them consistent. For full details, see cross-surface availability.

Next steps