feat: /learn skill for agent onboarding from external repos + release-driven knowledge updates

[maxine-at-forecast]

Summary

Two related features that keep agent-facing knowledge current and composable:

1. /learn <repo-or-package> skill

A skill (shipped via crosslink init) that lets an agent rapidly onboard on an external dependency, library, or codebase — the "I know kung fu" moment.

Usage:

/learn forecast-bio/atdata
/learn tokio-rs/axum
/learn ratatui

What it does:

1. Resolves the target (GitHub repo, crates.io, npm, etc.)
2. Finds the repo's agent-focused onboarding material:
   • CLAUDE.md, AGENTS.md, CONTRIBUTING.md
   • crosslink knowledge pages (if the repo uses crosslink)
   • README, API docs, examples
3. Reads and synthesizes the material into two knowledge pages:
   • Standalone reference (knowledge add <name>-reference) — what the library is, key APIs, patterns, gotchas, versioning
   • Project-specific applicability (knowledge add <name>-in-<project>) — how this dependency is used here, which APIs matter for this codebase, integration patterns, known constraints
4. Tags both pages appropriately (learned-dependency, onboarding, the dependency name)

Why this matters:

• Agents currently spend significant tokens exploring unfamiliar dependency APIs every session
• A one-time /learn invocation creates persistent knowledge that all future sessions and agents benefit from
• The project-specific page is the high-value part — it grounds the generic docs in this codebase's usage patterns

Design considerations:

• Should work for GitHub repos, crate names, npm packages, and potentially local paths
• The project-specific page should reference actual files in the current repo that use the dependency
• Should detect if knowledge already exists and offer to update rather than duplicate
• Should be idempotent — re-running /learn refreshes the pages

2. Release-driven knowledge updates

Extend the release flow (currently prototyped as /dev-release, eventually crosslink release) so that in addition to bumping versions, updating CHANGELOG, and reviewing docs, it also:

1. Reviews agent onboarding knowledge pages tagged onboarding — checks if they're stale relative to the changes in the release
2. Updates pages that reference changed features — e.g., if the command taxonomy changed, update command-taxonomy; if new workflow patterns were added, update agent-workflow-patterns
3. Updates learned dependency pages — if a dependency was bumped or its usage patterns changed, flag the corresponding /learn-generated pages for refresh

This makes the release process a natural checkpoint for keeping agent knowledge current, rather than relying on someone to remember to update docs separately.

Integration point: A new phase in the release flow (between "Documentation review" and "Test & lint") that scans knowledge pages and proposes updates.

Relationship between the two

/learn creates knowledge. The release flow maintains it. Together they ensure agents always have current, project-grounded reference material without manual upkeep.

Open questions

• Should /learn work offline (local repos only) or require network access for remote repos?
• Should the release flow auto-update knowledge or just flag stale pages for human review?
• Should /learn be able to target specific subpaths (e.g., /learn forecast-bio/atdata --focus src/federation)?
• How should versioning of learned knowledge work — pin to a dependency version?