agentleFS
haxsdhaxsd/haxsd-byok/.agents/skills/cursor-prefix-stability/SKILL.md

cursor-prefix-stability

Skill33 starsChanged 34 days agoMITView on GitHub

Implement and review Cursor BYOK conversation projection with append-only provider history and prefix-cache stability. Use when changing runtime prompts, request context, canonical messages, checkpoint hydration, compaction, message identity, or provider history serialization under server.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. leookun/cursor-byok★ 3.2k100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository7 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 10 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Keep the invariant in the provider-independent conversation layers:

    line 12
  2. Distinctive:

    Do not solve prefix instability independently in each provider adapter.

    line 24
  3. Distinctive:

    When no compaction occurs, the complete provider-visible history from turn N must be an exact structural prefix of turn N+1.

    line 28
  4. Very specific:

    Keep PromptSpec.instructions and the stable tool prefix byte-stable when their inputs have not changed.

    line 29
  5. Distinctive:

    do not append it again when its compiled content is identical to the latest projected request context.

    line 33
  6. Distinctive:

    when its content changes, append a new request-context message immediately before the current runtime message.

    line 34
  7. Distinctive:

    never represent a context change by rewriting the system prompt, replacing an earlier context message, or mutating a checkpoint root.

    line 35
  8. Distinctive:

    Before editing, trace the whole path that applies:

    line 43
  9. Distinctive:

    Use TDD for changes in this path.

    line 56
  10. Distinctive:

    Run focused tests first, then the relevant server suites:

    line 70
  11. Distinctive:

    Do not repair unrelated dirty-worktree failures while validating.

    line 82

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Cursor prefix stability

Preserve the longest valid provider prefix across turns. Treat provider-visible history as an append-only log unless an explicit compaction operation replaces it.

Architecture

Keep the invariant in the provider-independent conversation layers:

server/
├── prompt/cursor/*/runtime.md       Per-turn runtime content
├── src/cursor/request/              Request context and runtime compilation
├── src/cursor/projection/           Canonical ↔ Cursor checkpoint projection
├── src/cursor/checkpoint/           Stable roots, turns, and hydration
├── src/run/                         Provider-independent model history
└── src/provider/                    Provider-specific serialization only

Do not solve prefix instability independently in each provider adapter. Produce one stable canonical history before dispatching to OpenAI Responses, OpenAI Chat, Anthropic, or another provider.

Required invariants

  • When no compaction occurs, the complete provider-visible history from turn N must be an exact structural prefix of turn N+1. Never edit, remove, merge, reorder, renormalize, or regenerate an earlier message.
  • Keep PromptSpec.instructions and the stable tool prefix byte-stable when their inputs have not changed. Deterministic ordering is required; do not use unordered iteration in provider-visible output.
  • Separate conversation/request context from the per-turn runtime message. The runtime message contains current-turn material such as the user query, selected context, open files, action context, mode reminders, and timestamp.
  • Project rules, skills, subagents, environment/Git context, and MCP metadata as a stable request-context:* message:
    • append it on the first applicable turn;
    • do not append it again when its compiled content is identical to the latest projected request context;
    • when its content changes, append a new request-context message immediately before the current runtime message;
    • never represent a context change by rewriting the system prompt, replacing an earlier context message, or mutating a checkpoint root.
  • Give every appended context update a unique event identity. Compare the latest context by content, not only by identifier, so A → B → A appends the final A again while retries of the same event remain idempotent.
  • Preserve request-context:* wire identity through checkpoint encoding and hydration. Deduplication must still work after process restart or conversation resume.
  • Automatic compaction is an explicit prefix reset. Compact obsolete history, retain exactly the latest request-context message, then place the summary and current initial messages in deterministic order. Manual compaction may reproject current context on the next user turn.
  • Background completions and injected runtime events must not manufacture duplicate request context unless they actually start a user turn whose context changed.

Change workflow

Before editing, trace the whole path that applies:

AgentRunRequest
→ request context hydration/compilation
→ CanonicalMessage identity and persistence
→ checkpoint encode/decode
→ projected ModelRequest history
→ provider serialization

Determine which data is conversation-level and which is turn-level. If a proposed change moves or rewrites an earlier provider-visible value, redesign it as a new append-only event unless the operation is explicitly compaction.

Use TDD for changes in this path. Start with a failing behavioral test, then implement the smallest provider-independent change.

Verification

Cover the affected behavior with structural assertions, not token-count estimates alone:

  • Two turns with identical request context: the first request history is an exact prefix of the second, the system instructions are identical, and only one request-context:* message exists.
  • Changed context: one new context message appears at the tail before the new runtime query; all earlier messages remain unchanged.
  • Context reversion A → B → A: three distinct context events are retained in order.
  • Retry of one runtime event: no duplicate or conflicting context message is persisted.
  • Checkpoint round-trip: request-context identity and content survive encode/hydrate.
  • Automatic compaction: only the latest context is retained outside the summary.
  • Runtime templates render without embedding conversation-level rules or MCP metadata in every user query.

Run focused tests first, then the relevant server suites:

cargo test --lib
cargo test --test runtime_modes
cargo test --test prefix_stability
cargo test --test checkpoint_recovery
cargo test --test compaction
cargo clippy --lib -- -D warnings
cargo fmt --all -- --check

Do not repair unrelated dirty-worktree failures while validating. Report them separately.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.