---
name: context-cache-skill
description: Use when building or updating a persistent context cache file where content should be stored in clearly separated blocks and later updates should append new blocks and refer to earlier ones by block marker.
---

# Context Cache Skill

Use this skill when you are generating or updating a context cache document that will accumulate content over time.

Read this skill before you write context content to the LLM backend.

Reference example:

- See `references/context_cache_example.md` for a simple append-and-reference example.

## Core Rule

- Store each content unit in its own clearly separated block.
- Use a distinct separator line exactly as:

```text
=======
```

- Treat each `=======` section as one addressable content block.
- Every block should include an explicit block index such as `BLOCK_ID: 001`.
- Use zero-padded ascending numbers so later blocks can cite earlier blocks precisely.
- Never renumber an existing `BLOCK_ID` once it has been written.
- Assign new `BLOCK_ID` values only to newly appended blocks.
- Fields like `Project:` and `Topic:` are optional metadata, not required structure.
- The agent may decide how to separate blocks based on what makes retrieval and updates clearer.
- Valid separation strategies include time, project, topic, session, or another practical grouping rule that fits the content.
- Prefer stable semantic groupings first, such as project or topic.
- Use time- or session-based grouping when the context is naturally chronological or conversational.

## Writing Format

- When creating a new cache file, write content as sequential blocks separated by `=======`.
- Start each block with a `BLOCK_ID` field.
- Add optional metadata fields only when they help readability or retrieval.
- Choose block boundaries deliberately. A block may represent a time slice, a project update, a topic cluster, a session summary, or another useful unit.
- Keep each block self-contained enough that later updates can refer back to it.
- Prefer appending new blocks over rewriting older blocks unless the task explicitly requires replacement.

## Updating Format

- When updating an existing cache file, add the new content as a new block after the existing content.
- Do not merge unrelated new content into an older block.
- When the new block depends on or extends an earlier block, explicitly refer to that earlier block by its `BLOCK_ID` in the new content.
- If an earlier block is outdated, incorrect, or superseded, append a correcting block instead of rewriting the older one unless full replacement is explicitly required.
- The reference can be plain language such as:
  - `Refers to BLOCK_ID: 001 about ...`
  - `Update to BLOCK_ID: 002 on ...`

## Intent

- The separator makes content boundaries obvious.
- The block index makes later citation precise.
- Later updates stay append-only and traceable.
- References between blocks make it easier to understand how newer context extends older context.

## Dynamic Optimization And Monitoring

- Monitor backend responses for cache effectiveness, including cached ratio when that signal is available.
- If the cached ratio drops dramatically, treat that as a sign that the fixed context may no longer be structured well for reuse.
- A practical default is to investigate when the cached ratio drops by more than 30% versus the recent baseline over several comparable requests.
- In that case, review the current cached content layout and regenerate or reorganize the fixed context blocks.
- When regenerating fixed context, prefer improving block boundaries, citations, and stable shared content before adding more text.
- Use the same block-based format after regeneration so future cache behavior remains observable and comparable.
