You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
New users rarely start from zero. They arrive with assets they already built for other
AI systems — above all Claude (Agent Skills) and OpenAI (Codex / ChatGPT custom
GPTs) — and today there is no first-class way to bring those into omadia. As an
onboarding improvement, the pragmatic first step is a skill import: take an existing
skill and turn it into a first-class omadia skill the user can attach to an agent.
This concept has three parts that build on each other:
Import mechanism — land a skill directly in the skills registry (never through a
bounded spec slot).
A skill-aware Builder agent — when a user brings or develops a skill while building
an agent, the Builder creates/attaches it as a first-class host skill (or sub-skill)
instead of inlining its text.
If technically feasible, the same front door later grows to cover richer resources
(bundled files, scripts, and eventually whole plugins).
This is a concept, not an implementation plan. It defines the problem, the principles,
the UX, and the omadia building blocks that make it feasible. Schema, APIs, and sequencing
are deliberately out of scope (separate implementation issue).
Epic — tracked work
This issue is the epic. It carries the import mechanism (Part 1) and the skill-aware
Builder (Part 2) as its concept; further work is tracked as sub-issues:
Parts 1 and 2 (import mechanism, skill-aware Builder) live in this issue and can be split
into their own sub-issues later if they are picked up independently.
The problem we are actually fixing
Two problems, one root cause.
Portability / onboarding. A user who has invested in Claude skills (or a ChatGPT
custom GPT) has to recreate that work by hand to use it in omadia — a cold-start tax
exactly when first impressions matter most.
The skill path in the Agent Builder is too hard and leaks internals. Today the
practical way to get a skill in is to paste its text into the builder conversation. As
soon as a skill grows beyond trivial, this hits slot / payload-size limits — an
artifact of routing structured content through the conversational spec path. The user
then sees "slot"-flavored errors. A normal user neither knows nor should know what a
slot is or where size limits come from. These mechanics must be handled internally
and stay invisible.
What should have happened in that session: the Builder recognizes the pasted content
as a skill and gives the new agent that skill — attached to the agent directly, or
as a sub-skill it accesses later — instead of trying to stuff it into a spec slot. Add
an upload affordance for the SKILL.md right there in the Builder and the experience
becomes dramatically friendlier.
Root cause. A skill is structured content (metadata + body, optionally bundled
resources). omadia already models it that way: the skills registry stores an unbounded
body plus structured frontmatter, and agents reference a skill by id instead of inlining
its text. The size pain appears only when a skill is forced through the conversational /
spec-slot path instead of landing directly in that registry. So the fix is mostly about using the path omadia already has — via a dedicated import and a skill-aware Builder —
and never inlining skill bodies into a bounded slot or chat turn.
Principles
Skills are imported and referenced, not pasted and inlined. A dedicated import path
writes the skill straight into the skills registry; agents point at it by id. The
conversational builder is for designing, not for carrying large content.
Size is the system's problem, never the user's. No character caps surfaced in the
UI, no "slot" vocabulary, no size errors. Where a genuine model-context limit exists,
the system resolves it (progressive disclosure / split into referenced resources) and,
if it must say anything, says it in plain language with an automatic remedy.
Progressive disclosure, mirroring how skills already work. Metadata (name /
description from frontmatter) is always cheap and is what the agent uses to decide whether a skill applies; the full body loads only when the owning sub-agent runs;
larger bundled resources load on demand. This keeps the main agent's context small no
matter how big the skill is.
One front door, many sources. The importer normalizes each source format into
omadia's canonical skill shape via per-source adapters, so adding a new source later is
an adapter, not a new product.
Untrusted by default. Imported content is third-party text; it gets a human
preview-before-activate step and stays subject to the same answer/quality guards as any
other prompt material.
Part 1 — What the user sees (import UX sketch)
From onboarding and from inside the Agent Builder: a single "Import a skill"
action — drag-and-drop a SKILL.md / folder / zip, or paste.
omadia parses it, auto-fills name + description from the frontmatter, and shows a
clean preview of what will be created. No size warnings, no slot talk.
One click creates the skill in the registry and (optionally) attaches it to the
agent / sub-agent the user is currently working on.
Re-importing an updated version updates the existing skill instead of duplicating it.
The whole flow should feel like: drop the file → it is now a skill on this agent.
Part 2 — The Builder agent must be skill-aware (the core fix)
The Builder is itself an agent. A skill can enter through the Builder in three ways,
and all three must end the same way — a real skill on the host, wired to the agent, never
inlined into a spec slot:
Bring a file — the user uploads a SKILL.md (or points at an existing registry skill).
Paste — the user pastes skill-shaped content into the conversation.
Develop it live in chat — there is no importable skill yet; the user and the Builder
draft the skill together in conversation. When it is ready, the Builder materializes it
as a real host skill (a registry entry, SKILL.md-shaped: frontmatter + body) and
attaches it to the agent. This is authoring, not import — but it lands in exactly the
same place, so it is equally immune to the slot-size limit.
For all three the Builder must:
Recognize skill intent and treat the content as a skill, not as free-form spec text.
Create on the host and attach, don't inline. The Builder persists the skill to the
registry and wires it to the agent under construction — on the agent directly or as a
sub-skill it calls on demand. The body never enters a spec slot or a chat turn, so the
size limit simply cannot be reached on this path.
Have a first-class "create-/attach-skill" capability it can call, with guidance to prefer that path over inlining whenever content looks like a skill or grows past a
trivial size.
Offer an upload affordance (SKILL.md) in the Builder surface, so the user need not
paste at all.
This is the part that directly removes the failure the user hit: a skill pasted into — or
authored inside — the Builder ends up as an attached host skill, not a slot-size error.
Part 3 — Onboarding: proactive import for a fast first success
Split out as its own tracked sub-issue: #396. In short: during new-user setup, omadia
proactively invites the user to bring a few skills they already trust (e.g. from Claude),
so they reach an early "it works, with my stuff" moment instead of an empty workspace —
reusing the Part 1 import path and the Part 2 skill-aware Builder. Full concept in #396.
Skill lifecycle: viewable and editable later (in every scenario)
Split out as its own tracked sub-issue: #397. In short: however a skill was created —
imported, pasted, or authored live in chat — its content must stay viewable and editable
through one consistent editor. Today that is only partly true (imported source: file
skills are read-only in the node-graph inspector, there is no central skills management
screen, and the conversational Builder has no skill view/edit surface). Full concept and
gap analysis in #397.
Feasibility anchors in omadia (why this is buildable)
The skills registry already fits the data. A skill entry carries an unbounded body,
structured frontmatter, and a source marker — the natural target for an imported SKILL.md. Claude's skill format (YAML frontmatter + Markdown body + optional bundled
files) maps onto it almost one-to-one.
Agents already reference skills by id, not by inlined text, and the body is composed
into the sub-agent prompt at dispatch time — i.e. the progressive-disclosure behavior
above is the existing runtime model, not a new mechanism to invent.
The Agent Builder already renders skills as first-class nodes wired to sub-agents,
and the UI already has upload / bulk-import building blocks to reuse for both the
import surface and the in-Builder upload affordance.
For the later plugins-with-scripts step, omadia already has the safe machinery: signed ZIP plugins, the Hub with sha256 integrity, the Builder's smoke
pipeline, and the Privacy Shield boundary. Scripts / executables should only ever
enter through that path (signed + sandboxed), never as raw content in a skill import.
Extensibility path (do not build all of it now)
Now: import a single Claude skill (frontmatter + body) → registry entry → attach to
an agent; Builder is skill-aware.
Next: skill bundles — body plus bundled resource files (knowledge, references)
loaded on demand; re-import = update by content hash.
Later, if feasible: an OpenAI adapter (Codex AGENTS.md / prompt files; ChatGPT
custom-GPT instructions + knowledge files + actions → body + resources + tool/MCP
mappings).
Eventually: whole plugins (incl. scripts) via the existing signed-ZIP + Hub + smoke
pipeline, with the importer as the unified "bring your resources" front door.
Non-goals
Exact schema / API / sequencing (separate implementation issue).
Executing or trusting imported scripts (gated to the plugin path).
Multi-tenant / marketplace concerns.
Open questions
Safety: prompt-injection / instruction-smuggling from imported skills — what is the
right review/guard step before activation?
Builder routing: what is the trigger for the Builder to treat content as a skill
(explicit upload vs. heuristic on pasted text vs. size threshold), and how does it
confirm with the user?
Fidelity: OpenAI sources have no formal skill format — how much is auto-mapped vs.
surfaced for user edit in the preview?
Provenance / licensing: what do we record and attribute for imported resources
(a source / source_path notion already exists)?
Versioning / dedup on re-import: content-hash identity (cf. Kemia's content-addressed
Profile-Bundle) vs. slug collision handling.
Edit semantics for imported skills: edit in place, or fork to an editable host copy
that preserves provenance — and what happens to the link when the upstream file changes?
Where the skills management view lives: admin, operator, or both, and how it relates
to the existing node-graph inspector so there is one editor, not two.
Summary
New users rarely start from zero. They arrive with assets they already built for other
AI systems — above all Claude (Agent Skills) and OpenAI (Codex / ChatGPT custom
GPTs) — and today there is no first-class way to bring those into omadia. As an
onboarding improvement, the pragmatic first step is a skill import: take an existing
skill and turn it into a first-class omadia skill the user can attach to an agent.
This concept has three parts that build on each other:
bounded spec slot).
an agent, the Builder creates/attaches it as a first-class host skill (or sub-skill)
instead of inlining its text.
(e.g. from Claude) for a fast first success. (tracked separately in Concept: Onboarding — proactively offer to import existing skills (e.g. from Claude) for a fast first success #396)
If technically feasible, the same front door later grows to cover richer resources
(bundled files, scripts, and eventually whole plugins).
This is a concept, not an implementation plan. It defines the problem, the principles,
the UX, and the omadia building blocks that make it feasible. Schema, APIs, and sequencing
are deliberately out of scope (separate implementation issue).
Epic — tracked work
This issue is the epic. It carries the import mechanism (Part 1) and the skill-aware
Builder (Part 2) as its concept; further work is tracked as sub-issues:
Parts 1 and 2 (import mechanism, skill-aware Builder) live in this issue and can be split
into their own sub-issues later if they are picked up independently.
The problem we are actually fixing
Two problems, one root cause.
Portability / onboarding. A user who has invested in Claude skills (or a ChatGPT
custom GPT) has to recreate that work by hand to use it in omadia — a cold-start tax
exactly when first impressions matter most.
The skill path in the Agent Builder is too hard and leaks internals. Today the
practical way to get a skill in is to paste its text into the builder conversation. As
soon as a skill grows beyond trivial, this hits slot / payload-size limits — an
artifact of routing structured content through the conversational spec path. The user
then sees "slot"-flavored errors. A normal user neither knows nor should know what a
slot is or where size limits come from. These mechanics must be handled internally
and stay invisible.
What should have happened in that session: the Builder recognizes the pasted content
as a skill and gives the new agent that skill — attached to the agent directly, or
as a sub-skill it accesses later — instead of trying to stuff it into a spec slot. Add
an upload affordance for the
SKILL.mdright there in the Builder and the experiencebecomes dramatically friendlier.
Root cause. A skill is structured content (metadata + body, optionally bundled
resources). omadia already models it that way: the skills registry stores an unbounded
body plus structured frontmatter, and agents reference a skill by id instead of inlining
its text. The size pain appears only when a skill is forced through the conversational /
spec-slot path instead of landing directly in that registry. So the fix is mostly about
using the path omadia already has — via a dedicated import and a skill-aware Builder —
and never inlining skill bodies into a bounded slot or chat turn.
Principles
writes the skill straight into the skills registry; agents point at it by id. The
conversational builder is for designing, not for carrying large content.
UI, no "slot" vocabulary, no size errors. Where a genuine model-context limit exists,
the system resolves it (progressive disclosure / split into referenced resources) and,
if it must say anything, says it in plain language with an automatic remedy.
description from frontmatter) is always cheap and is what the agent uses to decide
whether a skill applies; the full body loads only when the owning sub-agent runs;
larger bundled resources load on demand. This keeps the main agent's context small no
matter how big the skill is.
omadia's canonical skill shape via per-source adapters, so adding a new source later is
an adapter, not a new product.
preview-before-activate step and stays subject to the same answer/quality guards as any
other prompt material.
Part 1 — What the user sees (import UX sketch)
action — drag-and-drop a
SKILL.md/ folder / zip, or paste.clean preview of what will be created. No size warnings, no slot talk.
agent / sub-agent the user is currently working on.
The whole flow should feel like: drop the file → it is now a skill on this agent.
Part 2 — The Builder agent must be skill-aware (the core fix)
The Builder is itself an agent. A skill can enter through the Builder in three ways,
and all three must end the same way — a real skill on the host, wired to the agent, never
inlined into a spec slot:
SKILL.md(or points at an existing registry skill).draft the skill together in conversation. When it is ready, the Builder materializes it
as a real host skill (a registry entry,
SKILL.md-shaped: frontmatter + body) andattaches it to the agent. This is authoring, not import — but it lands in exactly the
same place, so it is equally immune to the slot-size limit.
For all three the Builder must:
registry and wires it to the agent under construction — on the agent directly or as a
sub-skill it calls on demand. The body never enters a spec slot or a chat turn, so the
size limit simply cannot be reached on this path.
prefer that path over inlining whenever content looks like a skill or grows past a
trivial size.
SKILL.md) in the Builder surface, so the user need notpaste at all.
This is the part that directly removes the failure the user hit: a skill pasted into — or
authored inside — the Builder ends up as an attached host skill, not a slot-size error.
Part 3 — Onboarding: proactive import for a fast first success
Split out as its own tracked sub-issue: #396. In short: during new-user setup, omadia
proactively invites the user to bring a few skills they already trust (e.g. from Claude),
so they reach an early "it works, with my stuff" moment instead of an empty workspace —
reusing the Part 1 import path and the Part 2 skill-aware Builder. Full concept in #396.
Skill lifecycle: viewable and editable later (in every scenario)
Split out as its own tracked sub-issue: #397. In short: however a skill was created —
imported, pasted, or authored live in chat — its content must stay viewable and editable
through one consistent editor. Today that is only partly true (imported
source: fileskills are read-only in the node-graph inspector, there is no central skills management
screen, and the conversational Builder has no skill view/edit surface). Full concept and
gap analysis in #397.
Feasibility anchors in omadia (why this is buildable)
structured frontmatter, and a
sourcemarker — the natural target for an importedSKILL.md. Claude's skill format (YAML frontmatter + Markdown body + optional bundledfiles) maps onto it almost one-to-one.
into the sub-agent prompt at dispatch time — i.e. the progressive-disclosure behavior
above is the existing runtime model, not a new mechanism to invent.
and the UI already has upload / bulk-import building blocks to reuse for both the
import surface and the in-Builder upload affordance.
signed ZIP plugins, the Hub with sha256 integrity, the Builder's smoke
pipeline, and the Privacy Shield boundary. Scripts / executables should only ever
enter through that path (signed + sandboxed), never as raw content in a skill import.
Extensibility path (do not build all of it now)
an agent; Builder is skill-aware.
loaded on demand; re-import = update by content hash.
AGENTS.md/ prompt files; ChatGPTcustom-GPT instructions + knowledge files + actions → body + resources + tool/MCP
mappings).
pipeline, with the importer as the unified "bring your resources" front door.
Non-goals
Open questions
right review/guard step before activation?
(explicit upload vs. heuristic on pasted text vs. size threshold), and how does it
confirm with the user?
surfaced for user edit in the preview?
(a
source/source_pathnotion already exists)?Profile-Bundle) vs. slug collision handling.
that preserves provenance — and what happens to the link when the upstream file changes?
to the existing node-graph inspector so there is one editor, not two.
Related