DOCSEARCHbyAlgolia
Submit Docs

Claude Skills Documentation

repository·main·Indexed 12 days ago

https://github.com/travisvn/awesome-claude-skills

A curated collection of resources and instructions for creating and using Claude Skills. Learn how to implement a progressive disclosure architecture for repeatable tasks using SKILL.md, manage skills via the Claude.ai web interface, Claude Code CLI, and the /v1/skills API, and utilize the skill-creator tool for automated workflow generation.

Tokens
2K
Snippets
3
Records
13
Agent score
47%

What's inside Claude Skills

  1. Understand Claude Skills token usage and loading

    main

    Skills use a progressive disclosure architecture to remain token-efficient:

    1. Metadata Scanning: Claude scans the name and description in the skill's frontmatter. This uses only ~100 tokens.
    2. Relevance Evaluation: Claude evaluates if the skill is relevant to the current task.
    3. Activation: Only when a skill is deemed relevant is the full content loaded. Activated skills typically load at <5k tokens. Bundled resources are only loaded as needed.

  2. How Claude Skills work

    main

    Claude Skills are specialized folders containing instructions, scripts, and resources that Claude dynamically discovers and loads when relevant to tasks. They use a progressive disclosure architecture to manage context window efficiency:

    1. Metadata loading (~100 tokens): Claude scans available Skills to identify relevant matches.
    2. Full instructions (<5k tokens): Loaded only when Claude determines the Skill applies.
    3. Bundled resources: Files and executable code are loaded only as needed.

  3. Compare Skills vs System Prompts

    main

    Skills offer a more structured and efficient alternative to manual system prompting:

    FeatureSkillsSystem Prompts
    StructureFolder with YAML frontmatter, instructions, scriptsPlain text instructions
    ReusabilityVersion-controlled, shareable, composableCopy-paste, conversation-specific
    LoadingOn-demand (only when relevant)Always in context
    MaintenanceCentralized updatesManual updates per conversation
    ComposabilityMultiple skills stack automaticallyManual combination

  4. Decide when to use Skills vs other Claude features

    main

    Use the following decision matrix to choose the right tool for your task:

    • Skills: Use for reusable, portable procedural knowledge and task-specific workflows that should be accessible across any Claude instance. If you find yourself repeating the same prompt in multiple conversations, create a Skill.
    • Prompts: Use for one-time instructions and immediate context.
    • Projects: Use for persistent background knowledge within specific workspaces.
    • Subagents: Use for independent task execution with specific permissions and restricted tool access. Subagents can leverage Skills for specialized expertise.
    • MCP (Model Context Protocol): Use for connecting Claude to external data sources, databases, or API integrations.

  5. Best practices for Skill creation

    main

    When building Claude Skills, follow these guidelines:

    • 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: Provide specific examples within your SKILL.md.
    • Version your skills: Use git tags for version management.
    • Document dependencies: List any prerequisites or required packages.
    • Test thoroughly: Verify the skill works across different scenarios.

  6. Compare Skills vs MCP (Model Context Protocol)

    main

    While both extend Claude's capabilities, they serve different primary purposes:

    FeatureSkillsMCP
    PurposeTask-specific expertise and workflowsExternal data/API integration
    PortabilitySame format everywhere (Claude.ai, Code, API)Requires server configuration
    Code ExecutionCan include executable scriptsProvides tools/resources
    Token Efficiency30-50 tokens until loadedVaries by implementation
    Best ForRepeatable tasks, document workflowsDatabase access, API integrations

    Pro-tip: You can use them together. Skills can be used to create MCP servers (e.g., using the mcp-builder skill).

  7. Create a Skill using skill-creator

    main

    The recommended way to build a new skill is using the interactive skill-creator tool:

    1. Enable the skill-creator skill in Claude.
    2. Prompt Claude: "Use the skill-creator to help me build a skill for [your task]"
    3. Follow the interactive Q&A to define your workflow.
    4. Claude will generate the complete skill structure for you.

  8. Install Skills in Claude Code CLI

    main

    You can install skills in the Claude Code CLI either from the marketplace or from a local directory using the /plugin command.

    # Install skills from marketplace
/plugin marketplace add anthropics/skills

# Or install from local directory
/plugin add /path/to/skill-directory

  9. Security best practices for Claude Skills

    main

    ⚠️ Warning: Skills can execute arbitrary code. Only install skills from trusted sources.

    Vetting and Auditing

    • Review Files: Always review SKILL.md and all associated scripts before enabling a skill.
    • Data Sensitivity: Be cautious of skills that request access to sensitive data.
    • Audit: Perform careful audits before deploying skills to production or enterprise environments.

    Implementation Best Practices

    • Version Control: Track all skills in git with proper version tags.
    • Code Review: Peer review custom skills before distributing them to a team.
    • Least Privilege: Only grant the minimum necessary permissions and access.
    • Testing: Thoroughly test skills in non-production environments before use.

  10. Manually create a Claude Skill

    main

    To create a skill manually, follow these steps:

    1. Create the 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

    The SKILL.md file must include YAML frontmatter for discovery. The description field is used for skill discovery, so keep it concise.

    ---
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)

    You can include Python, JavaScript, or other scripts that Claude can execute. Reference these scripts within your SKILL.md instructions.

    4. Test and Refine

    Install the skill in Claude Code or Claude Desktop and test it with relevant tasks to iterate on the instructions.

  12. Troubleshoot Skills issues

    main

    Skills not appearing in Claude

    • Check Settings > Capabilities to ensure Skills are enabled.
    • For Team/Enterprise accounts, verify that an admin has enabled Skills organization-wide.
    • Restart Claude after installing new skills.

    Skills not loading or activating

    • Verify that SKILL.md has the correct YAML frontmatter format.
    • Ensure both name and description fields are present in the frontmatter.
    • Confirm the file structure matches the expected format.

    Permission and Execution errors

    • Permissions: Review admin settings for Team/Enterprise accounts and check file permissions in skill directories.
    • Execution Failures: Ensure all script dependencies are installed. Test scripts independently outside of Claude to isolate issues.