Skip to content

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.

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.md
index 7e14b4425f..3bf2c9ff9a 100644
--- a/docs/product/extend-and-automate/skills.md
+++ b/docs/product/extend-and-automate/skills.md
@@ -8,7 +8,7 @@ order: 2
diataxis: explanation
status: active
owner: maintainers
-last_reviewed: 2026-07-21
+last_reviewed: 2026-08-12
phase: "-"
audience: end-user
tags: [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 Skill
1. **Open the new-skill form from the Skills header.** Describe the outcome in
diff --git a/jarvis/cli_ctl/commands/skills.py b/jarvis/cli_ctl/commands/skills.py
index 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)
+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.py
index 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, Any
return _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.py
new file mode 100644
index 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