feat(blog): SKILL.md vs AGENTS.md vs CLAUDE.md + SKILL.md format rewrite (THE-2255, THE-2259)

Merged
ST
8h ago
+204-21

Content PR for the skillpack.app blog. Linear THE-2255 (new article) and THE-2259 (rewrite of /blog/what-is-skill-md), shipped together so the two posts cross-link in one preview.

1. New post — THE-2255

apps/web/content/blog/skill-md-vs-agents-md-vs-claude-md.md

Which of the three instruction files an agent actually reads, when each one loads, and a rule for deciding where a given line belongs. Takeaways box, three comparison tables, a 7-question FAQ (rendered as disclosures + FAQPage JSON-LD, same renderer as the other posts) and two /login CTAs. Uses the standard skillpack cover (drawn CSS BlogCover + opengraph-image.tsx), like the other posts.

Every loading rule is sourced to the official Claude Code, Codex, agents.md or Agent Skills docs, read on 2026-11-09. The claim that this repo symlinks AGENTS.md → CLAUDE.md was checked against the repo.

2. Rewrite — THE-2259

apps/web/content/blog/what-is-skill-md.md is replaced. New title and description, a new ## SKILL.md format specification H2 with field-by-field, naming/limits, cross-agent-fields and validation sub-sections, two new FAQ items, and three links to the new article. Slug, date and tags are unchanged, so no redirect is needed.

The in-page anchor #skillmd-format-specification was verified against the rendered page: the heading slugger drops the dot, so the link resolves as written.

3. Cross-links

One sentence each in how-to-create-a-claude-code-skill.md and agent-skills-open-standard-vs-vendor-folders.md.

Test changes (not planned, but required)

The rewritten post is the live fixture for the blog tests, so the renamed title, the new description and the body checksum had to move with it:

  • apps/web/src/lib/blog.test.ts — title + sha256 of the body
  • apps/web/src/app/blog/[slug]/page.test.ts — H1, JSON-LD headline/description, metadata
  • apps/web/src/app/blog/page.test.ts — card title, cover title, description
  • apps/web/src/components/landing/LandingPage.tsx — the home page's "From the blog" label for that post still advertised it as "the complete guide to Agent Skills"

The LandingPage.tsx line is the only runtime change; it pulls the Browser and Containers lanes into CI scope. Happy to drop it if you'd rather keep this PR to content plus tests.

Verification

  • pnpm verify:change — hygiene, anti-slop, quality (lint + typecheck + 860 tests) and build all pass. Exit 2 with the usual two follow-up gates (browser smoke, container smoke), both covered by CI.
  • Local production build: /blog, /blog/skill-md-vs-agents-md-vs-claude-md, /blog/what-is-skill-md and /sitemap.xml all return 200.
  • Sitemap goes 24 → 25 URLs, both posts listed; the new post appears on /blog.

🤖 Generated with Claude Code

Summary by cubic

Adds a new blog post comparing AGENTS.md, CLAUDE.md and SKILL.md, and rewrites the what-is-skill-md guide around the format specification (THE-2255, THE-2259). The two posts ship together so they cross-link in one preview.

Changes

  • The new post explains what each instruction file does, who reads it, when it loads, and where a given instruction belongs, with comparison tables and a 7-question FAQ.
  • The rewrite replaces the old title and description and adds a SKILL.md format specification section covering fields, naming rules and size limits, cross-agent fields, and validation. Slug, date and tags are unchanged, so no redirect is needed.
  • how-to-create-a-claude-code-skill and agent-skills-open-standard-vs-vendor-folders link to the new post.

Test updates

  • The rewritten post is the live fixture for the blog page, index, SEO and checksum tests, so expected titles, descriptions and the body hash move with it; the home page "From the blog" label is the only runtime change.