skill-awareness

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:

1. Which skills from the detection matrix applied?
2. Did I follow them?
3. Did I log each application?
4. 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.