Create Skill

About Skills

Skills extend Claude's capabilities with specialized workflows, tool integrations, domain expertise, and bundled resources. See references/skill_anatomy.md for detailed structure.

Key structure: SKILL.md (required) + optional scripts/, references/, assets/ directories.

YAML Frontmatter Reference

See references/frontmatter_reference.md for the complete field reference table. Key fields:

• •name: Lowercase, hyphens only (max 64 chars). No reserved words (anthropic, claude). Noun or short-phrase form preferred (pdf, changelog, smart-merge).
• •description: Third-person verb + triggers (max 1024 chars)
• •context: fork: Required for task-based skills. Ensures fresh context, subagent access, and prevents pollution between invocations.

Research $ARGUMENTS thoroughly:

1. •Find relevant files using Glob and Grep
2. •Read and analyze the code
3. •Summarize findings with specific file references

When invoked as `/deep-research authentication flow`, `$ARGUMENTS` becomes `authentication flow`.
</example>

<example>
**Side-effect skill requiring explicit invocation:**
```yaml
---
name: deploy-staging
description: "Deploys the current branch to the staging environment. Use when users request deployment or staging preview."
context: fork
disable-model-invocation: true
---

disable-model-invocation: true prevents auto-invocation. The user must run /deploy-staging explicitly. </example>

See references/frontmatter_reference.md for additional examples (inline reference skills, medium-freedom skills with tool restrictions).

Invocation Control

See references/frontmatter_reference.md for the full invocation control matrix. Key rule: add context: fork to any task-based skill so subagents can access it.

Bundled Resources

See references/bundled_resources.md for guidance on scripts/, references/, and assets/ directories. For public distribution, use relative paths only -- no absolute paths, personal info, or version numbers.

Best Practices

Read references/anthropic_best_practices_summary.md before creating or updating skills. For complete official documentation: Anthropic Best Practices

Edit Skills at Source Location

Do not edit skills in ~/.claude/plugins/cache/ -- changes are lost on cache refresh. Before any edit, confirm the file path does not contain /cache/ or /plugins/cache/. Always edit the source repository copy.

Skill Creation Process

User input: $ARGUMENTS

If $ARGUMENTS is non-empty, extract the skill name and purpose from it. Skip Step 1 and proceed to Step 2. Only ask clarifying questions if the skill's purpose is entirely unclear.

If $ARGUMENTS is empty, begin at Step 1.

To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable.

Step 1: Understanding the Skill with Concrete Examples

Skip this step when: the user has already described what the skill should do (via arguments or prior context).

When the skill's usage patterns are not yet clear, gather concrete examples of how it will be used. Start with the most important question and follow up as needed:

• •"What functionality should the skill support?"
• •"Can you give examples of how it would be used?"
• •"What would a user say that should trigger this skill?"

Conclude this step when there is a clear sense of the functionality the skill should support.

Step 2: Planning the Reusable Skill Contents

To turn concrete examples into an effective skill, analyze each example by:

1. •Considering how to execute on the example from scratch
2. •Determining the appropriate level of freedom for Claude
3. •Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly

Match specificity to task risk:

• •High freedom (text instructions): Multiple valid approaches exist; context determines best path (e.g., code reviews, troubleshooting, content analysis)
• •Medium freedom (pseudocode with parameters): Preferred patterns exist with acceptable variation (e.g., API integration patterns, data processing workflows)
• •Low freedom (exact scripts): Operations are fragile, consistency critical, sequence matters (e.g., PDF rotation, database migrations, form validation)

See references/planning_examples.md for detailed examples (pdf-editor, frontend-webapp-builder, big-query skills).

Analyze each concrete example to create a list of reusable resources: scripts, references, and assets.

Step 3: Initializing the Skill

At this point, it is time to actually create the skill.

Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.

When creating a new skill from scratch, run init_skill.py to generate a complete template:

python3 scripts/init_skill.py <skill-name> --path <output-directory>

The script creates a skill directory with SKILL.md, frontmatter, resource directories, and example files. Customize or remove the generated files as needed.

Step 4: Edit the Skill

When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.

Start with Reusable Skill Contents

To begin implementation, start with the reusable resources identified above: scripts/, references/, and assets/ files. Note that this step may require user input. For example, when implementing a brand-guidelines skill, the user may need to provide brand assets or templates to store in assets/, or documentation to store in references/.

Also, delete any example files and directories not needed for the skill. The initialization script creates example files in scripts/, references/, and assets/ to demonstrate structure, but most skills won't need all of them.

When updating an existing skill: Scan all existing reference files to check if they need corresponding updates. New features often require updates to architecture, workflow, or other existing documentation to maintain consistency.

Reference File Naming

Filenames must be self-explanatory without reading contents.

Pattern: <content-type>_<specificity>.md

Examples:

• •Bad: commands.md, cli_usage.md, reference.md
• •Good: script_parameters.md, api_endpoints.md, database_schema.md

Test: Can someone understand the file's contents from the name alone?

Update SKILL.md

Writing Style: Write the entire skill using imperative/infinitive form (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption.

To complete SKILL.md, answer the following questions:

1. •What is the purpose of the skill, in a few sentences?
2. •When should the skill be used?
3. •In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them.

Use <example> blocks around concrete examples to help Claude distinguish examples from instructions.

Consistency Verification

Before finalizing, check for contradictions:

1. •Search SKILL.md for each decision or rule. Verify the same rule does not appear with different values elsewhere.
2. •For each term used more than twice, confirm the same word refers to the same concept throughout (e.g., do not mix "user" and "customer" for the same entity).
3. •For each reference file mentioned in SKILL.md, open it and confirm the guidance aligns with what SKILL.md states.

Step 5: Sanitization Review (Optional)

Ask the user before executing this step: "This skill appears to be extracted from a business project. Would you like me to perform a sanitization review to remove business-specific content before public distribution?"

Skip this step if:

• •The skill was created from scratch for public use
• •The user explicitly declines sanitization
• •The skill is intended for internal/private use only

When to perform sanitization:

• •Skill was extracted from a business/internal project
• •Skill contains domain-specific examples from real systems
• •Skill will be distributed publicly or to other teams

Sanitization process (detailed in references/sanitization_checklist.md):

1. •Run the automated grep scans from the checklist against the skill folder
2. •Review each match and apply the category-specific replacements
3. •Re-run all scan patterns to confirm no matches remain
4. •Read through the skill to verify coherence and functionality

Step 6: Security Review

Before packaging or distributing a skill, run the security scanner:

python3 scripts/security_scan.py <path/to/skill-folder>           # Quick scan (required)
python3 scripts/security_scan.py <path/to/skill-folder> --verbose  # Detailed review

Install gitleaks first if not present (brew install gitleaks on macOS). The script prints installation instructions and remediation guidance for any issues found.

Step 7: Packaging a Skill

Package the skill into a distributable zip. The script validates before packaging:

python3 scripts/package_skill.py <path/to/skill-folder>            # Output to current dir
python3 scripts/package_skill.py <path/to/skill-folder> ./dist      # Output to ./dist

The packaging script will:

1. •

   Validate the skill automatically, checking:

   • •YAML frontmatter format and required fields
   • •Skill naming conventions and directory structure
   • •Description completeness and quality
   • •Path reference integrity - all scripts/, references/, and assets/ paths mentioned in SKILL.md must exist
2. •

   Package the skill if validation passes, creating a zip file named after the skill (e.g., my-skill.zip) that includes all files and maintains the proper directory structure for distribution.

Common validation failure: If SKILL.md references scripts/my_script.py but the file doesn't exist, validation will fail with "Missing referenced files: scripts/my_script.py". Ensure all bundled resources exist before packaging.

If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.

Step 8: Update Marketplace

After packaging, update the marketplace registry so the skill is discoverable. Read references/marketplace_update.md for the JSON template and semver versioning rules.

Step 9: Iterate

After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.

Iteration workflow:

1. •Use the skill on a real task and record where Claude hesitates, asks unnecessary questions, or produces incorrect output.
2. •For each observed failure, trace back to the responsible section in SKILL.md or a reference file.
3. •Apply the fix: add missing context, tighten vague instructions, or add an example covering the failure case.
4. •Re-run the same task to verify the fix resolved the issue.

Refinement filter: Only add what solves observed problems. If best practices already cover it, do not duplicate.

End-to-End Example

Step 1: Skipped -- purpose is clear from the name.

Step 2 (Planning): Brand guidelines are reference content (high freedom). Resources needed:

• •references/color_palette.md -- hex codes, usage rules
• •references/typography.md -- font families, sizes, hierarchy
• •assets/logo.png -- brand logo file

Step 3 (Init):

python3 scripts/init_skill.py brand-guidelines --path skills/

Step 4 (Edit): Write SKILL.md with:

---
name: brand-guidelines
description: "Applies brand identity standards to UI components, documents, and presentations. Use when creating user-facing output, choosing colours, or selecting typography."
license: MIT
---

Body references references/color_palette.md and references/typography.md. Asks user to provide the logo file for assets/.

Step 5: Skipped -- created from scratch for public use.

Steps 6-8: Run security scan, package, update marketplace. </example>