takazudo/skill-tweaker

Tweak Existing Skill

Workflow

Step 1: Identify the skill

Find skills at:

• $HOME/.claude/skills/<name>/SKILL.md (personal)
• .claude/skills/<name>/SKILL.md (project)

Case-sensitivity check (IMPORTANT for macOS): The skill file may be named SKILL.md (uppercase) or skill.md (lowercase). On case-insensitive filesystems (macOS), both resolve to the same file on disk, but git tracks them as separate entries. Before editing:

1. Check the actual filename in git: git ls-files --stage '<skill-dir>/'
2. If both SKILL.md and skill.md exist in the git index, remove the duplicate: git rm --cached '<path>/SKILL.md' (keep the one matching the project convention)
3. Always use the exact filename that exists in git when editing

Read the skill file 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. Claude tends to undertrigger — make the description slightly pushy (e.g. "Make sure to use this skill whenever the user mentions X, Y, or Z, even if they don't explicitly ask for it") | | 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

Inserting a new step into a numbered step list: When a skill is structured as Step 1, Step 2, Step 3, ... and you need to add a new step between existing ones, renumber the steps so the sequence stays contiguous. Do NOT introduce fractional numbers like "Step 2.5", and do NOT insert "Step 0" at the start. Examples:

• Inserting between Step 2 and Step 3: the old Step 3 becomes Step 4, old Step 4 becomes Step 5, and so on. Update every reference to those numbers (body text, TODO checklists, cross-references, "proceed to Step N" wording).
• Inserting before Step 1: shift everything up by one — the new step becomes Step 1, old Step 1 becomes Step 2, etc.

After renumbering, grep the skill file for stale references (e.g., "Step 3" where you now mean "Step 4") and fix them. Also check any sibling files (scripts, references) that mention step numbers.

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: Use the exclamation-backtick pattern (e.g. exclamation + backtick-wrapped command) to run shell commands before skill content is sent to Claude.

Writing principles when rewriting body content:

• Yellow flag: heavy-handed MUSTs. All-caps "ALWAYS" / "NEVER" / "MUST" piled across the skill is usually a sign of overfitting. When you see this, try reframing with a one-sentence explanation of why the rule matters — modern models follow reasoning more reliably than rigid imperatives, and the prompt gets shorter.
• Don't overfit to the one example that broke. If the user reports the skill failed on a specific case, fix the underlying pattern rather than adding a special-case rule that only helps that one input.
• Cut instructions that aren't pulling their weight. If you can read the skill and not lose anything by deleting a sentence, delete it.

Step 4: Format SKILL.md

Format the edited SKILL.md file using the mdx-formatter to ensure consistent markdown formatting:

pnpm dlx @takazudo/mdx-formatter --write <path-to-SKILL.md>

Step 5: Path safety check

Scan the skill's SKILL.md and all referenced scripts/files for ~/ in file paths. Replace with $HOME/.

Why: ~ is a shell expansion feature. It is NOT expanded by Node.js fs operations, Python open(), or non-login shell contexts. Using ~/ in these contexts creates a literal directory named ~ inside the working directory instead of resolving to the user's home directory. This has caused real bugs where a ~/ directory was accidentally created inside a repo.

What to check:

• Any hardcoded path like ~/foo/bar in scripts or skill instructions
• Shell commands wrapped in backtick injection that might be passed to Node.js
• File paths in references or asset configurations

Replace with: $HOME/foo/bar (expanded by both shell and most runtimes)

Step 6: Verify

After editing:

1. YAML frontmatter parses without errors
2. Description matches intended trigger scenarios
3. Referenced files (scripts, references) exist and are correct
4. For forked skills: content is self-contained (no conversation history available)
5. SKILL.md body stays under 500 lines
6. No ~/ paths in file operations -- use $HOME/ instead (see Step 5)

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"