Add /learn skill — per-project operational knowledge

[TechNickAI]

Summary

• New /learn skill for managing project-specific operational knowledge across sessions
• Plain markdown storage (not JSONL) — human-readable, git-friendly
• Five categorized files: index, patterns, pitfalls, operational, decisions

Changes

• plugins/core/skills/learn/SKILL.md — new skill (164 lines)
  • /learn — show index, /learn add — add entry, /learn search — search all files
  • /learn prune — find stale entries, /learn export — format for CLAUDE.md
  • Session-end reflection workflow (captures gotchas, conventions, decisions)
  • Staleness detection (checks if referenced files/commands still exist)
  • Complements memory system (memory = user prefs, learnings = project ops)

Design decisions

• Plain markdown over JSONL (human-readable, easy to edit manually)
• Categorized by type over chronological (find what you need faster)
• Index kept under 50 lines (briefing, not dump)
• Inspired by gstack (JSONL) and Hermes (three-tier markdown)

Test plan

• Run /learn add — verify file creation in learnings directory
• Run /learn search <term> — verify search across all files
• Run /learn prune — verify stale detection works
• Verify index.md stays concise

🤖 Generated with Claude Code

[claude]

Code Review — /learn skill

Good addition overall. The design decisions are sound (plain markdown > JSONL, categorized > chronological, curated index). A few issues worth addressing:

---

Bug: index.md won't auto-load at session start

The Storage section says:

index.md — Quick-reference summary (auto-loaded at session start)

This won't happen automatically. Claude Code doesn't scan ~/.claude/projects/{hash}/learnings/ — it only processes CLAUDE.md files and the configured memory system. Without a CLAUDE.md entry or a hook, the index stays invisible at session start.

Fix options:

1. Add a note in the bootstrapping section telling users to add a line to their project's CLAUDE.md:

   <!-- learnings index is at ~/.claude/projects/{hash}/learnings/index.md — read it at session start -->
   

2. Or document that /learn must be explicitly invoked — drop the "auto-loaded" claim.

---

Missing color field

Other skills in this repo have a color field in frontmatter. Per .claude/CLAUDE.md, meta/architecture category maps to magenta. The frontmatter should include:

color: magenta

---

/learn stats is listed but has no implementation section

The Usage section lists /learn stats — Show counts by category but there's no corresponding section explaining what it should output or how to compute it. Either add a ## Stats section or remove it from the usage list to avoid confusion.

---

Prune: "commands still work" is risky

Commands mentioned → do they still work?

Running arbitrary commands to verify them during prune could have side effects (triggering builds, network calls, etc.). Consider tightening this to:

• Check if the command binary exists (which <cmd>)
• Or just check if it's still referenced in package.json scripts / Makefile / etc.

---

Minor: project hash description is correct but could be clearer

with forward slashes replaced by hyphens

This is accurate (confirmed by this repo's own memory path: -home-runner-work-ai-coding-config-ai-coding-config), but the leading - (from the leading /) could trip people up. Worth noting the path starts with -.

---

Nit: /learn export output format not specified

The export command's behavior is described as "format suitable for CLAUDE.md" but there's no example of what that output looks like. A small example block (like you provided for the index format) would make it unambiguous.

---

Summary: The skill is well-structured and follows project conventions. The auto-loading claim is the most significant issue — it's functionally incorrect and could confuse users who expect the index to appear in new sessions without any setup. The other items are polish.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 67cc4fccf9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Replace nonexistent /learn command references

This skill advertises /learn and /learn ... subcommands, but the commit only adds a skill definition and does not add a corresponding slash-command file (there is no plugins/core/commands/learn.md). In this repo, slash commands come from files in plugins/core/commands/, so users following this usage section will hit an unknown command instead of the new feature. Either wire a real command entrypoint or document invocation via the existing skill mechanism.

Useful? React with 👍 / 👎.

[claude]

Code Review — /learn skill

Overall this is a well-designed skill. The structure, frontmatter conventions, color assignment, and "Use when..." description format all align with project conventions. The separation of concerns (memory = user prefs, learnings = project ops) is clearly articulated. A few issues worth addressing:

---

Issues

1. Version starts at 1.1.0 (should be 1.0.0)

Every other new skill in this repo starts at 1.0.0 (brainstorm-synthesis, fireflies, limitless, mcp-debug, vercel-react-best-practices, writing-for-llms). Using 1.1.0 for a brand-new file implies a prior version existed elsewhere.

-version: 1.1.0
+version: 1.0.0

---

2. Inconsistent invocation syntax in the Storage note

The note correctly states "this is a skill trigger — not a registered slash command" and instructs users to invoke via natural language. But then it immediately uses slash command syntax:

/learn — show index, /learn add — add entry, /learn search — search all files

This is in the PR description, but the same pattern appears subtly in the Storage section note. The Usage section correctly uses natural language (show learnings, add a learning). The Storage note's invocation examples should match — use natural language or remove the command-style examples there.

---

3. stats subcommand missing from triggers

The Usage section documents learning stats as a valid invocation, but stats appears nowhere in the triggers array. A user saying "show learning stats" won't reliably activate this skill.

triggers:
  - "learn"
  - "learnings"
  - "what did we learn"
  - "remember this pattern"
  - "project knowledge"
  - "operational notes"
  - "what do we know about"
+ - "learning stats"
+ - "stats"

---

4. Index auto-load path has an unresolved placeholder with no inline derivation hint

The Storage note tells users to add:

@~/.claude/projects/{project-hash}/learnings/index.md

The algorithm for deriving {project-hash} is explained at the bottom of the file in the Bootstrapping section — but that's far from where the user needs it. Consider either adding a one-liner inline or pointing to Bootstrapping:

To find your project hash, see the Bootstrapping section below, or run: pwd | sed 's|/|-|g'

---

Nits

• The session-end reflection prompt is excellent — very practical. Consider adding a note that it should only fire if there's actually something worth capturing (the "5-minute rule" at the bottom covers this, but could be surfaced earlier).
• The [STALE] prefix convention for prune results is a good touch — preserves history without data loss.

---

Verdict

Minor issues, none blocking. The 1.1.0 version and missing stats trigger are easy fixes. The design is solid and the skill fills a real gap in the memory system.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

Skill frontmatter includes agent-only color field

Low Severity

The color: magenta frontmatter field is specific to agent definitions, not skills. No other skill in the repo uses color, the skill creation guide in plugins/core/skills/CLAUDE.md doesn't list it as a valid field, and validate-frontmatter.py only validates color for agents (where it's required). This appears to be mistakenly carried over from an agent template.

 

[cursor]

Export template creates inverted markdown heading hierarchy

Medium Severity

The export template uses ### (H3) for category headers like ### Patterns, but the entry format specifies each entry as an ## (H2) heading. When file contents are inlined into the export, each entry's H2 heading outranks its parent H3 category, producing a broken and misleading markdown heading hierarchy. The categories and the top-level ## Project Learnings heading would effectively be swallowed by the first entry's H2.

Additional Locations (1)

• plugins/core/skills/learn/SKILL.md#L98-L104