Guides a first-time omo user through setup and the core workflow. Use when a new user asks to get started with omo.
77%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Critical
Do not install without reviewing
Fix and improve this skill with Tessl
tessl review fix ./packages/omo-senpi/skills/onboarding/SKILL.mdThis skill introduces OmO through six lanes, in order: the feature tour, migration help, session archaeology, value mapping, memory recording (which runs through the whole flow, not at the end), and the first-session init-deep proposal. Three of the lanes are opt-in. When the user declines one, move on without argument and without repeating the offer.
Detect the user's language from their message and respond in that language for the rest of the conversation. The skill is written in English; your output is not. Match them exactly, including tone.
Inside the onboarding lanes, use Senpi-native tools only: read, bash, edit, write, the memory tools, the
onboarding_session_history, onboarding_understand and onboarding_memory_apply tools, tool_search to find one of
those when it is not in your tool list, and skill invocations. Once a lane hands off to another skill (init-deep, or a
workflow the user starts), that skill's own tool contract governs: use the tools it requires, such as create_goal,
eval, task and the question tool.
Your context carries the Onboarding scan block: the engine already ran the one scan the desktop
app and omo setup use, with one row per item it found on this computer (sign-ins, providers, MCP
servers, skills, model choices) and a Value summary line. Recent sessions are not in it: they
arrive on a later turn as a short background summary, and onboarding_session_history has more. When you
show the user what omo found, print those rows, one per item, and quote the value summary as
computed; never recount by hand. Never assume a tool from another agent product exists here.
Be concrete, never generic. "omo caches your context" is a failure of this skill. "Your last week of Claude Code sessions read 4.7M tokens from cache at a 78% hit rate; here is what that would have cost cold" is the bar.
--onboard, a request for the tour or getting started, or acceptance of the
offer starts the lanes immediately. In TUI, --onboard starts the guided conversation at
launch; in RPC, it applies to the first real user prompt.Open by introducing yourself and giving a short tour of what omo adds on top of a plain coding agent. The catalog below is baked in at authoring time because the user's machine has no omo or senpi source tree to explore. Present it conversationally, three to five highlights at a time, and let the user ask for depth on any item. Do not dump the whole list as a wall of text.
The baked catalog:
init-deep, ultrawork, ulw-loop, ulw-plan, ulw-research,
hyperplan, coding-agent-sessions, and give-me-tips provide reusable workflows that the
agent reads and follows only when relevant..mcp.json servers, and skill-embedded
servers give projects a layered tool surface without forcing every integration into core.ulw keyword: don't try to memorize the workflows up front — you'll
pick them up by using them. For now, remember one word: ulw. Put ulw in your prompt and
the agent gets sharper: it plans, researches, loops, and fans out work with evidence-bound
continuation until the goal is actually proven. Whenever something makes you curious — a tip
you saw, a feature you want explained — ask give-me-tips and it walks you through it.mass ulw opens dependency-ordered multi-agent DAG orchestration — many child
agents run in parallel waves, some waiting on others, so big jobs finish faster. Combined
requests such as mass ulw research load both mass-ulw and ulw-research at once.AGENTS.md generation, snapshot state, local or committed mode, and
later drift detection keep project instructions aligned with the codebase. On larger
repositories init-deep runs through mass-ulw's DAG map-reduce, so the work is spread across
parallel scanner and writer agents instead of one session.omo --list-tips on OmO Native (omo-ai installs, where senpi is not on PATH) or senpi --list-tips on a plain senpi install - then read and follow give-me-tips for any visible tip
the user wants explained from the implementation.--onboard flag of the command this product is installed as - omo --onboard on OmO
Native (omo-ai installs, where senpi is not on PATH) or senpi --onboard on a plain senpi
install - or shut the auto-start off with the omo-senpi-onboarding-disabled flag.While the user reacts to the tour, start lane 5: record what you learn about them through the memory tools as you learn it.
Ask whether the user is coming from another coding agent and would like their setup carried over. This lane is opt-in. If they say no, skip to lane 3.
If they say yes, start from the migration inventory that arrived with this skill's context (the
Migration inventory sentence): the engine already ran the same detection omo setup uses, and it
lists every sign-in it found (API keys to import, OAuth logins to sign in again, unmapped
providers), every custom provider, every global skill, and every MCP server from the sources it
covers - OpenCode, the oh-my-pi and gajae-code credential stores, and the engine's own files. For
those sources the inventory is the source of truth - do not re-read their config files by hand to
rebuild it. Show the user what omo setup --dry-run would do with it.
The scan does not know every harness. When the user is coming from one it does not detect, read that harness's own files by hand and fold what you find into the same plan:
~/.claude/settings.json, global and project CLAUDE.md files, MCP server
definitions in .mcp.json or settings.config.toml)
and any AGENTS.md files it manages..mcp.json, or an AGENTS.md another agent manages).Hand-read only what the inventory does not cover; never re-derive its categories by hand.
Global OpenCode MCP servers and global OpenCode skills are not yours to move by hand. omo setup
imports them: MCP servers from ~/.config/opencode/opencode.json[c] into the engine's global
~/.omo/agent/mcp.json, and skills from ~/.config/opencode/skills/ into ~/.omo/agent/skills/,
converted to the shapes omo reads, consent-gated, and never overwriting a name that already exists.
Once they accept, run omo setup --yes: your shell is not a terminal, so plain omo setup stops
at its consent prompt and imports nothing.
Copying a global server into a project .mcp.json yourself is a bug: it disappears the moment the
user opens any other directory.
Present one concrete migration plan from the inventory and anything the user named: which settings
map to ~/.omo/omo.json[c], which MCP servers omo setup carries over globally and which
project-only servers still belong in that project's .mcp.json, which CLAUDE.md content becomes
project AGENTS.md content, and which personal facts belong in memory instead of files.
Show the plan and WAIT for the user to accept it. Apply nothing before they say yes. If they accept
part of it, apply that part only. Record their agent-product history and migration choices through
the memory tools.
Ask the user, in your own voice and their language, a question that means: "may I look through your previous coding-agent sessions?" Phrase it naturally; do not read that sentence out like a script. This lane is opt-in. If they say no, skip to lane 4 and base it on nothing.
If they say yes, call onboarding_understand with consent: true (find it through tool_search
if it is not in your tool list). It reads the scan's session digests with the current model and
returns candidate facts with ids; it saves nothing. Show every candidate as a numbered list and ask
which ones to remember. Then call onboarding_memory_apply with exactly the ids they picked: it
writes only those, as one memory commit, through the same writer the background facts extractor
uses. Never write a candidate the user did not pick, and never re-write candidates through the
memory tools. If the understanding falls back to the scan only, say so and continue.
For the patterns below, call the onboarding_session_history tool as well. It is the engine's one session-history scan, the same one the desktop app
uses: it lists the projects found in the local agent histories, newest first, with the found / read
/ cap counts per source, and a digest for every recent session (first request, tools used, files
changed, outcome). Digests stay on this machine; the tool output names the file holding all of
them, so read it when more digests exist than the output shows. Pass workspace_root to focus
one project or recent_days to widen the window. Do not open or grep the raw transcript files
under the agents' home directories yourself: the scan already applies the caps and exclusions, and
hand reading is slow and gives different results each run. Mine the digests for:
Weave in migration suggestions where the history invites them, lightly. When a pattern you find maps to an omo feature from the tour, say so with the evidence: "you corrected the agent about your test runner in nine sessions; memory ends that" lands, a generic pitch does not. Record every durable finding about the user through the memory tools as you go.
Open with the scan's Value summary line as it was computed. Then, from the session data gathered
in lane 3, give the user quantified estimates of what omo's caching
would have been worth on their real workload. Compute, do not guess:
coding-agent-sessions skill's finder for this lane only.https://models.dev/api.json. Treat its top level as the provider map. Each provider owns
a models object, and each model cost uses input, output, cache_read, and cache_write
USD prices per one million tokens. If the API is unavailable, every session has insufficient
pricing data.message.usage. Map input, cacheRead, cacheWrite, and output
exactly. The three input categories are disjoint:
total_input_tokens = input + cacheRead + cacheWrite. A session whose total input is zero is
skipped.message.provider plus message.model when both are present.
Otherwise use the latest model_change provider and modelId. Usage before any model
information uses the first later model_change in that file when one exists; otherwise skip it.provider/model composite identity. If that misses, search for an
exact model id across provider keys sorted alphabetically, then model keys sorted alphabetically.
The first deterministic hit wins. If any required price field is missing, mark that entire
session as insufficient data.cacheRead / (input + cacheRead + cacheWrite) * 100.(input * price.input + output * price.output + cacheRead * price.cache_read + cacheWrite * price.cache_write) / 1_000_000.
Compute omo savings as
cacheRead * (price.input - price.cache_read) / 1_000_000.Math.round(value * 100) / 100. Never round per message,
model, or session. Label the result estimate.Label the result as an estimate and give exactly one line of methodology, in this shape: "Estimate from your local Senpi session logs: message-level model attribution, models.dev input/output/cache read/cache write pricing, summed across sessions, rounded at the end." One line, then the numbers, then stop.
If the user skipped lane 3, skip this lane too; there is no data to map.
This lane has no fixed position: it runs through the entire flow. Nothing is written before the
user chooses it: facts from the session history go through the lane 3 selection, and anything
else you learn is proposed in one line and written through the memory tools only after the user
agrees. Worth recording:
Write durable personal and cross-project facts through the memory tool into system/human.md.
Write repository-specific stack, commands, constraints, and migration decisions through the memory
tool into system/project.md. Do not edit those backing files directly.
Planning-stance observations from lane 3 are the one exception: write them as SEEDS under a
## Seed heading in system/human/planning-style.md (create the block through the memory tool if
absent), never into system/human.md. Seeds are inferences and MUST stay weak:
confidence: low ALWAYS - never medium or high, however consistent the
history looks. Behavior in another tool reflects that tool's affordances, not necessarily this
user; omo's own planning sessions will confirm or replace these within a few runs.seeded:. Format:
- [YYYY-MM-DD] (seed) appears to <hypothesis + context> <!-- src: <harness>/<session-id>,...; harness: <names>; model: <models>; seeded: YYYY-MM-DD; pattern: inferred-from-external-sessions; confidence: low -->Record facts, not narration. "Prefers Korean, migrated from Claude Code, works one repo at a time in long sessions" is a memory. "The user went through onboarding today" is not.
On the true first session the advisor component stays quiet, so this proposal is yours to carry. Before saying anything about it, run the same eligibility gate the advisor uses, in this order:
git rev-parse --show-toplevel. Not a repo: ineligible.node_modules, .git, dist, build, vendor, .next, __pycache__,
.venv, target, coverage, third_party) holding at least 8 source files or at least 500
lines of source directly in them. Zero candidates: ineligible, regardless of anything else.AGENTS.md. The missing ratio is uncovered candidates over all candidates. Below 0.50:
ineligible. A new project with candidates and no AGENTS.md anywhere is missing ratio 1.0 and
eligible.If any gate fails, skip this lane SILENTLY. Do not mention AGENTS.md, do not explain why you are not proposing, do not hint that a check ran. Close the conversation warmly instead.
If all gates pass, ask in the user's language: "want me to set up AGENTS.md for this project?"
This is opt-in. On yes, read the init-deep skill at its SKILL.md path and follow it. On no,
record the decline through the memory tools and finish the conversation gracefully: a short
send-off in their language, an invitation to come back with omo --onboard on OmO Native or
senpi --onboard on a plain senpi install, and nothing more.
After init-deep finishes, tell the user in their language which path it took. On its dag path, say
that init-deep ran through mass-ulw's DAG orchestration — the work was spread across parallel child
agents in dependency-ordered waves rather than done by one session. On its inline path (a repo too
small for a dag), say that it mapped the project with a few parallel explore agents and wrote the
files itself. Then introduce mass-ulw: mass ulw is how you bring that
DAG orchestration to any big job, and combined requests such as mass ulw research, mass ulw loop, and mass ulw plan load mass-ulw alongside each of those workflows.
code-yeongyu/oh-my-openagent
687f5af
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.