Skip to content

importer

importer

SkillImporter — install ResolvedSkill instances into ~/.openjarvis/skills/.

Steps performed by import_skill:

  1. Parse the source SKILL.md through SkillParser (strict + tolerant).
  2. Translate tool references in the markdown body via ToolTranslator.
  3. Decide on scripts (default-skip; opt-in via with_scripts=True).
  4. Write to disk at ///:
  5. translated SKILL.md
  6. references/, assets/, templates/ (always copied)
  7. scripts/ (only if approved)
  8. .source metadata file
  9. Return ImportResult with status, warnings, translated/missing tools.

Classes

ImportResult dataclass 

ImportResult(success: bool = True, skipped: bool = False, target_path: Path | None = None, translated_tools: List[str] = list(), untranslated_tools: List[str] = list(), scripts_imported: bool = False, warnings: List[str] = list())

Result of importing a single skill.

SkillImporter 

SkillImporter(parser: SkillParser, tool_translator: ToolTranslator, target_root: Path | None = None)

Install resolved skills into the user skills directory.

Source code in src/openjarvis/skills/importer.py 
50
51
52
53
54
55
56
57
58
59
60
def __init__(
    self,
    parser: SkillParser,
    tool_translator: ToolTranslator,
    target_root: Path | None = None,
) -> None:
    self._parser = parser
    self._translator = tool_translator
    if target_root is None:
        target_root = Path("~/.openjarvis/skills/").expanduser()
    self._target_root = Path(target_root)
Functions
import_skill 
import_skill(resolved: ResolvedSkill, *, with_scripts: bool = False, force: bool = False) -> ImportResult

Install resolved into <target_root>/<source>/<name>/.

Returns an :class:ImportResult with status, paths, translated tools, untranslated tools, and warnings.

Source code in src/openjarvis/skills/importer.py 
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
def import_skill(
    self,
    resolved: ResolvedSkill,
    *,
    with_scripts: bool = False,
    force: bool = False,
) -> ImportResult:
    """Install *resolved* into ``<target_root>/<source>/<name>/``.

    Returns an :class:`ImportResult` with status, paths, translated
    tools, untranslated tools, and warnings.
    """
    result = ImportResult()
    target_dir = self._target_root / resolved.source / resolved.name
    result.target_path = target_dir

    # Skip if already installed and force is False
    if target_dir.exists() and not force:
        result.skipped = True
        result.warnings.append(
            f"Skill already installed at {target_dir} (use force=True to overwrite)"
        )
        return result

    # 1. Parse source SKILL.md
    source_md = resolved.path / "SKILL.md"
    if not source_md.exists():
        source_md = resolved.path / "skill.md"
        if not source_md.exists():
            result.success = False
            result.warnings.append(f"No SKILL.md found in {resolved.path}")
            return result

    try:
        frontmatter, body = self._read_skill_md(source_md)
        self._parser.parse_frontmatter(frontmatter, markdown_content=body)
    except Exception as exc:
        result.success = False
        result.warnings.append(f"Parse error: {exc}")
        return result

    # 2. Translate tool references
    translated_body, untranslated = self._translator.translate_markdown(body)
    result.untranslated_tools = untranslated
    # Compute the list of translations actually applied
    applied: List[str] = []
    for ext, internal in self._translator._table.items():
        if ext in body and ext not in translated_body:
            applied.append(f"{ext}->{internal}")
    result.translated_tools = applied

    # 3. Write the target directory
    if target_dir.exists():
        shutil.rmtree(target_dir)
    target_dir.mkdir(parents=True)

    # 3a. Translated SKILL.md
    new_md = self._render_skill_md(frontmatter, translated_body)
    (target_dir / "SKILL.md").write_text(new_md, encoding="utf-8")

    # 3b. Always-copied subdirs
    for subdir in COPIED_SUBDIRS:
        src_sub = resolved.path / subdir
        if src_sub.exists():
            shutil.copytree(src_sub, target_dir / subdir)

    # 3c. Scripts (gated by with_scripts)
    scripts_src = resolved.path / "scripts"
    if scripts_src.exists() and with_scripts:
        shutil.copytree(scripts_src, target_dir / "scripts")
        result.scripts_imported = True
    elif scripts_src.exists():
        result.warnings.append(
            "Skipped scripts/ directory (use with_scripts=True to import)"
        )

    # 4. Write .source metadata
    self._write_source_metadata(target_dir, resolved, result)

    return result