Shayan Rais
6.8 KiB
description, argument-hint
| description | argument-hint | ||
|---|---|---|---|
| Track Claude Code skills report changes and find what needs updating |
|
Workflow Changelog — Skills Report
You are a coordinator for the claude-code-best-practice project. Your job is to launch a research agent, wait for its results, and present a report about drift in the Skills Reference report (best-practice/claude-skills.md).
This workflow checks for exactly two types of drift:
- Frontmatter fields — any field added or removed in the official docs
- Official bundled skills — any bundled skill added or removed
Versions to check: $ARGUMENTS (default: 10 if empty or not a number)
This is a read-then-report workflow. Launch the agent, merge findings, and produce a report. Only take action if the user approves.
Phase 1: Launch Research Agent
Spawn the workflow-claude-skills-agent with this prompt:
Research the claude-code-best-practice project for skills report drift. Check the last $ARGUMENTS versions (default: 10).
Fetch these 2 external sources:
- Skills Reference: https://code.claude.com/docs/en/skills
- Changelog: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
Then read the local report (
best-practice/claude-skills.md).Check for exactly two things:
- Frontmatter fields: Compare the official docs' supported skill frontmatter fields against the report's Frontmatter Fields table. Flag any fields that were added or removed.
- Official bundled skills: Compare the official docs' bundled skills list (and any new bundled skills mentioned in the changelog) against the report's official skills table. Flag any skills that were added or removed.
Phase 2: Read Previous Changelog Entries
While the agent is running, read changelog/best-practice/claude-skills/changelog.md to get the last 25 entries. Parse the priority actions to identify:
- Recurring items — issues that appeared before and are still unresolved
- New items — issues appearing for the first time
- Resolved items — previously flagged issues now fixed
Phase 3: Generate Report
Wait for the agent to complete. Produce a report with these sections:
- Frontmatter Field Changes — Fields added or removed in official docs vs our report
- Official Bundled Skill Changes — Bundled skills added or removed vs our table
End with a prioritized Action Items summary table. Each item must include a Status column showing NEW, RECURRING (first seen: <date>), or RESOLVED:
Priority Actions:
# | Type | Action | Status
1 | New Field | Add <field> to frontmatter table | NEW
2 | Removed Field | Remove <field> from table | RECURRING (first seen: <date>)
3 | New Skill | Add <skill> to official skills table | NEW
4 | Removed Skill | Remove <skill> from table | NEW
Also include a Resolved Since Last Run section listing items from previous runs that are no longer issues.
Phase 3.5: Append Summary to Changelog
This phase is MANDATORY — always execute it before presenting the report to the user.
Read the existing changelog/best-practice/claude-skills/changelog.md file, then append (do NOT overwrite) a new entry at the end. The entry format must be exactly:
---
## [<YYYY-MM-DD HH:MM AM/PM PKT>] Claude Code v<VERSION>
| # | Priority | Type | Action | Status |
|---|----------|------|--------|--------|
| 1 | HIGH/MED/LOW | <type> | <action description> | <status> |
| ... | ... | ... | ... | ... |
Status format — MUST use one of these three formats:
COMPLETE (reason)— action was taken and resolved successfullyINVALID (reason)— finding was incorrect, not applicable, or intentionalON HOLD (reason)— action deferred, waiting on external dependency or user decision
The (reason) is mandatory and must briefly explain what was done or why.
Rules for appending:
- Always append — never overwrite or replace previous entries
- The date and time is when the command is executed in Pakistan Standard Time (PKT, UTC+5); get it by running
TZ=Asia/Karachi date "+%Y-%m-%d %I:%M %p PKT". The version comes from agent findings - If
changelog/best-practice/claude-skills/changelog.mddoesn't exist or is empty, create it with the Status Legend table (see top of file) then the first entry - Each entry is separated by
--- - Only include items with HIGH, MEDIUM, or LOW priority — omit NONE priority items
Phase 3.6: Update Last Updated Badge
This phase is MANDATORY — always execute it immediately after Phase 3.5, before presenting the report.
Update the "Last Updated" badge at the top of best-practice/claude-skills.md. Run TZ=Asia/Karachi date "+%b %d, %Y %-I:%M %p PKT" to get the time, URL-encode it (spaces to %20, commas to %2C), and replace the date portion in the badge. Also update the Claude Code version in the badge if it has changed.
Do NOT log badge updates as action items in the changelog or report. Badge syncing is a routine part of every run, not a finding.
Phase 4: Offer to Take Action
After presenting the report (and confirming both changelog and badge were updated), ask the user:
- Execute all actions — Apply all changes
- Execute specific actions — User picks which numbers to execute
- Just save the report — No changes
When executing:
- New fields: Add to the Frontmatter Fields table with correct type, required status, and description from the official docs
- Removed fields: Confirm with user before removing
- New skills: Add to the official skills table with correct #, skill name, and description
- Removed skills: Confirm with user before removing
- After any additions or removals, update the count in the
## Frontmatter Fields (N)and##  **(N)**headings
Critical Rules
- Never guess versions or dates — use data from the agent
- Cross-reference field counts — report field count must match official docs
- Cross-reference skill counts — report skill count must match official docs
- Don't auto-execute — always present the report first
- ALWAYS append to changelog — Phase 3.5 is mandatory. Never skip it. Never overwrite previous entries.
- ALWAYS update the Last Updated badge — Phase 3.6 is mandatory. Never skip it.
- Compare with previous runs — read the last 25 entries from the changelog and mark each action item as NEW, RECURRING, or RESOLVED.
- Distinguish bundled from installable — only track skills that ship with Claude Code (bundled). Do not track skills from the Official Skills Repository (github.com/anthropics/skills) — those are installable, not bundled.