# create-skill

> Creates a new Claude Code skill. Use when user asks to create or build a skill for Claude Code.

- Author: Gabe Mahoney
- Repository: gabemahoney/dot-claude
- Version: 20260201085021
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/gabemahoney/dot-claude
- Web: https://mule.run/skillshub/@@gabemahoney/dot-claude~create-skill:20260201085021

---

---
name: create-skill
description: Creates a new Claude Code skill. Use when user asks to create or build a skill for Claude Code.
---

# Creating Claude Code Skills

When a user asks to create a skill, follow this workflow to create a structured instruction file that extends Claude's capabilities.

## 1. Clarify Requirements

Ask if unclear:
- **Scope**: System-wide (all projects) or project-specific?
- **Invocation**: Auto-trigger or manual-only (`/command`)?
- **Arguments**: Will users pass values when invoking (e.g., `/skill-name value`)?

## 2. Determine Storage Location

### System-Wide (Personal)
**Path**: `~/.claude/skills/<skill-name>/SKILL.md`
- Available in all projects
- Use for: general workflows, coding standards, domain expertise

### Project-Specific
**Path**: `.claude/skills/<skill-name>/SKILL.md` (in project root)
- Only available in current project
- Use for: project conventions, deployment workflows, team processes
- Commit to version control

## 3. Name Convention

Format: lowercase with hyphens, max 64 chars
Examples: `explain-code`, `fix-bug`, `deploy-staging`, `review-pr`

## 4. Create SKILL.md Structure

### Minimal Template
```yaml
---
name: skill-name
description: Clear description with keywords matching how users naturally ask for this.
---

# Instructions

Step-by-step instructions for Claude to follow when invoked.

1. First step with clear actions
2. Second step
3. Final step
```

### Common Frontmatter Options
```yaml
---
name: skill-name
description: When to use this skill

# Optional: prevent Claude from auto-invoking (defaults to false, meaning Claude CAN auto-invoke)
disable-model-invocation: true

# Optional: hide from user menus (defaults to true, meaning users CAN manually invoke)
user-invocable: false

# Optional: restrict which tools are available when skill runs
allowed-tools: [Read, Grep, Glob]

# Optional: run in isolated subagent environment
context: fork
agent: Explore
---
```

## 5. Handle Arguments

Use placeholders in instructions:
- `$ARGUMENTS` - all args
- `$1`, `$2`, etc. - specific args
- `!backtick command` - inject shell output

Example:
```markdown
---
name: fix-issue
---
Fix GitHub issue #$1:
1. View issue: !\`gh issue view $1\`
2. Implement fix
3. Create PR
```

## 6. Choose Skill Type

**Task Skill** (workflows with steps):
- Set `disable-model-invocation: true` if it has side effects (deploy, commit)
- Provide clear step-by-step instructions

**Reference Skill** (conventions/guidelines):
- Set `user-invocable: false` (Claude reads, doesn't show in menus)
- Document standards, not workflows

## 7. Creation Process

```bash
# System-wide
mkdir -p ~/.claude/skills/<skill-name>
# Create SKILL.md at ~/.claude/skills/<skill-name>/SKILL.md

# Project-specific
mkdir -p .claude/skills/<skill-name>
# Create SKILL.md at .claude/skills/<skill-name>/SKILL.md
```

## Best Practices

- Keep under 500 lines (use supporting files if needed)
- Use specific keywords in description for auto-triggering
- Prefer task-oriented instructions over explanations
- Test with direct invocation first: `/skill-name`
- Side-effect commands (deploy, commit): add `disable-model-invocation: true`
- Add a "Your Context" section at the start:
  - If skill runs as main agent (user-invocable or invoked via Skill tool): "**You are a main agent.**"
  - If skill runs as subagent (launched via Task tool): "**You are a subagent.**"
  - CLAUDE.md contains all communication guidelines for agents and subagents

## Quick Examples

**Deployment workflow:**
```yaml
---
name: deploy-prod
description: Deploy to production environment
disable-model-invocation: true
---
1. Run tests: `npm test`
2. Build: `npm run build`
3. Deploy: `./deploy.sh prod`
4. Verify and notify team
```

**Coding conventions:**
```yaml
---
name: python-style
description: Python coding standards
user-invocable: false
---
- Use poetry for dependencies
- Type hints for public functions
- Max line length: 100
- Run: `poetry run pytest`
```

## Troubleshooting

- **Not auto-triggering**: Make description more specific
- **Triggers too often**: Narrow description or add `disable-model-invocation: true`
- **Not in menus**: Check `user-invocable: false` or file name is exactly `SKILL.md`