open-source-website: Skill for Claude Code

Run the blog post validation script and help the user fix any issues found.

Step 1: Identify the post

If the user provided a path in their request, use that. Otherwise, look for blog posts changed on the current branch:

git diff --name-only --diff-filter=d origin/main...HEAD -- 'content/blog/**/index.md' 'content/blog/**/index.qmd'

If no changed posts are found, ask the user which post to check.

Step 2: Check for unrendered .qmd files

For each post directory found, check if an index.qmd exists. If it does, check whether index.md also exists and is newer than index.qmd:

# For each post directory
if [ -f index.qmd ] && { [ ! -f index.md ] || [ index.qmd -nt index.md ]; }; then
  echo "index.qmd has not been rendered to index.md (or is out of date)"
fi

If any .qmd files need rendering, warn the user and always offer to re-render — even if there is no computational environment setup. To render:

quarto render <path>/index.qmd

.qmd posts may need to render through a specific environment — check the post folder for a pyproject.toml, renv.lock, or similar, and use whatever tool the author set up. See the "Setting up an environment" section of content/blog/_authoring-guide.md for context.

Do not proceed with validation until index.md exists and is up to date for all posts.

Step 3: Run validation

The validation script reads index.md files (not .qmd):

uv run scripts/validate-blog-posts.py <paths to index.md>

Step 4: Report results

If all checks pass, say so and stop.

If there are issues, summarize them clearly grouped by severity:

• Errors need fixing before the post can be published.
• Warnings are worth reviewing but won't block publishing — and some are reasonable to leave alone (see below).

For each error, explain what's wrong and suggest a concrete fix. For example:

• Missing topics → suggest values from data/topics.yaml that fit the post content
• Unknown software → check if there's a close match in content/software/. If there isn't one, suggest moving it to other_software, which shows it as a greyed-out, non-clickable pill without creating a page. If the software should get its own page, offer to create one using scripts/create-new-software.py.
• Unknown people → check if there's a close match in content/people/. If there isn't one, offer to create a new people page.
• Missing source on a ported post → suggest setting it to match ported_from
• categories present → replace with topics