Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(skill): preserve nested SKILL.md files during skill import (#4055)

dxp_whcfe57b5e33da
diff --git a/openviking/utils/skill_processor.py b/openviking/utils/skill_processor.py
index 9e0c67f49..c2e982256 100644
--- a/openviking/utils/skill_processor.py
+++ b/openviking/utils/skill_processor.py
@@ -316,7 +316,9 @@ class SkillProcessor:
skill_dict = SkillLoader.load(str(skill_file))
base_path = data
for item in data.rglob("*"):
- if item.is_file() and item.name != "SKILL.md":
+ # Exclude only the top-level SKILL.md (the skill body);
+ # nested SKILL.md files belong to sub-skills and must be kept.
+ if item.is_file() and item != skill_file:
auxiliary_files.append(item)
else:
# Single skill markdown file
diff --git a/tests/unit/test_skill_processor_nested_skill_md.py b/tests/unit/test_skill_processor_nested_skill_md.py
new file mode 100644
index 000000000..4281f16eb
--- /dev/null
+++ b/tests/unit/test_skill_processor_nested_skill_md.py
@@ -0,0 +1,76 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import shutil
+import zipfile
+
+from openviking.utils.skill_processor import SkillProcessor
+
+SKILL_MD = """---
+name: demo
+description: demo skill
+---
+
+# Demo
+"""
+
+NESTED_SKILL_MD = """---
+name: demo-notes
+description: demo notes sub-skill
+---
+
+# Notes
+"""
+
+
+def _build_nested_skill_dir(tmp_path):
+ skill_dir = tmp_path / "demo"
+ (skill_dir / "notes").mkdir(parents=True)
+ (skill_dir / "scripts").mkdir()
+ (skill_dir / "SKILL.md").write_text(SKILL_MD, encoding="utf-8")
+ (skill_dir / "notes" / "SKILL.md").write_text(NESTED_SKILL_MD, encoding="utf-8")
+ (skill_dir / "notes" / "api.md").write_text("api reference", encoding="utf-8")
+ (skill_dir / "scripts" / "helper.py").write_text("print('ok')\n", encoding="utf-8")
+ return skill_dir
+
+
+def test_parse_skill_directory_keeps_nested_skill_md(tmp_path):
+ skill_dir = _build_nested_skill_dir(tmp_path)
+
+ processor = SkillProcessor(vikingdb=None)
+ skill_dict, auxiliary_files, base_path, cleanup_path = processor._parse_skill(
+ skill_dir, allow_local_path_resolution=True
+ )
+
+ assert skill_dict["name"] == "demo"
+ assert base_path == skill_dir
+ relative = sorted(str(path.relative_to(skill_dir)) for path in auxiliary_files)
+ # The top-level SKILL.md is the skill body and must stay excluded, while
+ # nested SKILL.md files (sub-skills) must be collected as auxiliary files.
+ assert relative == [
+ "notes/SKILL.md",
+ "notes/api.md",
+ "scripts/helper.py",
+ ]
+
+
+def test_parse_skill_zip_keeps_nested_skill_md(tmp_path):
+ skill_zip = tmp_path / "demo.zip"
+ with zipfile.ZipFile(skill_zip, "w") as zf:
+ zf.writestr("demo/SKILL.md", SKILL_MD)
+ zf.writestr("demo/notes/SKILL.md", NESTED_SKILL_MD)
+ zf.writestr("demo/notes/api.md", "api reference")
+
+ processor = SkillProcessor(vikingdb=None)
+ cleanup_path = None
+ try:
+ skill_dict, auxiliary_files, base_path, cleanup_path = processor._parse_skill(
+ skill_zip, allow_local_path_resolution=True
+ )
+
+ assert skill_dict["name"] == "demo"
+ relative = sorted(str(path.relative_to(base_path)) for path in auxiliary_files)
+ assert relative == ["notes/SKILL.md", "notes/api.md"]
+ finally:
+ if cleanup_path:
+ shutil.rmtree(cleanup_path, ignore_errors=True)