claude-mods/tests/skills/reports/skill-analysis.md

Skill Activation Analysis

Generated: 2025-12-20

How Skills Actually Work

Important: Skills are NOT automatically triggered by keywords. They work like this:

1. All skill descriptions are loaded into Claude's system prompt at startup
2. Claude reads user messages and decides whether to invoke a skill
3. Claude uses the Skill tool to explicitly activate: skill: "data-processing"
4. The skill's SKILL.md content is then loaded into context

The "Triggers on:" keywords are hints for Claude, not automatic activation rules.

---

Skill-by-Skill Analysis

data-processing

Triggers: parse JSON, extract from YAML, query config, Docker Compose, K8s manifests, GitHub Actions workflows, package.json, filter data

Issue	Severity	Details
Generic triggers	Medium	"package.json" triggers on ANY package.json mention
Overlap with built-in	High	Claude already knows jq/yq - may not invoke skill
No visibility	High	User won't know skill was used

Will it fire? Maybe. Claude might just use jq directly without invoking the skill.

---

git-workflow

Triggers: stage changes, create PR, review PR, check issues, git diff, commit interactively, GitHub operations, rebase, stash, bisect

Issue	Severity	Details
Competes with built-in git	High	Claude has built-in git commit flow
Too many triggers	Medium	10 different trigger phrases
lazygit is TUI	Low	Can't actually use lazygit in non-interactive mode

Will it fire? Unlikely for common git operations. Built-in behavior takes precedence.

---

structural-search

Triggers: find all calls to X, search for pattern, refactor usages, find where function is used, structural search

Issue	Severity	Details
Competes with Grep tool	High	Claude defaults to ripgrep for code search
Specific tool (ast-grep)	Low	Clear use case distinction

Will it fire? Only if user specifically asks for AST/structural search.

---

code-stats

Triggers: how big is codebase, count lines of code, what languages, show semantic diff, compare files, code statistics

Issue	Severity	Details
Unique triggers	Low	"code statistics" is fairly specific
tokei vs wc -l	Medium	Claude might use simpler approach

Will it fire? Probably yes for "count lines of code" type requests.

---

file-search

Triggers: fd, ripgrep, rg, find files, search code, fzf, fuzzy find, search codebase

Issue	Severity	Details
Redundant with built-in	Critical	Claude has Glob/Grep tools built-in
Tool names as triggers	Low	If user says "use fd", skill helps

Will it fire? Only if user explicitly mentions fd/fzf. Otherwise Claude uses built-in tools.

---

find-replace

Triggers: sd, find replace, batch replace, sed replacement, string replacement, rename

Issue	Severity	Details
Competes with Edit tool	High	Claude prefers Edit tool for replacements
Unique for batch ops	Medium	"batch replace across files" is specific

Will it fire? Only for batch/multi-file operations.

---

doc-scanner

Triggers: review codebase, understand project, explore codebase, conventions, agents

Issue	Severity	Details
Very generic	High	Many requests "understand codebase"
Good use case	Low	Finding AGENTS.md, CLAUDE.md is useful

Will it fire? Yes, for "explore codebase" type requests. May over-fire.

---

task-runner

Triggers: run tests, build project, list tasks, check available commands, run script, project commands

Issue	Severity	Details
Very generic	Critical	"run tests" is extremely common
just-specific	Medium	Only useful if project has justfile

Will it fire? Too often for "run tests" - even when no justfile exists.

---

project-planner

Triggers: sync plan, update plan, check status, plan is stale, track progress, project planning

Issue	Severity	Details
Specific triggers	Low	"sync plan" is specific enough
Depends on session commands	Medium	Only useful if user uses /save and /sync

Will it fire? Appropriately - triggers are specific.

---

python-env

Triggers: uv, venv, pip, pyproject, python environment, install package, dependencies

Issue	Severity	Details
Tool-specific	Low	"uv" is specific
Generic overlap	Medium	"install package" could be npm too

Will it fire? Yes for Python-specific requests.

---

rest-patterns

Triggers: rest api, http methods, status codes, api design, endpoint design, api versioning, rate limiting, caching

Issue	Severity	Details
Reference-only	Low	No executable commands
Good specificity	Low	"api design" is clear

Will it fire? Appropriately for API design questions.

---

sql-patterns

Triggers: sql patterns, cte example, window functions, sql join, index strategy, pagination sql

Issue	Severity	Details
Reference-only	Low	No executable commands
Specific	Low	"window functions" is clear

Will it fire? Appropriately for SQL questions.

---

sqlite-ops

Triggers: sqlite, sqlite3, aiosqlite, local database, database schema, migration, wal mode

Issue	Severity	Details
Clear scope	Low	sqlite-specific
Overlaps with sql-patterns	Medium	Both cover SQL

Will it fire? Yes for SQLite-specific questions.

---

tailwind-patterns

Triggers: tailwind, utility classes, responsive design, tailwind config, dark mode css, tw classes

Issue	Severity	Details
Framework-specific	Low	"tailwind" is clear
Reference-only	Low	No executable commands

Will it fire? Yes for Tailwind questions.

---

mcp-patterns

Triggers: mcp server, model context protocol, tool handler, mcp resource, mcp tool

Issue	Severity	Details
Very specific	Low	MCP is niche topic
Reference-only	Low	Patterns and examples

Will it fire? Appropriately for MCP development.

---

tool-discovery

Triggers: which agent, which skill, what tool should I use, help me choose, recommend agent, find the right tool

Issue	Severity	Details
Meta-skill	Low	Helps find other skills
May not be needed	Medium	Claude already has tool descriptions

Will it fire? When user asks for help choosing tools.

---

Summary: Problem Skills

Skill	Issue	Recommendation
file-search	Redundant with built-in Glob/Grep	Remove or rename to "fd-fzf-patterns"
task-runner	Too generic, just-specific	Add "justfile" to triggers, remove generic ones
git-workflow	Competes with built-in git flow	Focus on lazygit/delta only
find-replace	Competes with Edit tool	Focus on batch/multi-file only
doc-scanner	Too generic	Already works well

How to Know If a Skill Was Used

Currently: You can't easily tell.

Options to add visibility:

1. Log skill invocations - Add a hook that logs when Skill tool is called
2. Skill announces itself - First line of skill output says "[data-processing skill]"
3. Status line - Configure Claude Code to show active skill