Devlog

Devlog

Write and optionally publish build-in-public updates from fresh engineering context. The skill name should stay devlog: short enough to become a habit, but broad enough to cover capture, draft, polish, and publish.

What this skill is

| Skill | Question it answers | Output | |---|---|---| | vd:journal | "What should future-me remember?" | Private markdown journal | | vd:twitter | "How do I read/post on X?" | Tweet/thread/reply via CLI | | vd:devlog | "How do I turn today's work into a public update?" | Draft or published X post |

Devlog is a public writing layer. It gathers facts, shapes the story, applies voice/taste, and delegates posting to vd:twitter only when the user explicitly asks to post/publish.

Argument model

Parse free-form args additively. If args conflict, later/more specific args win.

| Arg | Meaning | Default | |---|---|---| | today | Use current repo/session work from today | yes | | ship | Successful shipped work: what landed, why, next | no | | fix / debug | Bug hunt or incident: symptom, root cause, lesson | no | | lesson | Extract a reusable principle from recent work | no | | idea | Turn a raw thought into a devlog seed | no | | week | Weekly wrap from commits/journals/posts | no | | short | Single post, | Scope git facts from ref to HEAD | merge-base/default | | --topic | User-supplied angle/title | inferred | | --url | Include PR/demo/post URL if relevant | none | | --repo | Gather facts from another repo | current dir | | --project | Devlog vault project bucket for saved artifacts | inferred | | --dry-run` | Show intended post command, do not publish | false |

Examples:

devlog today long post
devlog ship short --url https://github.com/me/repo/pull/42
devlog debug thread blunt --since HEAD~5
devlog lesson polished --topic "worktrees as default isolation"
devlog ship artifact cover --project workflows

Workflow

1. Resolve scope

Use the current repo unless --repo is supplied. If the request mentions a specific PR, issue, commit, plan, or file, include it in the fact set. Use the local date in the session timezone for "today" and state exact dates internally when comparing ranges.

2. Gather facts before writing

Prefer cheap, high-signal commands:

git status --short --branch
git log --oneline --decorate --max-count=12
git diff --stat ..HEAD
git diff --stat

Gather release/version facts when the source is a shipped project:

git fetch --tags --quiet origin  # when network is available
git tag --list 'v*' --sort=-v:refname | head -10
git describe --tags --abbrev=0 2>/dev/null || true
gh release list --limit 10 2>/dev/null || true

Also inspect CHANGELOG.md, release PR titles, package metadata, and version files when present. Prefer the latest shipped release for a release_version fact. If the feature spans several releases, keep the range as a separate body detail. If release facts conflict, say which source won in Facts used.

Also inspect likely context files when present:

• .workbench/features/*/plans/**/plan.md (feature-first) plus legacy .workbench/plans/**/plan.md and plans/**/plan.md, latest phase/report/journal files
• CHANGELOG.md, release notes, PR body, issue text
• recent README.md or docs changes
• command outputs from this session if the user references them

If a PR likely exists, use gh pr view --json number,title,url,state,mergedAt when available. Do not block if GitHub CLI is unavailable.

3. Load taste

Read references/voice.md before drafting. If the current repo has a populated devlog style guide, prefer that too:

references/style-guide.md

Treat empty/stub style guides as no-op.

When working inside the devlog vault and the style guide is empty/stubbed, read 2-4 recent files from vault/projects/*/posts/*.md before drafting. Infer the current house style from those posts and prefer it over the generic examples:

• sectioned long-form notes (what shipped, the thing that clicked, proud,

uneasy, next, quote to self, facts used) when the examples use them;

• lowercase first-person fragments when present;
• concrete artifact bullets before reflective prose;
• explicit facts used at the end when the post depends on verified repos,

PRs, releases, or command output.

Do not copy unsupported metrics or structure from examples blindly. Use the shape and voice; keep facts scoped to the current task.

4. Choose a post shape

Use the source arg to decide structure:

• ship: outcome -> constraint -> decision -> what changed -> next.
• fix / debug: symptom -> false leads -> root cause -> fix -> lesson.
• lesson: concrete moment -> principle -> where it applies -> caveat.
• idea: observation -> why it matters -> small next experiment.
• week: shipped bullets -> learned -> open questions -> next week.
• today: strongest available shape from the facts.

Use the format arg to size it:

• short: one compact post, " --project

uv run pub draft --project --format --body-file uv run pub set-cover --alt "" uv run pub doctor

Vault artifact rules:

- Infer `` from `--project`, then from the central artifact/repo named
  in the post (`dataplanelabs/workflows` -> `workflows`), then current repo
  basename. Use kebab-case.
- Use a concise title derived from the post angle; let `pub new` generate the
  dated id and capture it from command output.
- Put the body in a temp file for `--body-file`. Include `# ` when local
  examples under `vault/projects/*/posts/*.md` use headings.
- Save posts under `vault/projects//posts/.md`.
- Save covers under `vault/projects//assets/-cover.png`.
- Generate a bitmap cover in the same turn when cover is auto/required. Use the
  image generation tool/skill when available, copy the selected output into the
  vault assets directory, inspect it, then attach it with `pub set-cover`.
- Normalize X post covers to `1200x675` PNG (16:9) by default, keep important
  content centered, and keep the file under 5 MB. If generation returns another
  size, resize/crop/extent before `pub set-cover`; use `1600x900` only when the
  user explicitly asks for a higher-resolution cover.
- If image generation is unavailable, create the post anyway and clearly say the
  cover is the only missing artifact.
- Run `uv run pub doctor` before final response.

When the vault CLI is absent or the current directory is not a devlog vault,
fall back to text-only output and say no vault artifact was created.

### 8. Publish when requested

Only publish when args include the verb `publish`, or the user explicitly says
to post/start it on X now. Do not treat "write a post", "draft a post", or
"make a post about this" as publishing permission. Otherwise return or save the
draft only.

Use `vd:twitter` CLI:

```bash
twitter doctor --offline
twitter post "$(cat /tmp/devlog-post.txt)"          # short,  280 chars
twitter thread "$(cat /tmp/devlog-1.txt)" "$(cat /tmp/devlog-2.txt)"

If twitter post fails with automation/API drift, follow vd:twitter failure modes and retry with --use-browser when appropriate. With --dry-run, print the command that would run and stop.

After posting, return the X URL/ID from the command output. If the CLI posts but does not return a URL, fetch the latest user timeline and identify the matching post.

Output

For text-only draft, return:

Draft (, , )

Facts used: 

For vault/artifact draft, return:

Draft saved: 
Cover saved: 
Idea note: 
Validation: 
Facts used: 

For post, return:

Posted: 
Format: 
Facts used: 

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vanducng
• Source: vanducng/skills
• License: MIT
• Homepage: https://skills.vanducng.dev

Install and usage instructions live in the source repository linked above.