context-pack（上下文包）

Context Pack

Store and retrieve context through Epismo context packs — so knowledge survives tool switches, session ends, and team handoffs.

The unit of organization is a block inside a pack. The goal is one well-structured pack per topic, grown over time by adding and refining blocks — not many small packs.

For Epismo connection setup, CLI/MCP surface conventions, scope model, share URL resolution, and error handling, see Epismo Basics.

Surface selection: CLI and MCP connect to the same Epismo service. Use CLI if available; fall back to MCP if not. Never use both in the same session.

Commands

Operations (context packs)

PACK

Goal: save current context as a block inside the right pack. Find an existing pack and add or refine a block; create a new pack only when nothing relevant exists.

Step 1 — Find the right pack

Infer 2–4 topic keywords from the current session. Search private packs (titles only — one fast call).

search pack — type: context, query: <inferred topic>, filter: {visibility: ["private"]}

Step 2 — Identify the right block

get pack — fetch the pack and read its existing blocks. Decide:

• Update an existing block — if the new content belongs to a block that already exists (e.g., decisions, next steps), integrate it there. Rewrite the block so it reads as a coherent whole, not as an append.
• Add a new block — if the new content is a distinct topic not covered by any existing block.

The pack should read well from scratch at any point. Do not leave stale or contradicted information in place.

Step 3 — Update and return

update pack:

{
  "id": "<existing-id>",
  "content": "<top-level summary or intro — does not include block content>",
  "blocks": [
    { "op": "update", "id": "<existing-block-id>", "title": "<block-title>", "content": "<updated block content>" },
    { "op": "add", "title": "<new-block-title>", "content": "<new block content>" }
  ]
}

• Omitted fields are left unchanged. Omitting "blocks" means no block changes.
• "op": "update" updates an existing block by ID. "op": "add" adds a new block. "op": "remove" deletes a block by ID (only "id" needed).
• "content" at the top level is a brief intro or summary. Block content lives in "blocks[]", not in the top-level "content".

context  <context-id>  <context-title>
block    <block-id>    <block-title>

NEW

Goal: create a fresh pack with an initial block structure. Use when no relevant pack exists, or when the content is clearly a separate topic.

Step 1 — Design the block structure

Before writing, decide how the content divides into blocks. Each block should be focused enough to update independently and broad enough to stay relevant over time.

Design for selective fetch. Because blocks can be loaded individually with --block-id, a well-split pack lets future sessions load only what they need without pulling the whole pack. Aim for blocks where any one block answers a distinct question on its own.

Good block boundaries: topic changes, audience changes, or update frequency changes (e.g., "Decisions" is stable; "Next Steps" changes every session — keep them separate).

For templates, see Content Templates.

Step 2 — Write

Content rules:

• Each block is self-contained — no "see above" references
• Prefer scannable structure: bullets, short paragraphs, and small tables only when they help
• Include IDs, URLs, and precise names so the reader can act without searching
• Title: infer from session topic. Do not ask unless genuinely ambiguous.

Step 3 — Publish

Default private. Use PUBLISH to go public.

create pack:

{
  "title": "<title>",
  "content": "<top-level summary or intro>",
  "type": "context",
  "visibility": "private",
  "blocks": [
    { "title": "<block-title>", "content": "<block content>" },
    { "title": "<block-title>", "content": "<block content>" }
  ]
}

• Blocks are passed as a separate "blocks[]" array — not embedded in the top-level "content" string.
• "content" at the top level is a brief intro only. All substantive content belongs in blocks.

context  <context-id>  <context-title>
block    <block-id>    <block-title>

PUBLISH

Goal: make a pack publicly discoverable. Always requires explicit user confirmation before writing.

Two paths:

Promote: private → public

1. get pack — fetch the pack. Run the Public Review Gate. Flag issues before proceeding.
2. Confirm with user: "Publish '{title}' ({id}) as public under category {category}?"
3. update pack:

{
  "id": "<id>",
  "visibility": "public",
  "category": "<category>"
}

Create new public

Write for an external reader using the public guide template in Content Templates. Content must be self-contained and pass the Public Review Gate.

Choose category carefully — it determines how people find this pack. See Category Reference.

Confirm with user, then create pack:

{
  "title": "<title>",
  "content": "<content>",
  "type": "context",
  "visibility": "public",
  "category": "<category>"
}

Return ID, title, and share URL. For share URL resolution, see Epismo Basics — Resolving Share URLs.

context  <context-id>  <context-title>
share    https://epismo.ai/hub/contexts/<id>

GET

Goal: fetch a pack by ID, alias, or explicit read/open target.

Route intent before resolving

Prefer alias-first unless the input is obviously a search query.

Resolve the input

1. UUID → get pack --id.
2. @handle/name or one compact token like weekly-handoff → get pack --alias; if it misses, run FIND with the same text.
3. Short phrase like auth refactor handoff → try get pack --alias first; if it misses, run FIND.
4. Question, explicit search wording, or long descriptive text → FIND first.
5. get/read/open/use <target> always counts as retrieval intent.

get pack — by id, or by alias. Default returns outline only; pass --full for all blocks, or --block-id to load a single block.

Read the most relevant block first. Continue from there without re-reading history.

FIND

Goal: discover the right pack when the ID is not known.

search pack — scan titles only (no full content). Use this for natural-language discovery requests and multi-keyword topic phrases. Search in this order:

1. type: context, query: <topic>, filter: {visibility: ["private"]}
2. type: context, query: <topic>, filter: {like: "liked"}
3. type: context, query: <topic>, filter: {visibility: ["public"]}

Present the title list; if the match is clear, get pack immediately.

For filter keys and search recipes, see Search & Discovery.

UPDATE

Goal: edit an existing pack directly.

ID or alias known

Always fetch before writing.

get pack → inspect current blocks → update pack with id and block operations using op fields.

For update <alias> based on this conversation:

• merge new context into the right existing blocks
• rewrite blocks coherently instead of appending raw notes
• add a new block only for a distinct new topic

ID unknown

1. search pack — type: context, query: <inferred topic>, filter: {visibility: ["private"]}
2. One clear match → fetch and update without asking.
3. Multiple candidates → show titles and IDs, ask the user to pick.
4. No match → fall back to NEW.

"Last pack" shortcut: search private context packs and take the first result from the default recent-first outline.

ORGANIZE

Goal: improve the block structure of an existing pack.

The most common need is not managing many packs — it's making the blocks inside one pack cleaner and more useful.

Actions

All changes are applied via update pack using op fields. Use "op": "add" for new blocks, "op": "update" for existing ones, "op": "remove" to delete a block by ID. delete pack requires explicit user approval.

Write Safety

1. Default private — pack, new, and update always write private. Use PUBLISH to go public.
2. No silent writes — if scope is unclear, ask once before writing.
3. Approval required — public publication, deletion, and overwriting another owner's pack require explicit user confirmation before writing.

For the full approval matrix, see Visibility & Sharing — Approval Boundary.

Operation Output

After every operation, return in this order:

1. Context and block — always return both ID and title at each level that was affected
2. What changed — one sentence
3. Next action — single most useful next step (omit if none)

context  <context-id>  <context-title>
block    <block-id>    <block-title>    # when a specific block was created or updated

Skip analysis and evidence unless the user asked for it.

Source of Truth

Repository: https://github.com/epismoai/skills