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:

=======

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.

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:

=======

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.

context-cache-skill