Full Report
Claude Skills are becoming bigger and bigger. This article details how to write good Claude skills from people using them internally at Anthropic. They break it down into nine different categories.... library API references, production verification, data/analysis, business automation, scaffolding/templates, code review, CI/CD deployment, incidient runbooks and infrastructure ops. The first tip is to NOT state the obvious. If something is default then Claude already knows it. Skills that improve on Claude's base knowledge, after trial and error, are great. Another item is a basic gotchas section. These are built in common failure points that Claude runs into when using the skill; these should be updated over time. Claude skills aren't just markdown files anymore; they are a folder of information. You can tell Claude what files are in a skill and when to read specific information. This progressive disclosure limits the usage of context while giving Claude all of the information that it needs. Some skills include built-in memory by having log files, JSON files or even a SQLite database. Giving Claude scripts and libraries to use can make it even more powerful. This is great for complex analysis, custom calls that are require and much more. Hooks are code that is always ran at deterministic times. The more deterministic Claude can be with user created code, the better. They also say to be careful about being too prescriptive. Claude is smart and can adapt to many situations. Their example of being too prescriptive is having step by step instructions to complete simple tasks. A good article on using Claude skills more effectively.
Analysis Summary
# Best Practices: Secure Development & Orchestration of Claude Skills
## Overview
These practices address the secure implementation, management, and optimization of "Claude Skills"—customized toolsets and knowledge bases used to extend AI capabilities. The focus is on moving from simple text-based prompts to structured, deterministic, and context-efficient AI agents while maintaining robust security boundaries.
## Key Recommendations
### Immediate Actions
1. **Implement Progressive Disclosure:** Map out your skill’s folder structure. Instruct Claude on which files to read only when specific triggers are met to minimize context window leakage and potential prompt injection surface area.
2. **Audit "Gotchas" Documentation:** Create a `failsafe.md` or similar file within the skill folder documenting known failure points where Claude tends to hallucinate or misinterpret commands.
3. **Minimize Redundancy:** Remove instructions that repeat Claude’s base training (e.g., "be polite") to save tokens and prevent conflicting instruction sets.
### Short-term Improvements (1-3 months)
1. **Deterministic Hook Integration:** Identify repeatable tasks (e.g., code linting, security scanning) and move them into "Hooks"—code that runs at fixed times—rather than relying on Claude to decide when to run them.
2. **Tool/Library Sandboxing:** Provide Claude with verified scripts and libraries for complex analysis rather than letting it generate raw code for critical tasks on the fly.
3. **State Management:** Implement structured logging or local databases (SQLite) within the skill folder to maintain a secure, auditable history of actions and decisions.
### Long-term Strategy (3+ months)
1. **Skills-as-Code Lifecycle:** Treat Claude Skills as infrastructure. Move from markdown files to managed directories with version control (Git), automated CI/CD deployment, and peer code review.
2. **Infrastructure Ops Integration:** Develop skill sets specifically for Incident Runbooks, ensuring Claude has read-access to infrastructure topology but limited, human-in-the-loop write access.
## Implementation Guidance
### For Small Organizations
- Focus on **Scaffolding/Templates**: Create standard templates for common tasks to ensure consistency without high overhead.
- Use **Library API References** to keep Claude grounded in your specific technical stack.
### For Medium Organizations
- Implement **Production Verification** skills: Use Claude to double-check deployments against a set of security requirements.
- Introduce **Code Review** skills that reference internal security standards and business-specific logic.
### For Large Enterprises
- Mandate **CI/CD Deployment** skills that integrate directly with pipeline logs for automated troubleshooting.
- Utilize **Data/Analysis** skills with siloed SQLite databases to ensure data residency and minimize external API calls.
## Configuration Examples
### Deterministic Hook Structure
*Example of a skill manifest directing Claude on file usage:*
json
{
"skill_name": "SecurityAuditor",
"files": {
"api_ref": "docs/api_v1.json",
"security_policy": "policies/owasp_top_10.md",
"failure_logs": "logs/common_errors.log"
},
"hooks": {
"pre_execution": "scripts/check_auth_tokens.py",
"post_execution": "scripts/validate_output_format.py"
}
}
## Compliance Alignment
- **NIST AI RMF:** Aligns with the "Govern" and "Map" functions by documenting known failure points ("Gotchas") and using deterministic hooks.
- **ISO/IEC 42001:** Supports AI management through structured skill folders and library references.
- **CIS Benchmarks:** Applicable through the "Infrastructure Ops" and "CI/CD Deployment" skill categories to ensure Claude-generated infra meets hardened standards.
## Common Pitfalls to Avoid
- **Over-Prescription:** Don't write step-by-step guides for simple tasks. It limits the LLM's reasoning capability and makes the skill brittle to updates.
- **Context Bloat:** Loading all documentation at once increases the risk of the model missing critical security instructions (the "Lost in the Middle" phenomenon).
- **Static "Gotchas":** Failing to update the common failure points relative to real-world performance leads to recurring security/operational errors.
## Resources
- **Anthropic Documentation:** `https://docs.anthropic[.]com`
- **Claude Code Repository:** (Internal enterprise access per organization)
- **OWASP LLM Top 10:** `https://owasp[.]org/www-project-top-10-for-large-language-model-applications/`