jamesgray-ai/publishing-playbook-updates

Publishing Playbook Updates

Draft a curated changelog entry from recent git history, get approval, publish it, and notify Slack.

Workflow

1. Find the last changelog entry date

   Look at the most recent file in docs/blog/posts/ to determine the date range. Use the date from the filename (format: YYYY-MM-DD-slug.md).

2. Scan recent changes

   Run:

   git log --oneline --since="YYYY-MM-DD" -- docs/ plugins/ .claude/
   git diff --stat HEAD~30 -- docs/ plugins/ .claude/
   

   Group changes by category:

   • New Content — New pages added to docs/
   • Plugins — Changes to plugins/ or .claude/skills/ or .claude/agents/
   • Platform Updates — Changes to docs/platforms/
   • Builder Setup — Changes to docs/builder-setup/
   • Courses — Changes to docs/courses/

3. Filter for signal

   Ignore:

   • Typo fixes, formatting tweaks, whitespace changes
   • Sidebar-only changes in astro.config.mjs
   • CI/CD config changes (.github/)
   • Script changes (scripts/)
   • CSS-only changes
   • Changes to src/components/ (layout-only)

   Surface:

   • New documentation pages
   • New or updated plugins, agents, skills
   • Significant content rewrites (not minor edits)
   • New questions answered
   • New resources added

4. Draft a changelog entry

   Create a draft with this structure:

   ---
   date: YYYY-MM-DD
   authors:
     - jamesgray
   categories:
     - <category>
   description: "<one-line summary of the update>"
   ---
   
   # <Headline summarizing the theme>
   
   <2-3 sentence overview of what changed and why it matters.>
   
   <!-- more -->
   
   <Details for each notable change — 2-4 sentences each with links to the new/changed pages.>
   

   Rules:

   • Filename format: docs/blog/posts/YYYY-MM-DD-<slug>.md
   • Use today's date
   • Keep it short and scannable — this is a changelog, not a blog post
   • Link to the actual playbook pages using relative paths (e.g., ../../agentic-building-blocks/agents/index.md)
   • If a related Substack article was published, cross-reference it
   • Categories: New Content, Plugins, Platform Updates, Builder Setup, Courses, Announcements
   • Multiple categories can be listed if the update spans areas

5. Present for review

   Show the full draft to James. Ask:

   "Here's the draft changelog entry. Want to adjust anything before I publish it?"

   Wait for approval. James may:

   • Approve as-is
   • Edit the content (make the changes he requests)
   • Add context ("this was built because a student asked...")
   • Reject (stop here)

6. Create the file

   Write the approved entry to docs/blog/posts/YYYY-MM-DD-<slug>.md.

7. Commit and push

   Commit the new changelog entry and push to main. The site deploys automatically via CI, and the RSS feed updates with the new entry.

8. Notify Slack

   After the commit is pushed (so the link is live), run the Slack notification script:

   ./scripts/notify-slack.sh "<title>" "<one-line summary>" "https://handsonai.info/blog/YYYY/MM/DD/<slug>/"
   

   The script loads .env automatically. If the webhooks are not configured, it will skip with a message — remind James to set SLACK_WEBHOOK_1 and SLACK_WEBHOOK_2 in .env at the project root.

Important Notes

• This skill is for James only — it is not published to the plugin marketplace
• The changelog is the single source of truth for updates — homepage, RSS, and Slack all derive from it
• Long-form content goes on Substack, not the changelog
• Always wait for explicit approval before writing the file