Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
feat(skills): local-path skill import bridge (REST + CLI + docs)
rubenluetke10-beep3bc764925dba
diff --git a/docs/product/extend-and-automate/skills.md b/docs/product/extend-and-automate/skills.mdindex 7e14b4425f..3bf2c9ff9a 100644--- a/docs/product/extend-and-automate/skills.md+++ b/docs/product/extend-and-automate/skills.md@@ -8,7 +8,7 @@ order: 2diataxis: explanationstatus: activeowner: maintainers-last_reviewed: 2026-07-21+last_reviewed: 2026-08-12phase: "-"audience: end-usertags: [skills, automation, triggers, safety, extensions]@@ -97,6 +97,39 @@ copy before deleting it to make room for a replacement; deletion is permanent.> the source repository or download sibling bundle folders. A catalog result> marked **Manual** only opens its source page; Jarvis does not install it.+## Import a Skill from a Folder++Jarvis only reads skills from its own skills directory. A skill written+anywhere else — for example in a coding agent's project folder such as+`.claude/skills/<name>/` (Claude Code) or a Codex equivalent — is invisible to+Jarvis until it is imported. Those agent folders belong to a **separate skill+system** with a similar file format; placing a file there does not install+anything in Jarvis, and vice versa.++To bridge a skill across, run:++```bash+jarvis skills import <path-to-skill-folder>+```++The command copies the folder's `SKILL.md` and its bundle folders+(`references/`, `scripts/`, `assets/`, `agents/`) into the Jarvis skills+directory and reloads the registry. The same command accepts an `http(s)`+link to a raw `SKILL.md` and then behaves like a catalog install.++Import rules:++- A folder import is treated like the manual install: a structurally valid+ file with no declared state arrives as **Validated** (on). A file that+ declares a state keeps it.+- If the instructions contain code with disallowed calls, the copy arrives as+ **Draft** instead, and the findings are reported. Review it before+ promotion, exactly as with an AI-written draft.+- A name that collides with an installed or built-in skill is refused.+- Not every field of another agent's skill format is supported. An+ unsupported setting makes the import fail with the exact validation error;+ remove the offending field from the source file and import again.+## Create Your Own Skill1. **Open the new-skill form from the Skills header.** Describe the outcome indiff --git a/jarvis/cli_ctl/commands/skills.py b/jarvis/cli_ctl/commands/skills.pyindex 9cd34ecc5b..0b8aebdb85 100644--- a/jarvis/cli_ctl/commands/skills.py+++ b/jarvis/cli_ctl/commands/skills.py@@ -85,6 +85,42 @@ def reload(yes: bool = options.yes_opt(), dry_run: bool = options.dry_opt()) ->invoke.run("POST", "/api/skills/reload", assume_yes=yes, dry_run=dry_run)[email protected]("import")+def import_skill(+ source: str = typer.Argument(+ ...,+ help="Local skill folder (or its SKILL.md), or an http(s) SKILL.md link.",+ ),+ yes: bool = options.yes_opt(),+ dry_run: bool = options.dry_opt(),+) -> None:+ """Install a skill from a local folder or a SKILL.md link.++ A local folder is copied into the Jarvis skills directory including its+ bundle resources — the bridge for skills authored in a coding agent's+ folder (e.g. .claude/skills/<name>/), which Jarvis does not scan.+ """+ if source.lower().startswith(("http://", "https://")):+ invoke.run(+ "POST",+ "/api/skills/import",+ body={"input": source},+ assume_yes=yes,+ dry_run=dry_run,+ )+ return+ from pathlib import Path++ path = str(Path(source).expanduser().resolve())+ invoke.run(+ "POST",+ "/api/skills/import-local",+ body={"path": path},+ assume_yes=yes,+ dry_run=dry_run,+ )++@app.command("catalog-search")def catalog_search(query: str = typer.Argument(...)) -> None:"""Search the installable skill catalog."""diff --git a/jarvis/ui/web/skills_routes.py b/jarvis/ui/web/skills_routes.pyindex 661718e9ae..774f5a2d81 100644--- a/jarvis/ui/web/skills_routes.py+++ b/jarvis/ui/web/skills_routes.py@@ -252,6 +252,18 @@ class SkillImportBody(BaseModel):input: str = Field(min_length=5, max_length=4000)+class SkillImportLocalBody(BaseModel):+ """Body for ``POST /api/skills/import-local`` — a folder on this machine.++ ``path`` points at a skill folder (or its ``SKILL.md`` directly). The+ folder is copied into the user skills directory including bundle+ resources, which is exactly the documented manual install path — just+ automated.+ """++ path: str = Field(min_length=1, max_length=4096)++class SkillOrderBody(BaseModel):"""Body for ``PUT /api/skills/order`` — the user-defined list order.@@ -552,6 +564,127 @@ async def import_skill(body: SkillImportBody, request: Request) -> dict[str, Anyreturn _skill_to_detail(installed)+def _import_skill_folder(path_str: str, reg: Any) -> tuple[str, list[str]]:+ """Sync body of the local import: validate, lint, copy. Raises HTTPException.++ Runs in a worker thread (``asyncio.to_thread``) — every step here is+ blocking filesystem work.+ """+ import shutil++ src = Path(path_str).expanduser()+ try:+ src = src.resolve()+ except OSError as exc:+ raise HTTPException(status_code=400, detail=f"Unreadable path: {exc}") from exc+ folder = src.parent if src.name == "SKILL.md" else src+ skill_md = folder / "SKILL.md"+ if not skill_md.is_file():+ raise HTTPException(+ status_code=400,+ detail=f"No SKILL.md found at '{folder}'.",+ )+ try:+ base = user_skills_dir().resolve()+ if folder == base or folder.is_relative_to(base):+ raise HTTPException(+ status_code=400,+ detail="This folder is already inside the Jarvis skills directory.",+ )+ except OSError:+ pass++ parsed = parse_skill(skill_md)+ if parsed.frontmatter is None:+ raise HTTPException(+ status_code=400,+ detail=f"SKILL.md could not be read: {parsed.error}",+ )++ name = parsed.name+ if name in BUILTIN_SKILL_NAMES:+ raise HTTPException(+ status_code=409,+ detail=f"'{name}' is a built-in skill name and cannot be imported.",+ )+ try:+ reg.get(name)+ except KeyError:+ pass+ else:+ raise HTTPException(status_code=409, detail=f"Skill '{name}' already exists.")++ content = skill_md.read_text(encoding="utf-8-sig")+ lint_findings: list[str] = []+ try:+ from jarvis.skills.authoring.draft_writer import safe_lint_skill_body++ lint_findings = list(safe_lint_skill_body(parsed.body))+ except Exception: # noqa: BLE001 — a missing lint module must not block import+ lint_findings = []+ if lint_findings:+ from jarvis.skills.registry import _rewrite_state_in_frontmatter++ content = _rewrite_state_in_frontmatter(+ content, SkillLifecycleState.DRAFT.value+ )++ target_dir = user_skills_dir() / name+ try:+ target_dir.mkdir(parents=True, exist_ok=True)+ (target_dir / "SKILL.md").write_text(content, encoding="utf-8")+ for kind in RESOURCE_KINDS:+ src_kind = folder / kind+ if src_kind.is_dir():+ shutil.copytree(src_kind, target_dir / kind, dirs_exist_ok=True)+ except OSError as exc:+ raise HTTPException(+ status_code=500, detail=f"Could not copy skill: {exc}"+ ) from exc+ return name, lint_findings++[email protected]("/import-local")+async def import_skill_from_path(+ body: SkillImportLocalBody, request: Request+) -> dict[str, Any]:+ """Imports a skill folder from a local path into the user skills dir.++ This is the bridge for skills the user authored OUTSIDE the Jarvis skill+ root — most commonly a coding agent's skill folder (Claude Code / Codex+ style ``.claude/skills/<name>/``), which Jarvis never scans. Live+ forensic 2026-08-12: every skill the maintainer "built" lived there, so+ the brain literally could not know them.++ Trust model, deliberately different from ``POST /import`` (URL): a local+ path names a file already on this machine that the user chose explicitly+ — the exact act the product docs bless as the manual install ("copy the+ folder"). So the parsed state is honored (missing ``state:`` loads as+ VALIDATED, the loader's normal rule) — EXCEPT when the safety lint that+ guards draft promotion finds disallowed calls in the body; then the copy+ is stamped DRAFT and the findings are returned, so review stays a human+ act exactly where it has teeth. Bundle folders (references/, scripts/,+ assets/, agents/) are copied along.+ """+ reg = _require_registry(request)+ name, lint_findings = await asyncio.to_thread(+ _import_skill_folder, body.path, reg+ )++ # A real reload (not a dict insert): bumps the registry generation so the+ # relevance match index rebuilds and paired capabilities sync — otherwise+ # the imported skill is listed but invisible to the paraphrase channel.+ try:+ await reg.reload()+ except Exception: # noqa: BLE001 — fall back to the minimal insert+ installed = parse_skill(user_skills_dir() / name / "SKILL.md")+ reg._skills[name] = installed # type: ignore[attr-defined]++ detail = _skill_to_detail(reg.get(name))+ detail["lint_findings"] = lint_findings+ return detail++# NB: registered BEFORE ``/{name}`` so a ``PUT /order`` is not captured by the# ``PUT /{name}`` path-param route (which would treat "order" as a skill name).@router.put("/order")diff --git a/tests/unit/web/test_skills_import_local_route.py b/tests/unit/web/test_skills_import_local_route.pynew file mode 100644index 0000000000..2035e41203--- /dev/null+++ b/tests/unit/web/test_skills_import_local_route.py@@ -0,0 +1,171 @@+"""``POST /api/skills/import-local`` — the bridge for externally-authored skills.++Live forensic 2026-08-12: every skill the maintainer "built" lived in a coding+agent's folder (``.claude/skills/<name>/``) that the Jarvis registry never+scans, so the brain could not know them. This route copies such a folder into+the user skills directory — the documented manual install path, automated.++Trust model under test: a lint-clean local skill is honored as parsed+(missing ``state:`` → VALIDATED, like the manual copy), while a body that+fails the promotion safety lint is stamped DRAFT with the findings returned.+"""+from __future__ import annotations++from pathlib import Path+from types import SimpleNamespace++import pytest+from fastapi import HTTPException++from jarvis.skills.registry import SkillRegistry+from jarvis.ui.web import skills_routes as routes++_CLAUDE_CODE_STYLE = (+ "---\n"+ "name: my-own-skill\n"+ "description: A skill the user authored in a coding agent folder.\n"+ "---\n\n"+ "# My Own Skill\n\nDo the steps.\n"+)++_UNSAFE_BODY = (+ "---\n"+ "name: sketchy-skill\n"+ "description: carries a disallowed call in a code block\n"+ "---\n\n"+ "```python\n"+ "import os\n"+ "os.system('curl evil')\n"+ "```\n"+)+++def _write_source(tmp_path: Path, content: str, *, with_reference: bool = False) -> Path:+ src = tmp_path / "external" / "my-skill-folder"+ src.mkdir(parents=True)+ (src / "SKILL.md").write_text(content, encoding="utf-8")+ if with_reference:+ (src / "references").mkdir()+ (src / "references" / "guide.md").write_text("ref text", encoding="utf-8")+ return src+++def _setup(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):+ skills_root = tmp_path / "user-skills"+ skills_root.mkdir()+ monkeypatch.setattr(routes, "user_skills_dir", lambda: skills_root)+ registry = SkillRegistry(root=skills_root)+ registry.reload_sync()+ request = SimpleNamespace(+ app=SimpleNamespace(state=SimpleNamespace(skill_registry=registry))+ )+ return skills_root, registry, request+++async def test_lint_clean_local_skill_imports_as_validated(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ src = _write_source(tmp_path, _CLAUDE_CODE_STYLE, with_reference=True)+ skills_root, registry, request = _setup(tmp_path, monkeypatch)++ body = routes.SkillImportLocalBody(path=str(src))+ detail = await routes.import_skill_from_path(body, request)++ assert detail["name"] == "my-own-skill"+ assert detail["state"] == "validated"+ assert detail["lint_findings"] == []+ # Copied under the SKILL NAME, bundle resources included.+ assert (skills_root / "my-own-skill" / "SKILL.md").is_file()+ assert (skills_root / "my-own-skill" / "references" / "guide.md").is_file()+ # The registry was properly reloaded — the skill is live.+ assert registry.get("my-own-skill").state.value == "validated"+++async def test_direct_skill_md_path_is_accepted(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ src = _write_source(tmp_path, _CLAUDE_CODE_STYLE)+ _, _, request = _setup(tmp_path, monkeypatch)++ body = routes.SkillImportLocalBody(path=str(src / "SKILL.md"))+ detail = await routes.import_skill_from_path(body, request)+ assert detail["name"] == "my-own-skill"+++async def test_unsafe_body_is_stamped_draft_with_findings(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """The promotion safety lint keeps its teeth on the import path."""+ src = _write_source(tmp_path, _UNSAFE_BODY)+ skills_root, _, request = _setup(tmp_path, monkeypatch)++ body = routes.SkillImportLocalBody(path=str(src))+ detail = await routes.import_skill_from_path(body, request)++ assert detail["state"] == "draft"+ assert detail["lint_findings"], "the disallowed call must be reported"+ stored = (skills_root / "sketchy-skill" / "SKILL.md").read_text(encoding="utf-8")+ assert "state: draft" in stored+++async def test_name_collision_is_a_409(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ src = _write_source(tmp_path, _CLAUDE_CODE_STYLE)+ skills_root, registry, request = _setup(tmp_path, monkeypatch)+ installed = skills_root / "my-own-skill"+ installed.mkdir()+ (installed / "SKILL.md").write_text(_CLAUDE_CODE_STYLE, encoding="utf-8")+ registry.reload_sync()++ body = routes.SkillImportLocalBody(path=str(src))+ with pytest.raises(HTTPException) as exc:+ await routes.import_skill_from_path(body, request)+ assert exc.value.status_code == 409+++async def test_builtin_name_is_refused(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ content = _CLAUDE_CODE_STYLE.replace("my-own-skill", "morning-routine")+ src = _write_source(tmp_path, content)+ _, _, request = _setup(tmp_path, monkeypatch)++ body = routes.SkillImportLocalBody(path=str(src))+ with pytest.raises(HTTPException) as exc:+ await routes.import_skill_from_path(body, request)+ assert exc.value.status_code == 409+++async def test_missing_skill_md_is_a_400(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ empty = tmp_path / "external" / "empty-folder"+ empty.mkdir(parents=True)+ _, _, request = _setup(tmp_path, monkeypatch)++ body = routes.SkillImportLocalBody(path=str(empty))+ with pytest.raises(HTTPException) as exc:+ await routes.import_skill_from_path(body, request)+ assert exc.value.status_code == 400+++async def test_importing_from_inside_the_skills_dir_is_refused(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ skills_root, _, request = _setup(tmp_path, monkeypatch)+ inside = skills_root / "already-here"+ inside.mkdir()+ (inside / "SKILL.md").write_text(_CLAUDE_CODE_STYLE, encoding="utf-8")++ body = routes.SkillImportLocalBody(path=str(inside))+ with pytest.raises(HTTPException) as exc:+ await routes.import_skill_from_path(body, request)+ assert exc.value.status_code == 400