devlog-skill

A Claude Code skill (plus a vendor-neutral schema any coding agent can follow) for keeping a per-project development log: ideas, technical discussions, decisions, bug fixes, and progress, auto-classified per project and distilled straight out of your conversations with a coding agent.

This repo is the installable skill — it does not contain your actual log data. The log itself lives in a separate repo (your own private one) that you bootstrap from template/.

What's in here

Path	Role
SKILL.md	The Claude Code skill definition. Install it into ~/.claude/skills/devlog/.
template/AGENTS.md	The schema layer — tells any agent how to Archive, Recall, Query, and Lint. Vendor-neutral, read by Claude Code, Codex, Cursor, Gemini, etc.
template/CLAUDE.md	Symlink to AGENTS.md (Claude Code looks for this filename specifically).
template/index.md	Empty global catalog — one row per project, filled in as you go.

There's no projects/ folder in the template — it doesn't exist yet. Git can't track empty directories, and the whole point is that the agent creates projects/<slug>/ lazily the first time you archive something for that project.

Quickstart

1. Bootstrap your devlog repo (a new, separate repo — this is where your actual notes will live):

   mkdir -p ~/devlog
   cp template/AGENTS.md template/index.md ~/devlog/
   ln -s AGENTS.md ~/devlog/CLAUDE.md
   cd ~/devlog && git init

2. Install the skill (Claude Code):

   mkdir -p ~/.claude/skills/devlog
   cp SKILL.md ~/.claude/skills/devlog/SKILL.md

   If your devlog repo isn't at ~/devlog, adjust the path mentioned in SKILL.md.

3. Other agents (Codex, Cursor, Gemini, ...): no skill install needed — just tell the agent, in any project directory: "Read ~/devlog/AGENTS.md, then archive this discussion." Every rule the agent needs lives in that one file.

How it works

Four operations, all triggered by talking to your agent in any project directory.

1. Archive (the one you'll use most)

After a work session — a design discussion, a debugging hunt, a milestone — say:

"Archive this discussion" / "Save this to the devlog" / "Log how we fixed this bug"

The agent identifies the project (cwd name → slug, first time auto-creates the dir), distills the conversation, classifies items into decisions/ bugs/ ideas/ notes/, refreshes the project index.md (current status + next steps), appends to log.md. No need to specify a category — it decides.

2. Recall (back to a project after days away)

"Where did we leave off on my-project?" / "What did we do last time?"

The agent reads the project's index.md hub and reports: status, next steps, open bugs.

3. Query (can't remember a decision or a fix)

"Why did we pick SQLite back then?" / "How did we fix that download-freeze bug?"

Answers cite the exact pages used.

4. Lint (occasionally)

"Lint the devlog"

Sweeps for stale statuses, contradictions, and orphaned pages.

Everything is plain markdown — no proprietary SDK, no account, consumable by any agent that can read AGENTS.md.

See template/AGENTS.md for the full schema and conventions.