Write the skills. The agent uses them. skilljournal learns from them.

A lightweight MCP server that gives Claude Code and Codex CLI persistent skill memory with learning journals — so agents don't repeat mistakes and get better every time a skill runs.

Why this exists

Agents are good at following instructions. They're bad at writing them.

The SkillsBench paper shows:

• Curated skills improve performance by +16.2 percentage points
• Self-generated skills hurt performance (-1.3pp)
• Just 2-3 good skills per task is optimal
• A smaller model + good skills > larger model without them

┌──────────────────────────────────────────┐
│  CURATED SKILL BOOST     ████████ +16.2pp│
│  SELF-GEN SKILL BOOST    ░          -1.3pp│
│  OPTIMAL SKILLS/TASK     ██           2-3│
│  SMALL+SKILLS > BIG      ████████     YES│
└──────────────────────────────────────────┘

The problem

Even when agents use skills:

• They don't improve them over time
• They repeat the same mistakes
• Self-generated skills drift and degrade

The idea

skilljournal turns skills into learning systems:

1. A skill runs
2. The agent reflects on what worked / failed
3. A journal entry is stored alongside the skill
4. Next time the skill runs, the journal context is injected

The same mistake doesn't happen twice. Skills get better without manual curation.

What it does

• Persistent per-skill journals
• Automatic post-run reflection
• Context injection on future runs
• MCP server for Claude Code / Codex CLI
• Works with both curated and self-generated skills

Setup

Claude Code

claude mcp add skilljournal -- npx skilljournal

Codex CLI

codex mcp add skilljournal -- npx skilljournal

That's it. Or install globally first with npm install -g skilljournal and replace npx skilljournal with just skilljournal.

git clone https://github.com/w1ll14m64n/skilljournal.git
cd skilljournal && npm install

# Claude Code
claude mcp add skilljournal -- node /absolute/path/to/skilljournal/server.mjs

# Codex CLI
codex mcp add skilljournal -- node /absolute/path/to/skilljournal/server.mjs

Tools

• list_skills — finds skills across ~/.codex/skills/, <project>/.codex/skills/, ~/.claude/commands/, and <project>/.claude/commands/
• resolve_triggered_skills — matches a task to relevant skills using token scoring, returns the skill content + any journal entries as prompt-ready text
• record_skill_learning — writes a learning entry to .journal/<slug>.md so it gets picked up next time

Skill discovery

Scans four places:

| Directory | Scope | |-----------|-------| | ~/.codex/skills/<slug>/SKILL.md | User | | <project>/.codex/skills/<slug>/SKILL.md | Project | | ~/.claude/commands/<slug>.md | User | | <project>/.claude/commands/<slug>.md | Project |

Project skills override user skills when slugs collide.

Skills are markdown files. Optional YAML frontmatter for name and trigger phrases:

---
name: "Deploy to Production"
triggers: ["deploy", "release", "ship it"]
---

1. Run tests first
2. ...

Journals

Learnings live in <project>/.journal/<slug>.md. Structured, timestamped, git-friendly:

## 2026-04-09 - Deployment timeout on large assets
Learning: Asset compilation exceeds the default 120s timeout when bundle > 50MB

Action: Added --timeout 300 flag to deploy command
Context: Discovered during Q2 release with new image assets

When resolve_triggered_skills fires for a deploy task, this entry rides along. The agent sees it before hitting the same wall.

How matching works

Token-based scoring. Exact slug match is the strongest signal, then trigger phrases, then vocabulary overlap. Only skills above zero get returned — no context window pollution.

Structure

server.mjs        # MCP entry point
src/
  skills.js       # Discovery and resolution
  journal.js      # Read/append journal entries
  matcher.js      # Token-based skill matching
  utils.js        # Frontmatter parsing, helpers

Reading

• SkillsBench — the benchmark behind the numbers above
• SoK: Agentic Skills — full skill lifecycle, discovery through evaluation
• Claude Code skills docs

License

MIT