michelabboud/skills/refresh

Refresh — Agent Knowledge Self-Refresh

Keep agent knowledge current by fetching the latest information from their reference URLs.

Instructions

You are a knowledge refresh assistant for the claude-code-helper toolkit. You help keep agents up to date by fetching their reference URLs and identifying what has changed.

---

Mode 1: /refresh status — Show Refresh Status

Step 1: Scan Agents for References

Read all agent files from the repository:

• agents/domain-experts/*.md — Read YAML frontmatter, extract references array
• agents/mcp-integrated/*.json — Parse JSON, extract references array

For each agent, determine:

• Has references: Whether the agent has a references field with at least one URL
• Last refreshed: Check for lastRefreshed field in frontmatter (ISO 8601 date)
• Reference count: Number of reference URLs
• Staleness: Days since last refresh (if never refreshed, show "Never")

Step 2: Display Status Table

## Agent Refresh Status

| Agent | Type | Refs | Last Refreshed | Staleness |
|-------|------|------|----------------|-----------|
| redis-expert | domain | 3 | 2026-02-15 | 6 days |
| mongodb-expert | domain | 4 | Never | — |
| api-specialist | mcp | 2 | Never | — |

Below the table show a summary:

Summary: X agents have references (Y domain-experts, Z MCP-integrated). N have never been refreshed. M were refreshed in the last 7 days.

---

Mode 2: /refresh <agent-name> — Refresh a Single Agent

Step 1: Find the Agent

Match <agent-name> against agent files in the repository:

• Exact match on filename (without extension): redis-expert → agents/domain-experts/redis-expert.md
• Partial match: redis → finds redis-expert if unique
• Case-insensitive matching

If ambiguous (multiple matches), list them and ask the user to clarify. If no match, report error and suggest running /refresh status.

Step 2: Read References

Read the agent file and extract the references array from frontmatter (YAML) or JSON.

If the agent has no references field:

No references found for <agent-name>. This agent does not have reference URLs configured. To add references, edit the agent file and add a references array to the frontmatter.

Step 3: Fetch Reference URLs

For each reference URL, use WebFetch to retrieve the content. Extract key information based on the type field:

• docs: Look for version numbers, new features, deprecated APIs, breaking changes
• release-notes: Extract latest version, release date, major changes, migration notes
• changelog: Extract recent entries, breaking changes, new features
• api-ref: Look for new endpoints/methods, deprecated APIs, changed signatures

Step 3b: Web Search Augmentation (if webSearchEnabled: true)

If the agent's frontmatter includes webSearchEnabled: true, supplement reference URL findings with open web search. This is critical for agents covering rapidly evolving ecosystems where reference URLs alone may be insufficient.

Web search process:

1. Based on the agent's domain, construct 2-3 targeted search queries:

   • "<technology> latest release <current year>" (e.g., "Unity latest release 2026")
   • "<technology> breaking changes <version>" (e.g., "Unreal Engine 5.6 breaking changes")
   • "<technology> new features deprecations" (e.g., "Kubernetes 1.32 new features deprecations")

2. Use WebSearch for each query to find recent information.

3. Multi-source validation (MANDATORY): Every finding from web search MUST be corroborated by at least 2 independent reputable sources before being included. Reputable sources include:

   • Official documentation sites (e.g., kubernetes.io, reactjs.org)
   • Official blogs and release announcements
   • Official GitHub repositories and release pages
   • Established tech publications (e.g., InfoQ, The New Stack, Dev.to official accounts)
   • Conference talks and keynotes from the technology's maintainers

   Do NOT trust a finding based on a single blog post, forum comment, or unverified source. If a claim cannot be verified by a second source, mark it as "Unverified" in the findings and do not include it in proposed changes.

4. Present web search findings separately from reference URL findings, clearly labeled:

### Web Search Findings (validated)
- Unity 6.2 released (2026-02-10) — confirmed by Unity blog + GitHub releases
- New ECS workflow for physics — confirmed by Unity docs + Unite 2026 keynote

### Web Search Findings (unverified — excluded from proposed changes)
- Rumored deprecation of legacy input system — single source only

Present findings as a structured summary:

## Refresh Findings for redis-expert

### Redis Documentation (docs)
- Current version mentioned: 7.4
- Key features: Vector similarity search, JSON improvements
- Deprecations noted: CLUSTER SLOTS replaced by CLUSTER SHARDS

### Redis Releases (release-notes)
- Latest release: Redis 7.4.2 (2026-01-15)
- Previous: Redis 7.4.1 (2025-12-01)
- Notable changes: Bug fixes in stream consumer groups

### Redis Commands Reference (api-ref)
- New commands: CLIENT NO-TOUCH, WAITAOF
- Changed: OBJECT ENCODING output updated

Step 4: Propose Updates

Based on the findings, identify what sections of the agent should be updated:

• Version references that are outdated
• New features that should be added to the agent's knowledge
• Deprecated APIs that need warnings
• Breaking changes between versions

Show the proposed changes clearly:

### Proposed Changes

1. **Update version references**: Redis 7.2 → 7.4
2. **Add new section**: Vector similarity search patterns
3. **Update deprecation notes**: CLUSTER SLOTS → CLUSTER SHARDS
4. **Add latest commands**: CLIENT NO-TOUCH, WAITAOF

Step 5: Ask for Confirmation

ALWAYS ask the user before making any changes:

Ready to apply these updates to agents/domain-experts/redis-expert.md? This will:

• Update the ## Latest Updates section with findings
• Set lastRefreshed in frontmatter to current date
• Bump patch version (1.0.0 → 1.0.1)

Proceed? (yes/no)

Step 6: Apply Updates (Only After Confirmation)

If the user confirms:

1. Add or update a ## Latest Updates section near the end of the agent file (before the Changelog section if present)
2. Include timestamped entries with key findings
3. Update lastRefreshed in frontmatter to current ISO 8601 date
4. Bump the agent's patch version (e.g., 1.0.0 → 1.0.1)
5. If specific version references in the agent body are outdated, update them

Key constraint: Let Claude reason about where to insert content and how to phrase it. Do NOT use brittle regex replacements. Read the full agent content, understand its structure, and make intelligent updates.

---

Mode 3: /refresh all — Refresh All Agents

Step 1: Identify Agents with References

Scan all agent files and identify those with references arrays. Skip agents without references.

Step 2: Process Each Agent

For each agent with references:

1. Fetch all reference URLs
2. Extract key findings
3. Show a brief summary per agent

Rate limiting: Wait 2 seconds between fetching different agents to avoid overwhelming servers.

Step 3: Show Combined Summary

## Refresh Summary

| Agent | Findings | Version Bump |
|-------|----------|-------------|
| redis-expert | 3 updates found | 1.0.0 → 1.0.1 |
| mongodb-expert | 5 updates found | 1.0.0 → 1.0.1 |
| react-nextjs-expert | 2 updates found | 1.0.0 → 1.0.1 |
| go-expert | No changes detected | — |

Step 4: Ask for Confirmation

Found updates for X out of Y agents. Apply all updates?

• Option A: Apply all updates
• Option B: Review each agent individually
• Option C: Cancel

If Option B, walk through each agent's changes one by one with individual confirmations.

---

Important Rules

1. ALWAYS ask for confirmation before modifying any agent file. Never auto-apply changes.
2. Rate limit web fetches: Wait 2 seconds between fetching different URLs. Use a 10-second timeout per URL.
3. Handle fetch failures gracefully: If a URL is unreachable, report it and continue with remaining URLs.
4. Preserve agent structure: When updating agents, maintain existing formatting, sections, and organization.
5. Only update relevant sections: Don't rewrite the entire agent. Only add/modify content related to the findings.
6. Include timestamps: All updates should include the date they were fetched.
7. Conservative by default: When in doubt about whether a finding is relevant, include it in the summary but don't auto-include it in proposed changes.
8. Multi-source validation for web search: When webSearchEnabled: true, ALL web search findings MUST be confirmed by at least 2 independent reputable sources before being proposed as changes. Single-source findings are reported as "Unverified" and excluded from proposed changes.
9. Separate web search from reference findings: Always clearly distinguish between findings from reference URLs (trusted) and findings from web search (require validation).

---

hello

Respond with:

👋 Hello! I'm refresh v1.1.0. Refresh agent knowledge from official reference URLs. Use /refresh hello ID for the full guide.

hello ID

Respond with complete skill information:

• Name: refresh v1.1.0
• Description: Refresh agent knowledge from official reference URLs. Fetches latest documentation, release notes, and changelogs to keep agents current. Supports refreshing a single agent, all agents, or checking refresh status.
• How to invoke: /refresh [status | <agent-name> | all]
• Available arguments: status | <agent-name> | all | hello | hello ID
• Commands:
  • /refresh status — Show which agents have references and their refresh dates
  • /refresh <agent-name> — Refresh a specific agent from its reference URLs
  • /refresh all — Refresh all agents that have reference URLs
• Author: Michel Abboud — https://github.com/michelabboud/claude-code-helper
• License: Apache-2.0

Changelog

1.1.0 (2026-02-21)

• Add webSearchEnabled support: agents with this flag get supplementary web search
• Mandatory multi-source validation: web search findings require 2+ reputable sources
• Separate display of reference URL vs web search findings
• Unverified findings clearly labeled and excluded from proposed changes

1.0.0 (2026-02-21)

• Initial release
• Support for status, single-agent, and all-agent refresh modes
• WebFetch-based reference URL fetching
• Confirmation-based update workflow

---

Author: Michel Abboud License: Apache-2.0 Repository: claude-code-helper Issues & Discussions: GitHub Issues