# Epismo Basics > Shared Epismo operating model: CLI/MCP surface conventions, workspace and project scope, share URL resolution, selective fetch and pack reuse patterns, pack aliases, pack suggestions, credits/payment handling, and common auth or permission errors. Load this alongside any Epismo skill, or trigger on Epismo usage questions, alias/credit issues, share URLs, workspace scope, or setup/auth problems bl… - **Type:** Skill - **Install:** `agentstack add skill-epismoai-skills-epismo-basics` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [epismoai](https://agentstack.voostack.com/s/epismoai) - **Installs:** 0 - **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [epismoai](https://github.com/epismoai) - **Source:** https://github.com/epismoai/skills/tree/main/skills/epismo-basics - **Website:** https://epismo.ai/hub ## Install ```sh agentstack add skill-epismoai-skills-epismo-basics ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Epismo Basics Shared reference for all Epismo skills. Covers connection, surface conventions, scope, share URL resolution, and error handling. Skills that build on this: - [Project Tracking](../project-tracking/SKILL.md) — tasks, goals, notes, planning - [Workflow Pack](../workflow-pack/SKILL.md) — workflow pack discovery and release - [Context Pack](../context-pack/SKILL.md) — context packs, session handoff --- ## Connection CLI and MCP are two interfaces to the **same Epismo service** — same account, same data, same tools. There is one Epismo account; the difference is only how you connect. **When both are available, use CLI.** If only MCP is available, use MCP. Never use both in the same session. ### Auth **CLI** (preferred): ```bash epismo login --email you@example.com # OTP flow (default, no browser) epismo login --browser # browser-based flow epismo whoami # verify ``` **MCP**: add `https://mcp.epismo.ai` as an MCP server in your client. Authentication is handled automatically via OAuth. --- ## Surface Conventions | Surface | Pattern | Example | | ------- | -------------------------------------- | ----------------------------------- | | `cli` | `epismo [--flags]` | `epismo pack search --type context` | | `mcp` | `epismo__` + JSON | `epismo_pack_search` | MCP tool name = CLI command with spaces and hyphens replaced by underscores (e.g. `epismo pack get` → `epismo_pack_get`). Conceptual payloads are the same across surfaces; each `--kebab-flag` becomes a camelCase JSON key (`--include-snapshot` → `includeSnapshot`), and a repeatable / comma-separated flag becomes an array (`--status open,applied` → `statuses: ["open", "applied"]`). **Skill docs show CLI forms only** — derive the MCP tool and parameters from these rules rather than re-listing them per page. **CLI is the full surface; MCP is a subset.** Prefer MCP or CLI and ignore the HTTP API in normal use. Some surfaces are **CLI-only** (no `epismo_*` tool): `login` / `logout` / `whoami`, `workspace`, `project`, `agent`, `credit`, and `token` — use the CLI for these. ### Pack Aliases Packs can be fetched by a short alias instead of a full ID. On the CLI, pass the alias (with or without `@` prefix) as the positional `` to `pack get` — same slot the ID goes in. In MCP, pass it via the `reference` parameter. To create and manage aliases, see [Pack Alias](./references/pack-alias.md). ### Suggestions Anyone who can read a workflow or context pack can send the owner a text-first improvement suggestion, and the owner reviews and resolves it (`open` → `applied` / `declined` / `archived`). Suggestions never edit the pack directly. The surface is shared across both pack skills — see [Suggestions](./references/suggestions.md) for the lifecycle, listing modes, and CLI/MCP operations. ### CLI Input Conventions - `--input ''` — inline JSON - `--input @path/to/file.json` — from file - `--input -` — from stdin - Explicit flags override fields in `--input`. ### Workspace Selection ```bash epismo workspace list epismo workspace use # save default epismo workspace current # show saved default (no network) ``` Workspace selection is CLI-only. All CLI commands resolve workspace automatically from `EPISMO_TOKEN`, saved default, then personal space. In MCP, workspace scope is implicit in the OAuth token. --- ## Scope Model - `workspace` — top-level access boundary. All operations run within the active workspace. - **Search inputs** use additive `scopes`: - `scopes: [{ type: "personal" }]` — search items that target the current user directly. - `scopes: [{ type: "projects", ids: [...] }]` — search items in specific projects. - Combine both scopes to search personal and project items together. Omit `scopes` to use the default search scope. - CLI search flags `--personal` and `--projects` build `scopes`. - **Mutation inputs** (pack/track create, update, apply) use `scope` plus optional `sharedWith`: - `scope: { type: "personal" }` — write to the caller's personal space. - `scope: { type: "projects", ids: [...] }` — write to specific projects. `ids` must be non-empty and a subset of the caller's accessible projects (see `references.projects`). `projects` scope is only valid in a workspace context. - `sharedWith: { userIds?: [...], emails?: [...] }` — optional, grants write access to specific people. Works with both `personal` and `projects` scope. - On create, `scope` is required (no implicit personal fallback). On update, omit `scope`/`sharedWith` to preserve existing ACL bits; passing them replaces. - Updating an item that has hidden project shares to `scope: { type: "personal" }` errors out. - CLI mutation flags: `--personal`, `--projects `, `--share-with ` (values containing `@` are treated as emails). When the user refers to "my project", resolve both layers before writing: 1. Active workspace 2. Target project(s) via `scope: { type: "projects", ids: [...] }` --- ## Pack References (Resolving Share URLs) Pack-level commands (`get`, `update`, `like`, `delete`) take a **single `reference`** — the server resolves it. You never follow redirects or extract IDs yourself; pass the user's value as-is. | Reference form | Example | | -------------- | ---------------------------------------------------------------------------------- | | Artifact ID | `abc-123-...` | | Alias | `@myproject`, `@handle/myproject` | | Share URL | `https://epismo.ai/share/{token}` or `https://{workspace}.epismo.ai/share/{token}` | | Hub URL | `https://epismo.ai/hub/workflows/{id}`, `https://epismo.ai/hub/contexts/{id}` | - **CLI** — positional ``: `epismo pack get `. - **MCP** — `reference` parameter on the `epismo_pack_*` tools. Share URLs resolve server-side by token, independent of host — a workspace-subdomain share URL works without special handling, and no credentials or redirect-following are needed. The resolved pack type (`workflow` / `context`) comes back in the response. --- ## Selective Fetch Pattern `search` always returns outline format (`id`, `title`, and brief metadata) — never full content blocks. Always scan titles first, then fetch only what you need — this keeps session context lean. 1. **Scan** — `search pack` or `search track` to get a title list. 2. **Select** — identify relevant items from the titles. Skip clearly unrelated ones. 3. **Fetch** — `get pack --full` or `get track` for each selected item to load full content. `get pack` has two modes: | Mode | Flag | Returns | | ----------------- | -------- | --------------------------------------------------------- | | Outline (default) | _(none)_ | `id`, `title`, `view`, `contentIndex` — no content blocks | | Full | `--full` | complete content including all blocks / steps | To load a single block or step instead of the full pack: ```bash # context pack — fetch one block epismo pack get --block-id # workflow pack — fetch specific steps epismo pack get --step-id , ``` ## Pack Reuse Scan Before creating any new pack, scan private and public candidates for the same topic so local work and community patterns can be compared directly: 1. `visibility=["private"]` + `query=` — your own or workspace-scoped packs 2. `visibility=["public"]` + `query=` — community packs for the same topic 3. `like="liked"` + `query=` — bookmarked packs as a quality signal or fallback If a close match is found, prefer `get pack` over creating new. ## Search Ranking Mode `search pack` and `search track` accept `searchMode`: `keyword` (default) or `semantic`. Keyword matches terms in title and content; semantic adds vector similarity, so it also surfaces paraphrases and cross-language matches. Default to `keyword`; use `semantic` when the user describes intent in their own words rather than exact terms. In CLI, pass `--search-mode keyword|semantic`. ```bash epismo pack search --type context --query "how onboarding works" --search-mode semantic epismo track search --type task --query "login is broken" --search-mode semantic ``` ## Pagination All `search` calls return page size 20. For large result sets, iterate `page=1, 2, 3...` and merge results. ```bash epismo pack search --type context --filter '{"visibility":["public"]}' --page 2 epismo track search --type task --filter '{"status":["todo"]}' --page 2 ``` Stop iterating when a page returns fewer than 20 results. --- ## Error Handling | Error | Action | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `Payment Required: Insufficient credits` | Stop. Check balance and purchase credits — see [Credit Purchase](./references/credit-purchase.md). | | `Permission denied` | Re-check accessible projects and resource ownership. | | `Unauthorized` / `403` | Re-authenticate: run `epismo login` (CLI) or reconnect via MCP OAuth. Verify active workspace and subscription. | | `Not Found` / `404` | Confirm the resource ID. It may have been deleted or the share token may have expired. | | Rate limit / `429` | Wait and retry with backoff. Inform user if persistent. | | Timeout | Retry once. If persistent, reduce payload size or split the operation. | ## Source of Truth Repository: `https://github.com/epismoai/skills` ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [epismoai](https://github.com/epismoai) - **Source:** [epismoai/skills](https://github.com/epismoai/skills) - **License:** MIT - **Homepage:** https://epismo.ai/hub Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-epismoai-skills-epismo-basics - Seller: https://agentstack.voostack.com/s/epismoai - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.