Tweak Existing Skill
Workflow
Step 1: Identify the skill
Find skills at:
- •
~/.claude/skills/<name>/SKILL.md(personal) - •
.claude/skills/<name>/SKILL.md(project)
Read the SKILL.md and any referenced files (scripts/, references/, assets/).
Step 2: Diagnose the issue
Common problems and fixes:
| Problem | Likely Cause | Fix |
|---|---|---|
| Skill not triggering | Poor description | Rewrite with clear trigger keywords and scenarios |
| Skill triggers too often | Description too broad | Make description more specific; add disable-model-invocation: true for manual-only |
| Skill not visible | Exceeds character budget | Run /context to check; shorten description or increase SLASH_COMMAND_TOOL_CHAR_BUDGET |
| Wrong agent used in fork | agent: field incorrect | Change to correct agent name |
| Forked skill lacks context | Missing instructions | Skill content IS the prompt in fork mode - make it self-contained |
| Script fails | Bug or environment issue | Read and test the script |
Step 3: Apply changes
Frontmatter fields reference:
| Field | Description |
|---|---|
name | Skill name (lowercase, hyphens, max 64 chars) |
description | What it does + when to use. Primary trigger mechanism |
disable-model-invocation | true = manual only via /skill-name |
user-invocable | false = hidden from / menu, Claude can still auto-invoke |
argument-hint | Hint in autocomplete (e.g., [filename]) |
allowed-tools | Tools allowed without permission when active |
model | Model override when active |
context | fork = run in isolated subagent context |
agent | Agent type for fork: Explore, Plan, general-purpose, or custom agent name |
hooks | Lifecycle hooks |
Substitution variables: $ARGUMENTS, $0, $1, ${CLAUDE_SESSION_ID}
Dynamic injection: !`shell command` runs before skill content is sent to Claude.
Step 4: Verify
After editing:
- •YAML frontmatter parses without errors
- •Description matches intended trigger scenarios
- •Referenced files (scripts, references) exist and are correct
- •For forked skills: content is self-contained (no conversation history available)
- •SKILL.md body stays under 500 lines
Progressive Disclosure Reminder
If SKILL.md is getting too long (approaching 500 lines):
- •Move detailed content to
references/files - •Keep only core workflow and navigation in SKILL.md
- •Reference split files clearly: "See filename for details"