Skill Awareness

Overview

Track every skill application to build a practice record.

When you apply any code-craft skill, log it. This creates a persistent record across Claude Code and OpenCode sessions for analytics, identifying underused skills, and measuring improvement.

The Iron Rule

ALWAYS log when applying a code-craft skill. No silent applications.

Usage Log

Append one JSON line to ~/.claude/skills/skill-usage.jsonl:

{"ts":"2026-01-22T10:30:00Z","skill":"single-responsibility","agent":"opencode","project":"/path/to/project","ctx":"Split UserManager into UserAuth and UserProfile"}

Field	Value
`ts`	ISO 8601 timestamp
`skill`	Skill name (kebab-case)
`agent`	`claude-code` or `opencode`
`project`	Working directory path
`ctx`	Brief description of application (< 100 chars)

Skill Detection Matrix

If you're doing...	Check these skills
Creating/modifying classes	`single-responsibility`, `open-closed`, `composition-over-inheritance`, `encapsulation`
Inheritance hierarchy	`liskov-substitution`, `composition-over-inheritance`
Adding dependencies	`dependency-inversion`, `interface-segregation`
Error handling	`fail-fast`, `exception-hierarchies`, `error-boundaries`
Writing API endpoints	`rest-conventions`, `error-responses`, `api-versioning`, `idempotency`, `input-validation`
Database queries	`n-plus-one-prevention`, `caching`, `lazy-loading`
Writing tests	`tdd`, `test-isolation`, `aaa-pattern`
Handling secrets/auth	`secrets-handling`, `auth-patterns`, `input-validation`
Concurrent operations	`race-conditions`, `deadlock-prevention`, `idempotency`
Copy-pasting code	`dry`
Adding "future" features	`yagni`, `kiss`
Complex logic	`kiss`, `separation-of-concerns`, `law-of-demeter`
Modifying state	`immutability`, `encapsulation`

Logging Protocol

After applying a skill:

echo '{"ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","skill":"SKILL_NAME","agent":"AGENT","project":"PROJECT_PATH","ctx":"BRIEF_CONTEXT"}' >> ~/.claude/skills/skill-usage.jsonl

Analytics Commands

View total usage:

cat ~/.claude/skills/skill-usage.jsonl | jq -s 'group_by(.skill) | map({skill: .[0].skill, count: length}) | sort_by(-.count)'

Recent applications:

tail -20 ~/.claude/skills/skill-usage.jsonl | jq .

Underused skills (applied < 3 times):

cat ~/.claude/skills/skill-usage.jsonl | jq -s 'group_by(.skill) | map({skill: .[0].skill, count: length}) | map(select(.count < 3))'

Never-used skills:

# Compare logged skills against all 31
comm -23 <(ls ~/.claude/skills/ | grep -v '\.' | sort) <(cat ~/.claude/skills/skill-usage.jsonl | jq -r '.skill' | sort -u)

Usage by project:

cat ~/.claude/skills/skill-usage.jsonl | jq -s 'group_by(.project) | map({project: .[0].project, skills: (group_by(.skill) | map({skill: .[0].skill, count: length}))})'

Available Skills Reference

SOLID (5)

single-responsibility, open-closed, liskov-substitution, interface-segregation, dependency-inversion

Core (6)

dry, yagni, kiss, composition-over-inheritance, law-of-demeter, fail-fast

Testing (3)

tdd, test-isolation, aaa-pattern

Security (3)

input-validation, secrets-handling, auth-patterns

API Design (4)

rest-conventions, error-responses, idempotency, api-versioning

Performance (3)

n-plus-one-prevention, lazy-loading, caching

Code Quality (3)

separation-of-concerns, encapsulation, immutability

Error Handling (2)

exception-hierarchies, error-boundaries

Concurrency (2)

race-conditions, deadlock-prevention

Pre-Completion Checklist

Before finishing any coding task, ask:

Which skills from the detection matrix applied?
Did I follow them?
Did I log each application?
Any violations I should flag to the user?

The Bottom Line

Every skill application gets logged. No exceptions.

This builds a record of practice, reveals blind spots, and enables continuous improvement. When in doubt about whether a skill applies—log it and note the uncertainty.

skill-awareness

SKILL.md