Files

refactor: migrate commands to user-invocable skills

Claude Code has unified commands into skills with the user-invocable
frontmatter field. This migration:

- Converts 20 commands to skills with user-invocable: true
- Consolidates docs into single writing-capabilities.md
- Rewrites capability-writing skill for unified model
- Updates CLAUDE.md, Makefile, and other references
- Removes commands/ directory

Skills now have two types:
- user-invocable: true - workflows users trigger with /name
- user-invocable: false - background knowledge auto-loaded

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-11 16:39:55 +01:00

2.5 KiB

Raw Permalink Blame History

Learnings

This folder captures learnings from retrospectives and day-to-day work. Learnings serve three purposes:

Historical record: What we learned and when
Governance reference: Why we work the way we do
Encoding source: Input that gets encoded into skills and agents

The Learning Flow

Experience → Learning captured → Encoded into system → Knowledge is actionable
                   ↓
            Stays here for:
            - Historical reference
            - Governance validation
            - Periodic review

Learnings are not the final destination. They are inputs that get encoded into skills and agents where Claude can actually use them. But we keep the learning file as a record of why we encoded what we did.

Writing a Learning

Create a new file: YYYY-MM-DD-short-title.md

Use this template:

# [Title]

**Date**: YYYY-MM-DD
**Context**: What triggered this learning (task, incident, observation)

## Learning

The insight we gained. Be specific and actionable.

## Encoded In

Where this learning has been (or will be) encoded:

- `skills/xxx/SKILL.md` - What was added/changed
- `agents/xxx/AGENT.md` - What was added/changed

If not yet encoded, note: "Pending: Issue #XX"

## Governance

What this learning means for how we work going forward. This is the "why" that justifies the encoding.

Encoding Process

Capture the learning in this folder
Create an issue to encode it into the appropriate location
Update the skill/agent with the encoded knowledge
Update the learning file with the "Encoded In" references

The goal: Claude should be able to use the learning, not just read about it.

What Gets Encoded Where

Learning Type	Encode In
How to use a tool	`skills/` (background skill)
Workflow improvement	`skills/` (user-invocable skill)
Subtask behavior	`agents/`
Organization belief	`manifesto.md`
Product direction	`vision.md` (in product repo)

Periodic Review

Periodically review learnings to:

Verify encoded locations still reflect the learning
Check if governance is still being followed
Identify patterns across multiple learnings
Archive or update outdated learnings

Naming Convention

Files follow the pattern: YYYY-MM-DD-short-kebab-title.md

Examples:

2024-01-15-always-use-comments-flag.md
2024-01-20-verify-before-cleanup.md
2024-02-01-small-prs-merge-faster.md

2.5 KiB Raw Permalink Blame History