slice icon Context Slice

Session Watcher Agents

Four specialized agents automatically monitor skill execution and maintain knowledge files. Skills should READ these resources but NOT modify them directly—the watcher agents handle all updates.

The Four Watchers

Agent Maintains Purpose
preference PREFERENCES.md files Detects and updates user preferences (global and skill-specific)
skill-recipe Skill recipes Creates/updates skill workflows based on observed patterns
skill-tool-guide Tool guides Creates/updates API integration guides
cache cache/ directories Stores discovered data (user IDs, channel names, endpoints)

PREFERENCES.md

User preferences are stored in PREFERENCES.md files:

  • Global preferences: Apply across all skills
  • Skill-specific preferences: In each skill's folder, override global settings

The preference watcher detects patterns like "always use Gordon Ramsay voice" and persists them. When a skill's SKILL.md is read, its PREFERENCES.md is automatically loaded too.

Cache Directory

Each skill has a cache/ directory for storing reusable information between runs:

  • User IDs and mappings
  • Channel names and endpoints
  • Team member lists
  • Common queries

Check cache first before making API calls—look in each skill's cache/ folder for user mappings, endpoints, and other reusable data.

Cache vs Preferences:

  • cache/ — Discovered data (objective facts from APIs)
  • PREFERENCES.md — User choices (subjective preferences)

Staleness warning: Cache may be out of date. If information seems wrong or APIs fail, re-fetch the data.

When User Requests Updates

If a user explicitly asks to update preferences, skills, or cache, use the Task tool with the appropriate agent type:

Task(agent_type="preference")    — Update preferences
Task(agent_type="skill-recipe")  — Update skill recipes
Task(agent_type="skill-tool-guide") — Update tool guides
Task(agent_type="cache")         — Update cache files

Describe what needs to be updated; the subagent makes the changes and returns the result.

Implications for Skill Planning

When planning skills that build persistent knowledge:

  1. Don't modify watcher-owned files — Let the watchers handle updates
  2. Read cache before API calls — Avoid redundant requests
  3. Expect preferences to exist — Design for both presence and absence
  4. Use shared locations — Prefer shared state bullets over skill-specific duplicates