feat(skills): trail learn turns corrections into skills

[anirudhkumar-nanonets]

Moves: takeaway_saved and skills_folded (PostHog DB 11), both 0 on 2026-10-07 because they're new.

When the user corrects how something is done, the agent saves the correction, and the agent follows it from then on.

• trail learn <skill> saves the correction as a takeaway in ~/.trail/repos/<key>/skills/<skill>/takeaways/, with the text on stdin.
  • A skill the repo already has in .claude/skills/ takes the takeaway as is.
  • A new name starts a skill in ~/.trail.
  • Trail's and graft's own skills are refused, because every init rewrites them.
• trail skills lists the skills. Its subcommands:
  • show <skill> prints the skill and the corrections not yet folded in, newest first.
  • fold writes the waiting takeaways into SKILL.md and bumps the version. It edits only the version: line, so a team's own frontmatter keeps its exact formatting. --confirmed folds only the ones a second person confirmed.
  • publish moves a skill from ~/.trail into the repo's .claude/skills/, to commit for the team.
  • confirm records that a second person confirmed a takeaway.
• When to run it. The trail skill's description and its opening list, and the session-start text, say to run trail learn when the user corrects how something is done or states a rule for it.
• Session start tells the agent about skills Claude Code can't load by itself: ones kept only on this machine, and the team's ones with corrections waiting.

Tests: npm test, 1,424 pass.

[trailhq-graft]

🌱 graft blast radius

4 areas changed → 5 areas can be affected. 14 dependent symbols, depth 2.
Tests: no test reaches noSuchSkill; 2 areas updated their tests.
Tag: @shhdwi — 7 of 9 areas

flowchart TB
  A0(("Session Metrics<br/>6 symbols"))
  A1(("Data Synchronization<br/>3 symbols"))
  A2(("Skill Registry<br/>2 symbols"))
  A3(("Telemetry Tracking<br/>2 symbols"))
  A4(("Tooling<br/>1 symbol"))
  classDef reached fill:#D9EDF3,stroke:#3AA7C9,stroke-width:1.5px,color:#0E313C;
  class A0,A1,A2,A3,A4 reached;

Loading

Can be affected	Symbols	Nearest hop	Reached from
Session Metrics	6	src/claude/session-metrics.ts:L1-L214 session-metrics.ts — imports, depth 1	Skill Formatting, Contract Management
Data Synchronization	3	src/brain/autopush.ts:L1-L270 autopush.ts — imports, depth 1	Contract Management
Skill Registry	2	src/hosts/antigravity.ts:L36-L46 installAntigravitySkill — calls, depth 2	Skill Formatting
Telemetry Tracking	2	src/telemetry/sessions.ts:L1-L113 sessions.ts — imports, depth 1	Contract Management
Tooling	1	src/mcp/tools.ts:L1-L330 tools.ts — imports, depth 2	Contract Management

Who knows this code — 1 person across 9 areas

Area	Who knows it
Contract Management · changed	@shhdwi — 1 commit, last 27d ago
Skill Formatting · changed	@shhdwi — 1 commit, last 27d ago
noSuchSkill · changed	@shhdwi — 1 commit, last 27d ago
Session Metrics · affected	@shhdwi — 1 commit, last 27d ago
Skill Registry · affected	@shhdwi — 1 commit, last 27d ago
Telemetry Tracking · affected	@shhdwi — 1 commit, last 27d ago
Tooling · affected	@shhdwi — 1 commit, last 27d ago
Skill Management · changed	only you — nobody else has touched these files
…1 further area

Ownership is git history over each area's own files, weighted towards recent work (120-day half-life). Merge commits and bots are dropped, and you are dropped from your own PR. A name with no @ has no GitHub handle in its commit email — tag them by hand, or add a .mailmap entry. A suggestion from history, not a CODEOWNERS rule.

All 14 dependent symbols, grouped by area

Session Metrics — 6 symbols in 6 files

• src/claude/session-metrics.ts:L1-L214 — session-metrics.ts (imports, depth 1)
• src/claude/state.ts:L1-L104 — state.ts (imports, depth 1)
• src/claude/init.ts:L81-L132 — runInit (calls, depth 2)
• src/claude/stats.ts:L1-L27 — stats.ts (imports, depth 2)
• src/claude/statusline.ts:L1-L39 — statusline.ts (imports, depth 2)
• src/claude/sync-run.ts:L1-L42 — sync-run.ts (imports, depth 2)

Data Synchronization — 3 symbols in 3 files

• src/brain/autopush.ts:L1-L270 — autopush.ts (imports, depth 1)
• src/brain/pull.ts:L1-L332 — pull.ts (imports, depth 1)
• src/brain/watch-trail.ts:L1-L395 — watch-trail.ts (imports, depth 1)

Skill Registry — 2 symbols in 2 files

• src/hosts/antigravity.ts:L36-L46 — installAntigravitySkill (calls, depth 2)
• src/hosts/registry.ts:L1-L133 — registry.ts (references, depth 2)

Telemetry Tracking — 2 symbols in 2 files

• src/telemetry/sessions.ts:L1-L113 — sessions.ts (imports, depth 1)
• src/telemetry/track.ts:L1-L161 — track.ts (imports, depth 1)

Tooling — 1 symbol in 1 file

• src/mcp/tools.ts:L1-L330 — tools.ts (imports, depth 2)

Test signal per changed area — 2 ✓ · 1 ✗ · 1 –

Reached = a node under a test path has a resolved edge into the changed symbol. It undercounts anything called indirectly — through a CLI, a spawned process or a dynamic import — so read a low ratio as “look here”, never as a coverage gate.

• – Contract Management — 1 test file changed here: test/telemetry-contract.test.ts
• ✓ Skill Formatting — 1 of 4 reached · 1 test file changed here: test/trail-notes.test.ts
  • not reached: teamNotesDirective, main, trailSkill
• ✓ Skill Management — 11 of 24 reached · 1 test file changed here: test/trail-skills.test.ts
  • not reached: asDate, fold, foldedLine, publish, readSkill, readTakeaways, renderNewSkill, rewriteSkill, …5 more
• ✗ noSuchSkill — 0 of 1 reached · no test file reaches it
  • not reached: noSuchSkill

14 test suites also reference this code

14 symbols, kept out of the diagram and the table so they cannot crowd out the areas a reviewer has to look at.

• test/brain-context-files-pull.test.ts
• test/brain-trail-watch.test.ts
• test/claude-format.test.ts
• test/claude-hooks.test.ts
• test/claude-skill-template.test.ts
• test/claude-state.test.ts
• test/claude-statusline.test.ts
• test/claude-tally.test.ts
• test/session-metrics.test.ts
• test/telemetry-gate.test.ts
• test/telemetry-install.test.ts
• test/telemetry-sessions.test.ts
• test/trail-name.test.ts
• test/trail-session-start.test.ts

⚠️ 1 changed file not in the graph (TELEMETRY.md) — no parser claims the extension, or the index predates the file.

_{graft blast · refs/graft/base...HEAD · depth 2 · 10 changed files}

Open the interactive graph → — click an area to see the code that changed, and the line that reaches it.

[anirudhkumar-nanonets]

Folded into #558, which now carries this change along with the rest of trail.