Skip to content
Claude Kit

Creating Skills

Creating Skills

Section titled “Creating Skills”

Skills are the core building block of Claude Kit. You can create custom skills for your project’s specific patterns, frameworks, or workflows.

Skill Structure

Section titled “Skill Structure”

Plugin skills live in the skills/ directory at the plugin root. For project-specific skills, create them in .claude/skills/:

.claude/skills/
└── my-skill/
    ├── SKILL.md           # Skill definition (required)
    └── resources/         # Optional bundled references
        ├── patterns.md
        └── examples.md

SKILL.md Format

Section titled “SKILL.md Format”
---
name: my-skill
description: Use when [trigger conditions]. Activate for keywords like
  "keyword1", "keyword2". Also trigger when [specific scenarios].
---


# My Skill


## When to Use
- [Scenario 1]
- [Scenario 2]


## When NOT to Use
- [Anti-scenario 1]


---


## Core Patterns


### Pattern 1: [Name]


[Explanation]


\`\`\`typescript
// Code example
\`\`\`


### Pattern 2: [Name]


[Explanation]


## Best Practices


- [Practice 1]
- [Practice 2]


## Common Pitfalls


- [Pitfall 1]
- [Pitfall 2]

Frontmatter Fields

Section titled “Frontmatter Fields”
FieldRequiredDescription
nameYesSkill identifier (kebab-case)
descriptionYesTrigger description — Claude reads this to decide when to activate
argument-hintNoHint for user-invocable skills (e.g., <topic>)
user-invocableNoIf true, users can invoke with /skill-name
disable-model-invocationNoIf true, only manual invocation works

Writing Effective Descriptions

Section titled “Writing Effective Descriptions”

The description field is critical — it determines when Claude activates your skill. Include:

  1. Primary trigger: “Use when [main scenario]”
  2. Keywords: “Activate for keywords like X, Y, Z”
  3. Secondary triggers: “Also trigger when [less obvious scenarios]“

Good Description

Section titled “Good Description”
description: Use when implementing JWT tokens, OAuth2 flows, session
  management, or role-based access control. Activate for keywords like
  "login", "signup", "token refresh", "protected routes". Also trigger
  when code handles password hashing or API key authentication.

Bad Description

Section titled “Bad Description”
description: Authentication skill for handling auth stuff.

Bundled Resources

Section titled “Bundled Resources”

For complex skills, include reference documents in a resources/ subdirectory:

my-framework/
├── SKILL.md
└── resources/
    ├── api-reference.md      # Framework API docs
    ├── migration-guide.md    # Version migration patterns
    └── examples.md           # Code examples

Reference them from SKILL.md:

See `resources/api-reference.md` for the full API surface.

Skill Types

Section titled “Skill Types”

Rigid Skills

Section titled “Rigid Skills”

Follow exactly — no adaptation. Used for methodologies where discipline matters:

  • TDD (red-green-refactor cycle)
  • Systematic debugging (four-phase investigation)
  • Verification before completion

Flexible Skills

Section titled “Flexible Skills”

Adapt principles to context. Used for patterns that vary by project:

  • Language idioms
  • Framework patterns
  • Architecture guidelines

Example: Custom Deployment Skill

Section titled “Example: Custom Deployment Skill”
---
name: deploy-to-fly
description: Use when deploying to Fly.io or configuring Fly.io
  services. Activate for keywords like "fly deploy", "fly.toml",
  "Fly.io", "fly machines", or any Fly.io-specific configuration.
---


# Deploy to Fly.io


## When to Use
- Deploying applications to Fly.io
- Configuring fly.toml
- Setting up Fly.io machines or volumes


## When NOT to Use
- Deploying to other platforms (use devops skill instead)


---


## Deployment Checklist


1. Verify `fly.toml` exists and is configured
2. Check environment secrets are set: `fly secrets list`
3. Deploy: `fly deploy --strategy rolling`
4. Verify: `fly status` and `fly logs`


## Common Patterns


### Multi-region deployment


\`\`\`toml
[env]
  PRIMARY_REGION = "iad"


[[services]]
  internal_port = 8080
  protocol = "tcp"
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 1
\`\`\`

Tips

Section titled “Tips”
  • Start small: Begin with the core patterns, add detail as you learn what Claude needs
  • Be specific: Vague skills produce vague results. Include exact code patterns.
  • Test the trigger: After creating a skill, test that it activates on the right keywords
  • Update regularly: Skills should evolve with your codebase
Section titled “Related Pages”