Method 1: Use skill-creator (Recommended)

The easiest way to create a skill is to use the built-in skill-creator:

1. Enable the skill-creator skill in Claude
2. Ask Claude: "Use the skill-creator to help me build a skill for [your task]"
3. Answer the interactive questions about your workflow
4. Claude generates the complete skill structure for you

Method 2: Manual Creation

1. Create folder structure:

   my-skill/
   ├── SKILL.md          # Main skill file with frontmatter
   ├── scripts/          # Optional executable scripts
   │   └── helper.py
   └── resources/        # Optional supporting files
       └── template.json
   

2. Create SKILL.md with frontmatter:

   ---
   name: my-skill
   description: Brief description for skill discovery (keep concise)
   ---
   
   # Detailed Instructions
   
   Claude will read these instructions when the skill is activated.
   
   ## Usage
   Explain how to use this skill...
   
   ## Examples
   Provide clear examples...
   

3. Add executable scripts (optional):

   • Python, JavaScript, or other scripts Claude can execute
   • Reference them in your SKILL.md instructions

4. Test locally:

   • Install the skill in Claude Code or Claude Desktop
   • Test with relevant tasks
   • Iterate and refine

5. Share:

   • Publish to GitHub
   • Submit to this awesome list via PR
   • Share with your team via git repos or internal distribution

Best Practices

• Keep descriptions concise - The frontmatter description is used for skill discovery
• Use clear, actionable instructions - Write instructions as if for a human collaborator
• Include examples - Show specific examples in your SKILL.md
• Version your skills - Use git tags for version management
• Document dependencies - List any prerequisites or required packages
• Test thoroughly - Verify your skill works across different scenarios

• Getting started with Claude Skills
• Building your first custom skill
• Skills vs MCP comparison
• Enterprise deployment strategies

Vetting Skills

• Only install skills from trusted sources
• Review SKILL.md and all scripts before enabling a skill
• Be cautious of skills that request sensitive data access
• Audit carefully before deploying to production or enterprise environments

Security Concerns

• Malicious skills may introduce vulnerabilities or enable data exfiltration
• Prompt injection attacks could be amplified through compromised skills
• Sandboxing limitations - Understand the security model before enterprise deployment
• Security research: Weaponizing Claude Code Skills - Analysis of potential security risks

Best Practices

• Version control - Track all skills in git with proper version tags
• Code review - Peer review custom skills before team distribution
• Least privilege - Only grant necessary permissions and access
• Regular audits - Periodically review installed skills
• Documentation - Maintain clear documentation for custom skills
• Testing - Thoroughly test skills in non-production environments first

Enterprise Considerations

• As of October 2025, Claude.ai does not support centralized admin management for custom skills
• Use version control and internal repositories for team skill distribution
• Establish clear policies for skill vetting and approval
• Monitor skill usage and performance

Known Issues

• Linux path bug (Oct 18, 2025): Agent SDK uses hardcoded macOS paths instead of environment home directory

  • Issue #268
  • Workaround: Manually specify skill paths

• Enterprise distribution: No centralized admin management yet for custom skills on claude.ai

  • Use git repositories for team distribution
  • API integration provides more control

Common Problems

Skills not appearing in Claude

• Check Settings > Capabilities to ensure Skills are enabled
• For Team/Enterprise: Verify admin has enabled Skills organization-wide
• Restart Claude after installing new skills

Skills not loading/activating

• Verify SKILL.md has proper YAML frontmatter format
• Check that name and description fields are present
• Ensure file structure matches expected format

Permission errors

• Review admin settings for Team/Enterprise accounts
• Check file permissions in skill directories
• Verify API key has appropriate permissions

Skill execution failures

• Check script dependencies are installed
• Review error logs for specific issues
• Test scripts independently outside of Claude

Getting Help

• Official Skills Repository Issues
• Claude Documentation
• Community Discussions

Q: How much do skills impact token usage?

A: Skills are highly efficient thanks to progressive disclosure. Each skill uses only ~100 tokens during metadata scanning to determine relevance. When activated, the full skill content loads at <5k tokens. Bundled resources only load as needed.

Q: What's the difference between Claude Skills and Agent Skills?

A: They are the same thing.

Q: Can I share skills with my team?

A: Yes! Skills can be shared via:

• Git repositories (recommended)
• Internal file sharing
• Claude API for programmatic distribution
• Enterprise-wide deployment features (coming soon)

Q: Do skills work with all Claude models?

A: Skills are available for Pro, Max, Team, and Enterprise users. Free tier users do not have access to Skills.

Q: Can skills call external APIs?

A: Yes, skills can include scripts that call external APIs. For complex API integrations, consider using MCP (Model Context Protocol) alongside skills.

Q: How does Claude decide which skill to use?

A: Claude scans all available skills' frontmatter (name and description), evaluates relevance to the current task, then loads the full content of relevant skills. Multiple skills can be loaded and composed together automatically.

Q: Can I use Skills and MCP together?

A: Absolutely! They complement each other. Use Skills for task-specific workflows and MCP for external data/API integration. The mcp-builder skill can even help you build MCP servers.

Q: Are there any costs beyond my Claude subscription?

A: No additional costs for using official skills. Community and custom skills are free to use, though some may require external services (APIs, databases, etc.) that have their own costs.

Q: Can I monetize custom skills?

A: Currently, there is no official marketplace for paid skills. Anthropic has mentioned plans for community contributions and a potential marketplace in the future.

Q: How do I update a skill?

A: For skills from git repositories, pull the latest changes. For manually installed skills, replace the skill folder with the updated version. Always test updates in a non-production environment first.