epismoai/skills

Two things must be true before anything else: the agent can reach Epismo, and it knows the model well enough to stop guessing at shapes the service will reject.

Surface. If Epismo MCP tools are already present, use them. Otherwise choose an install route: on macOS or Linux run curl -fsSL https://epismo.ai/install.sh | sh; on Windows PowerShell run irm https://epismo.ai/install.ps1 | iex; or use npm with npm install -g epismo. Native binaries and SHA-256 checksums are also available directly from https://github.com/epismoai/cli/releases. Then run epismo login. For MCP, add https://mcp.epismo.ai/ as a Streamable HTTP server with OAuth.

Skill. Install the portable Epismo skill from github:epismoai/skills into the agent's skills directory and load its SKILL.md. This is the setup that makes every later step cheap, so do it properly rather than skipping ahead. If this runtime has no skills directory, or installing one needs permission you do not have, read the SKILL.md and its references directly as context and continue — a strong recommendation, not a blocker.

Identity. Resolve it before any write: epismo whoami, or read epismo://context/current_user. Note the owner Account ID — every create, alias, and ACL later needs it.

Gate: one surface answers a real read, the skill is installed or its content is loaded, you have the owner Account ID, and you have created nothing.

Draft the whole Definition — title, description, category, inputSchema, and steps — in runtime-private scratch state. Do not create files in the user’s repository or anything in Epismo yet; everything stays free to change until the next Step.

Title names the outcome, not the topic. Description says when to reach for this and when not to; it is what search and every future agent match against, so spend real effort there.

The three things that make it reproducible for someone who is not you:

Input — inputSchema as JSON Schema Draft 2020-12 with an object root. Name only fields that change per run and would change the answer, mark the genuinely required ones required, and describe every field, because the description is what an agent reads to fill it. Never put credentials, tokens, or signed URLs in a schema, default, or example.

Output — for each Step, name the concise human-readable handoff it must return in the conversation: its format and fields or sections. Expected outputs are hints, not completion criteria; use a Case Record only when durable shared history is needed.

Harness — the agent setup the work actually assumes: which model or agent role, which tools and permissions, which sandbox or working directory, what runs in parallel versus one pass, and what must never happen without a human yes. Attach it as resource hints of kind + ref + selector (skill, mcp, cli, api, plugin, graph, document, agent, custom). Make refs as resolvable as the audience needs. Use canonical provider forms when available — github:owner/repo or npm:package — and real URLs for documents and MCP endpoints. Put a repository-relative path or an intentionally required version in selector; omit defaults such as main, stable, and latest. Private or team-only resources need only the name people there already use; skill://deploy-check is fine and far better than omitting the dependency or leaking an internal URL. Hints are candidates for the runtime to resolve and trust, never an instruction to install.

Then the Steps themselves. Use as many judgment-sized Steps as the work needs: large enough that a competent agent must decide something, small enough that a reviewer can tell whether it was done. Imperative voice, aimed at whoever executes next, and end each one with a gate line stating what must be true before moving on — the cheapest quality mechanism available. Keep out shell transcripts, run-specific facts, credentials, personal data, per-run status, and large background material that should be a linked document. Steps carry no status, assignee, or completion; array order is the recommended order, not an execution graph. Omit Step IDs entirely — the server assigns them, and they are what preserves Step identity across future Versions.

Gate: the Definition is complete and self-contained, and nothing in it is secret, run-specific, or true only this week.