In short:
ak-journalrecords what happened in a session, why, and what is still open, then saves it withak journal createtoplans/journals/. It usually runs automatically at the end ofak-cook,ak-fix,ak-shipand is the last step, with no next skill. It does not replace ADRs or docs, and it does not post to social media on its own.
Disclosure: I maintain AgentKit and have an affiliate relationship with it: the AgentKit link in this post is an affiliate link; buying through it gets you 30% off.
Summary
Use it when you have just fixed a hard bug, finished a session with many small tasks, or want to write honestly about a failure, so that tomorrow you know where you left off. You do not need it when what you want to keep is a long-lived rule: that goes into an ADR or the project docs.
flowchart LR
A["ak-cook, ak-fix, ak-ship"] --> B["ak-journal"]
U["You call it by hand"] --> B
B --> C["File in plans/journals/"]
B --> D["Social post, only when you ask"]
C --> E["Stop, last step"]It rests on 4 ideas:
| Idea | Question | Example |
|---|---|---|
| History, not decisions | Should this go into the journal or into the docs? | "Tried 3 caching approaches, the second one served stale data" goes into the journal. The rule "all caching uses Redis" goes into an ADR or the project docs. |
| Saved through the CLI | Where does the file live and what is it called? | plans/journals/2026-10-21-session-expiry-fix.md. Another entry with the same name on the same day becomes ...-2.md, ...-3.md. Review them with ak journal list, ak journal show <slug> or the Journals page in the desktop app. |
| Automatic and manual | When is a journal written on its own, and how do you turn it off? | ak-plan, ak-cook, ak-fix, ak-ship, ak-bootstrap end with an automatic journal step. Turn it off once with --skip-journal on that skill, or for good with ak config prefs set journal.auto false. Calling /ak-journal by hand always runs. |
| Local first, social later | If channels are configured, does it post on its own? | No. You have to say "post to social media" explicitly. Even then, it previews the exact channels and content, and only reports a post as done once the provider returns a receipt. |
A good journal is specific: real errors, real paths, real results. Turning off journal.auto only turns off the automatic step at the end of workflows, and calling /ak-journal by hand still runs.
Sample prompt after a bug fix:
/ak-journal Record the fix for <bug name>: root cause, main changes,
user impact, the decision we made and what is still open.This skill has no flags.
Below is the detailed version: the run flow, 5 situations with prompts, how to pass options when the skill has no flags, the change history by ak release, and common pitfalls. The detailed version and the interactive page are for subscribers. Your agent can also search them through the portal's MCP.
Opens when your account has subscriber access
This guide is for subscribers
Once your account has access, the full piece, the interactive visual and the agent call all open.
- Sign in or create a modernEngineer accountReading access belongs to your account email.
- Choose a plan on the pricing page1, 3 or 12 months, paid by VietQR bank transfer. Access opens about a minute after the money arrives.
- Or redeem a Facebook subscriber codePeople supporting the page on Facebook get an activation code by message each month.
Already a subscriber? Sign in to read.
Use this piece in your agent
Get an API keyCopy the text below and paste it into Claude Code, Codex or whichever agent you use. The agent reads the piece and checks it against the repo you have open.
Read "ak-journal: turn a work session into a technical journal" on modernEngineer and apply it to this repo.
1. Call the content_get tool of the modernengineer MCP server with locale "en", slug "ak-journal". If the modernengineer MCP server is not connected, stop and walk me through connecting it from https://modernengineer.dev/en/mcp.
2. Summarize the main steps of the piece and point out which apply to this repo.
3. Propose concrete changes and ask me before editing any file.Connect MCP in Claude Code (once)
claude mcp add --transport http modernengineer \
https://api.modernengineer.dev/mcp \
--header "Authorization: Bearer <API key>"Reading the full piece over MCP needs an API key from a subscriber account or one that bought this guide. Without access, the agent only gets the opening.
- Version
- v1.0.0
- Updated
- 22/10/2026
- Licence
- All rights reserved
- Slug
- ak-journal
