The blog lives at https://byronxlg.com/skillfold/blog/, deployed by\n.github/workflows/docs.yml on merge to main.
You write exactly one file. A post is a markdown file in\nsite/blog/posts/ with YAML frontmatter. scripts/build-blog.ts derives\neverything else - the blog index, the post page, the RSS feed, the sitemap,\nand the newest-three list on the landing page. Never hand-edit generated\noutput; it is gitignored and rebuilt on every deploy.
A post touches these files and no others:
\n| File | \nChange | \n
|---|---|
site/blog/posts/<date>-<n>-<slug>.md | \nthe new post (create) | \n
site/index.html | \nonly the generated block, and only via npm run build:blog | \n
docs/blog-todo.md | \nrecord it under Shipped; check off a Queue item if you used one | \n
If you are editing site/blog/index.html, site/feed.xml,\nsite/sitemap.xml, or site/robots.txt, stop: those are build products.
This is not a product blog. A blog that explains skillfold over and over\nis worth nothing to anyone who has not already adopted it, and it is the\ndefault failure mode of dev-tool blogs. Do not write another one.
\nThe blog covers the problem space skillfold lives in: agent\nconfiguration, skill distribution, reproducibility, and the supply chain\nunderneath all of it. That space now generates real news every week. Write\nabout the news. skillfold earns a mention when it genuinely bears on the\nstory, and stays out of the post when it does not.
\nThree post types, in descending order of how often you should write them:
\n| Type | \nTag | \nWhat it is | \n
|---|---|---|
| Current events | \necosystem | \nA real story in the space, and what it means. The default. | \n
| Evergreen | \nconcepts, feature, workflow | \nA durable problem, capability, or task explained. The quiet-week fallback. | \n
| Rollout | \nrelease | \nA large feature shipping. Only when one actually ships. | \n
Scan the beats listed in docs/blog-todo.md for the week's strongest story.\nThe recurring ones:
agentskills.io, AGENTS.md conventions.A story is worth a post when it is verifiable from primary sources and\ngenuinely connected to reproducibility, distribution, or trust in agent\nconfig. Both conditions, not either.
\nDo not force a connection. If the honest read is \"interesting, but it has\nnothing to do with what we know about\", write the evergreen fallback\ninstead. A forced tie-in is more damaging than a quiet week, because it\ntells the reader the blog is an ad.
\nCheck the Shipped list in docs/blog-todo.md first. Do not re-cover a story\nalready written up unless the picture materially changed, and then say what\nchanged and link the earlier post.
Your knowledge cutoff is behind the news. Fetch, do not recall.
\nSource quality is the whole game. The agent-tooling space is saturated\nwith SEO content farms that restate each other, and their numbers drift with\nevery retelling. Rules:
\nTwo failure modes have already shipped and both are subtle. Check for them\nexplicitly before you commit:
\nClaims about skillfold's own behavior are verified differently: never from\nmemory, always from the repo.
\nsrc/resolve.ts for pin reuse and frozen mode,\nsrc/install.ts for managed-directory safety and pruning,\nsrc/compose.ts for composition, src/targets.ts and src/agentsmd.ts\nfor targets and the AGENTS.md block, src/lock.ts for the lockfile shape.docs/manifest.md,\ndocs/cli.md, docs/getting-started.md, docs/publishing.md. If a post\nand the docs disagree, one of them is a bug - resolve it, do not paper\nover it.npx tsx src/cli.ts <command>), never from memory. Use a scratch\ndirectory when the command writes files.If a claim cannot be verified, cut it.
\nFilename: site/blog/posts/YYYY-MM-DD-N-<slug>.md, where YYYY-MM-DD is\ntoday's real date and N orders posts that share a date. A higher N was\npublished later and sits higher on the page, so take the next number above\nthe highest already used for that date (1 if the date is new). Neither the\ndate nor the number appears in the URL, so renumbering never breaks a\npermalink.
---\ntitle: What the reader is trying to understand\ndescription: 140-160 characters stating what the post explains and what the reader leaves with.\ndate: 2026-07-25\ntags: [ecosystem]\n---\ntitle, description, and date are required; the build fails without them.description is 140-160 characters.\": \". YAML reads an unquoted colon-space as\na nested mapping and the build fails. Either quote it\n(description: \"Skills: a primer\") or rewrite the sentence without the\ncolon. This is the single most common way a post fails to build.date must be YYYY-MM-DD and must be today's real date.tags: exactly one of ecosystem (a current story), concepts (how to\nthink about a problem), feature (how a capability works), workflow (a\ntask end to end), or release (a rollout).slug is derived from the filename. Set it explicitly only to keep a URL\nstable when renaming.draft: true keeps a post out of the build entirely.Content rules:
\nrelease post, which is about skillfold by\ndefinition).ecosystem post that means\nsaying plainly what skillfold does not fix about the story. This is the\nsingle biggest thing separating a post developers trust from one they\nbounce off, and it is the first thing to check when reviewing your own\ndraft.## for sections, ### sparingly. The generator gives every heading an id.yaml, sh, ```console). Keep\nlines under about 76 characters or they force a horizontal scrollbar at the\narticle measure. Use console only for real output from a real run.Write one when a feature is large enough to change how someone uses the tool:\na new source kind, a new install target, a breaking change, a major version.\nNot for patch releases or bug fixes - those belong in CHANGELOG.md.
A rollout post must cover: the problem the feature solves, what it looks like\nin the manifest, the migration path for existing users, what it explicitly\ndoes not do, and a link to the reference docs. Tag it release.
npm run build:blog\nThis regenerates the post page, blog index, feed, sitemap, and the landing\npage block. Then:
\nnpm run typecheck and npm test still pass.npx http-server -p 8899 -s site, then check\n/blog/, the new post, and the landing #blog section. Confirm the post\nrenders, prev/next point at real posts, and the landing block lists the new\npost first. Kill the server when done.site/ - it must appear in the generated post\npath, the blog index, the feed, the sitemap, and the landing block.site/index.html is committed, so if build:blog rewrote its generated\nblock (it says so in its output), commit that change with the post.
In docs/blog-todo.md, add a line under Shipped. An ecosystem post's line\nmust name the story, not just the title, so the repeat check can match it:
- [x] <title> (story: <what happened>, <date>) - 2026-07-25, site/blog/posts/<file>.md\nIf you used a Queue topic, check it off too. Shipped is how the next run\navoids re-covering ground, so every published post lands there.
\nBranch blog/<slug>, commit as Blog: <title>, push, and open a PR\ndescribing the story and why it is worth covering.
Open the PR in the same breath as the push. A pushed branch with no PR is\ninvisible: nothing reviews it, nothing deploys it, and the next run will not\nfind it. The first unattended run did exactly this, pushing a finished post and\nthen stopping before gh pr create. Push and open the PR as one step, then do\nany remaining polish on the PR.
The PR is the audit trail and revert point, not a review gate. If the diff is\nonly the post, the landing page's generated block, and docs/blog-todo.md,\nsquash-merge it yourself:
gh pr merge --squash --delete-branch\nIf the diff touches anything else - the workflow, this skill, scripts/,\nsrc/, the manifest - leave the PR open for review and say why in a comment.\nThat boundary is the whole safety model for unattended runs; do not widen it.
When merging from inside a GitHub Actions run, dispatch the deploy afterwards:
\ngh workflow run docs.yml\nPushes made with GITHUB_TOKEN do not trigger other workflows on their own.\nA merge done interactively with a human's gh auth triggers the deploy\nautomatically and needs no dispatch.