structured_skills 0.1.1__tar.gz

structured_skills-0.1.1/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.3
+Name: structured_skills
+Version: 0.1.1
+Summary: Structured Skills for Agents
+Requires-Dist: fastmcp>=3.0.0
+Requires-Dist: libcst>=1.8.6
+Requires-Dist: strictyaml>=1.7.3
+Requires-Dist: smolagents>=1.0.0 ; extra == 'smolagents'
+Requires-Python: >=3.10
+Provides-Extra: smolagents
+Description-Content-Type: text/markdown
+
+# structured_skills
+
+Structured Skills for Agents - launch MCP servers from skill directories
+
+## Usage
+
+Quick usage to launch MCP server:
+
+```sh
+structured_skills run path/to/root/skills
+```
+
+To test via CLI:
+
+```sh
+structured_skills cli list_skills
+structured_skills cli load_skill <skill_name>
+structured_skills cli read_skill_resource <skill_name> <resource_name>
+structured_skills cli run_skill <skill_name> <function_name>
+```
+
+Programmatically:
+
+```py
+from structured_skills import SkillRegistry
+
+registry = SkillRegistry("/path/to/skills")
+
+# List all available skills
+registry.list_skills()
+
+# Load full skill instructions
+registry.load_skill(skill_name)
+
+# Read a resource (file, script, or function info)
+registry.read_skill_resource(skill_name, resource_name, args)
+
+# Execute a skill function
+registry.run_skill(skill_name, function_name, args)
+```
+
+## smolagents Integration
+
+structured_skills provides integration with [smolagents](https://github.com/huggingface/smolagents):
+
+```sh
+uv pip install structured_skills[smolagents]
+```
+
+```py
+from structured_skills import SkillRegistry
+from structured_skills.smolagents import create_smolagents_tools
+
+registry = SkillRegistry("/path/to/skills")
+
+# Create all tools
+tools = create_smolagents_tools(registry)
+
+# Or create specific tools
+tools = create_smolagents_tools(registry, tools=["list_skills", "load_skill"])
+
+# Use with smolagents
+from smolagents import CodeAgent, HfApiModel
+
+agent = CodeAgent(tools=tools, model=HfApiModel())
+agent.run("List available skills")
+```
+
+## Validation
+
+Perform checks with suggested fixes:
+
+```sh
+structured_skills check path/to/root/skills
+structured_skills check path/to/root/skills --fix  # try to fix observed issues
+```

structured_skills-0.1.1/README.md

@@ -0,0 +1,76 @@
+# structured_skills
+
+Structured Skills for Agents - launch MCP servers from skill directories
+
+## Usage
+
+Quick usage to launch MCP server:
+
+```sh
+structured_skills run path/to/root/skills
+```
+
+To test via CLI:
+
+```sh
+structured_skills cli list_skills
+structured_skills cli load_skill <skill_name>
+structured_skills cli read_skill_resource <skill_name> <resource_name>
+structured_skills cli run_skill <skill_name> <function_name>
+```
+
+Programmatically:
+
+```py
+from structured_skills import SkillRegistry
+
+registry = SkillRegistry("/path/to/skills")
+
+# List all available skills
+registry.list_skills()
+
+# Load full skill instructions
+registry.load_skill(skill_name)
+
+# Read a resource (file, script, or function info)
+registry.read_skill_resource(skill_name, resource_name, args)
+
+# Execute a skill function
+registry.run_skill(skill_name, function_name, args)
+```
+
+## smolagents Integration
+
+structured_skills provides integration with [smolagents](https://github.com/huggingface/smolagents):
+
+```sh
+uv pip install structured_skills[smolagents]
+```
+
+```py
+from structured_skills import SkillRegistry
+from structured_skills.smolagents import create_smolagents_tools
+
+registry = SkillRegistry("/path/to/skills")
+
+# Create all tools
+tools = create_smolagents_tools(registry)
+
+# Or create specific tools
+tools = create_smolagents_tools(registry, tools=["list_skills", "load_skill"])
+
+# Use with smolagents
+from smolagents import CodeAgent, HfApiModel
+
+agent = CodeAgent(tools=tools, model=HfApiModel())
+agent.run("List available skills")
+```
+
+## Validation
+
+Perform checks with suggested fixes:
+
+```sh
+structured_skills check path/to/root/skills
+structured_skills check path/to/root/skills --fix  # try to fix observed issues
+```

structured_skills-0.1.1/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "structured_skills"
+version = "0.1.1"
+description = "Structured Skills for Agents"
+readme = "README.md"
+authors = []
+requires-python = ">=3.10"
+dependencies = [
+    "fastmcp>=3.0.0",
+    "libcst>=1.8.6",
+    "strictyaml>=1.7.3",
+]
+
+[project.optional-dependencies]
+smolagents = ["smolagents>=1.0.0"]
+
+[project.scripts]
+structured_skills = "structured_skills:main"
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "bump-my-version>=1.2.7",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.15.2",
+    "ty>=0.0.17",
+]
+smolagents = ["smolagents>=1.0.0"]
+
+[tool.coverage.run]
+omit = [
+    "*/__init__.py",
+    "*/__main__.py",
+]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I001"]
+
+[tool.bumpversion]
+current_version = "0.1.1"
+parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
+serialize = ["{major}.{minor}.{patch}"]
+search = "{current_version}"
+replace = "{new_version}"
+regex = false
+ignore_missing_version = false
+tag = true
+sign_tags = false
+tag_name = "v{new_version}"
+tag_message = "Bump version: {current_version} → {new_version}"
+allow_dirty = false
+commit = true
+message = "Bump version: {current_version} → {new_version}"
+pre_commit_hooks = ["uv sync", "git add uv.lock"]  # The new bit.
+commit_args = ""

structured_skills-0.1.1/src/structured_skills/__init__.py

@@ -0,0 +1,13 @@
+from structured_skills.cli import main
+from structured_skills.skill_registry import Skill, SkillRegistry, get_tool
+from structured_skills.validator import find_skill_md, parse_frontmatter, validate
+
+__all__ = [
+    "main",
+    "SkillRegistry",
+    "Skill",
+    "get_tool",
+    "validate",
+    "find_skill_md",
+    "parse_frontmatter",
+]

structured_skills-0.1.1/src/structured_skills/__main__.py

@@ -0,0 +1,4 @@
+from structured_skills.cli import main
+
+if __name__ == "__main__":
+    main()

structured_skills-0.1.1/src/structured_skills/cli.py

@@ -0,0 +1,140 @@
+import argparse
+import sys
+from pathlib import Path
+
+from structured_skills.server import create_mcp_server
+from structured_skills.skill_registry import SkillRegistry
+from structured_skills.validator import validate
+
+
+def create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="structured_skills",
+        description="Structured Skills for Agents - Launch MCP servers from skill directories",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    run_parser = subparsers.add_parser("run", help="Launch MCP server for skills")
+    run_parser.add_argument("skill_dir", type=Path, help="Path to skill root directory")
+
+    cli_parser = subparsers.add_parser("cli", help="CLI tools for skill management")
+    cli_subparsers = cli_parser.add_subparsers(dest="cli_command", help="CLI subcommands")
+
+    list_skills_parser = cli_subparsers.add_parser("list_skills", help="List skills")
+    list_skills_parser.add_argument("skill_dir", type=Path, help="Path to skill root directory")
+
+    load_skill_parser = cli_subparsers.add_parser("load_skill", help="Load a skill")
+    load_skill_parser.add_argument("skill_dir", type=Path, help="Path to skill root directory")
+    load_skill_parser.add_argument("skill_name", help="Name of the skill to load")
+
+    read_resource_parser = cli_subparsers.add_parser(
+        "read_skill_resource", help="Read a skill resource"
+    )
+    read_resource_parser.add_argument("skill_dir", type=Path, help="Path to skill root directory")
+    read_resource_parser.add_argument("skill_name", help="Name of the skill")
+    read_resource_parser.add_argument("resource_name", help="Name of the resource")
+    read_resource_parser.add_argument(
+        "--args", type=str, default=None, help="JSON args for the resource"
+    )
+
+    run_skill_parser = cli_subparsers.add_parser("run_skill_script", help="Run a skill script")
+    run_skill_parser.add_argument("skill_dir", type=Path, help="Path to skill root directory")
+    run_skill_parser.add_argument("skill_name", help="Name of the skill")
+    run_skill_parser.add_argument("function_or_script", help="Function or script name to run")
+    run_skill_parser.add_argument("--args", type=str, default=None, help="JSON args for the script")
+
+    check_parser = subparsers.add_parser("check", help="Validate skill directory")
+    check_parser.add_argument("skill_dir", type=Path, help="Path to skill directory")
+    check_parser.add_argument("--fix", action="store_true", help="Attempt to fix issues")
+
+    return parser
+
+
+def handle_cli(args: argparse.Namespace) -> None:
+    registry = SkillRegistry(args.skill_dir)
+
+    if args.cli_command == "list_skills":
+        skills = registry.list_skills()
+        for name, desc in skills.items():
+            print(f"{name}: {desc}")
+
+    elif args.cli_command == "load_skill":
+        content = registry.load_skill(args.skill_name)
+        print(content)
+
+    elif args.cli_command == "read_skill_resource":
+        import json
+
+        args_dict = json.loads(args.args) if args.args else None
+        result = registry.read_skill_resource(args.skill_name, args.resource_name, args_dict)
+        if isinstance(result, dict):
+            print(json.dumps(result, indent=2))
+        else:
+            print(result)
+
+    elif args.cli_command == "run_skill_script":
+        import json
+
+        args_dict = json.loads(args.args) if args.args else None
+        result = registry.run_skill(args.skill_name, args.function_or_script, args_dict)
+        print(result)
+
+    else:
+        print("Unknown CLI command. Use --help for usage.")
+        sys.exit(1)
+
+
+def handle_check(args: argparse.Namespace) -> None:
+    skill_dir = args.skill_dir
+
+    if not skill_dir.is_dir():
+        print(f"Error: {skill_dir} is not a directory")
+        sys.exit(1)
+
+    all_errors: list[tuple[Path, list[str]]] = []
+
+    for sub_dir in skill_dir.iterdir():
+        if sub_dir.is_dir():
+            errors = validate(sub_dir)
+            if errors:
+                all_errors.append((sub_dir, errors))
+
+    if all_errors:
+        print("Validation errors found:\n")
+        for dir_path, errors in all_errors:
+            print(f"{dir_path}:")
+            for error in errors:
+                print(f"  - {error}")
+        sys.exit(1)
+    else:
+        print("All skills validated successfully!")
+
+    if args.fix:
+        print("\nNote: Auto-fix is not yet implemented.")
+
+
+def main() -> None:
+    parser = create_parser()
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    if args.command == "run":
+        mcp = create_mcp_server(args.skill_dir)
+        mcp.run()
+
+    elif args.command == "cli":
+        handle_cli(args)
+
+    elif args.command == "check":
+        handle_check(args)
+
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

structured_skills-0.1.1/src/structured_skills/cst/utils.py

@@ -0,0 +1,171 @@
+from dataclasses import dataclass
+
+import libcst as cst
+
+SECRET_VARIABLE = "__VALUE"
+
+
+@dataclass
+class ParameterInfo:
+    name: str
+    annotation: str | None
+    default: str | None
+
+
+@dataclass
+class FunctionInfo:
+    name: str
+    parameters: list[ParameterInfo]
+    return_type: str | None
+    docstring: str | None
+
+
+class FunctionNotFoundError(Exception):
+    pass
+
+
+def extract_function_info(source: str, function_name: str) -> FunctionInfo:
+    module = cst.parse_module(source)
+
+    class FunctionFinder(cst.CSTVisitor):
+        def __init__(self):
+            self.function_node = None
+
+        def visit_FunctionDef(self, node: cst.FunctionDef) -> None:
+            if node.name.value == function_name:
+                self.function_node = node
+            super().visit_FunctionDef(node)
+
+    finder = FunctionFinder()
+    module.visit(finder)
+
+    if finder.function_node is None:
+        raise FunctionNotFoundError(f"Function '{function_name}' not found in source")
+
+    func = finder.function_node
+
+    params = []
+    if func.params and func.params.params:
+        for param in func.params.params:
+            annotation = None
+            if param.annotation and hasattr(param.annotation, "annotation"):
+                try:
+                    expr_value = param.annotation.annotation
+                    code_val = getattr(expr_value, "code", None)
+                    if isinstance(code_val, str):
+                        annotation = code_val
+                    elif isinstance(expr_value, cst.BaseExpression):
+                        if hasattr(expr_value, "value"):
+                            value_attr = getattr(expr_value, "value", None)
+                            if callable(value_attr):
+                                annotation = str(value_attr())
+                            else:
+                                annotation = str(value_attr)
+                        else:
+                            annotation = str(expr_value)
+                    elif isinstance(expr_value, str):
+                        annotation = expr_value
+                except (AttributeError, TypeError):
+                    pass
+
+            default = None
+            if param.default:
+                expr_value = param.default
+                value_attr = getattr(expr_value, "value", None)
+                if callable(value_attr):
+                    default = str(value_attr())
+                elif isinstance(value_attr, str):
+                    default = value_attr
+                else:
+                    code_attr = getattr(expr_value, "code", None)
+                    if code_attr is not None:
+                        default = str(code_attr)
+
+            params.append(
+                ParameterInfo(
+                    name=param.name.value,
+                    annotation=annotation,
+                    default=default,
+                )
+            )
+
+    return_type = None
+    if func.returns:
+        annotation_attr = getattr(func.returns, "annotation", None)
+        if annotation_attr is not None:
+            return_type = getattr(annotation_attr, "value", None)
+
+    docstring = None
+    if hasattr(func.body, "body") and func.body.body:
+        first_stmt = func.body.body[0]
+        if isinstance(first_stmt, cst.SimpleStatementLine):
+            body_stmt = first_stmt.body[0] if first_stmt.body else None
+            if isinstance(body_stmt, cst.Expr) and isinstance(body_stmt.value, cst.SimpleString):
+                docstring = (
+                    body_stmt.value.value[3:-3]
+                    if body_stmt.value.value.startswith('"""')
+                    or body_stmt.value.value.startswith("'''")
+                    else body_stmt.value.value[1:-1]
+                )
+        elif isinstance(first_stmt, cst.Expr) and isinstance(first_stmt.value, cst.SimpleString):
+            docstring = (
+                first_stmt.value.value[3:-3]
+                if first_stmt.value.value.startswith('"""')
+                or first_stmt.value.value.startswith("'''")
+                else first_stmt.value.value[1:-1]
+            )
+
+    return FunctionInfo(
+        name=func.name.value,
+        parameters=params,
+        return_type=return_type,
+        docstring=docstring,
+    )
+
+
+def update_code(source: str, new_call: str) -> str:
+    module = cst.parse_module(source)
+
+    class MainBlockFinder(cst.CSTVisitor):
+        def __init__(self):
+            self.main_block_positions = []
+
+        def visit_If(self, node: cst.If) -> None:
+            test = node.test
+            if isinstance(test, cst.Comparison):
+                if (
+                    isinstance(test.left, cst.Name)
+                    and test.left.value == "__name__"
+                    and len(test.comparisons) == 1
+                ):
+                    comparison = test.comparisons[0]
+                    if (
+                        isinstance(comparison.operator, cst.Equal)
+                        and isinstance(comparison.comparator, cst.SimpleString)
+                        and comparison.comparator.value == '"__main__"'
+                    ):
+                        self.main_block_positions.append(node)
+            super().visit_If(node)
+
+    finder = MainBlockFinder()
+    module.visit(finder)
+
+    if not finder.main_block_positions:
+        return source + "\n" + new_call + "\n"
+
+    body = list(module.body)
+    for node in finder.main_block_positions:
+        body.remove(node)
+
+    new_statement = cst.parse_statement(new_call)
+    body.append(new_statement)
+
+    new_module = cst.Module(body=body)
+    return new_module.code
+
+
+def execute_script(content, function_name, args):
+    output = update_code(content, f"args={str(args)};{SECRET_VARIABLE} = {function_name}(**args)")
+    context: dict = {"__builtins__": __builtins__}
+    exec(output, context, context)
+    return context[SECRET_VARIABLE]

structured_skills-0.1.1/src/structured_skills/server.py

@@ -0,0 +1,42 @@
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+from structured_skills.skill_registry import SkillRegistry
+
+
+def create_mcp_server(skill_root_dir: Path, server_name: str = "structured_skills") -> FastMCP:
+    mcp = FastMCP(server_name)
+    registry = SkillRegistry(skill_root_dir)
+
+    skill_names = registry.get_skill_names()
+    skills_info = f"\n\nAvailable skills: {', '.join(skill_names)}"
+
+    @mcp.tool(
+        description=f"List all available skills. Returns a mapping of skill names to their descriptions.{skills_info}"
+    )
+    def list_skills() -> dict[str, str]:
+        """List all available skills. Returns a mapping of skill names to their descriptions."""
+        return registry.list_skills()
+
+    @mcp.tool(description=f"Load full instructions for a specific skill by name.{skills_info}")
+    def load_skill(skill_name: str) -> str:
+        """Load full instructions for a specific skill by name."""
+        return registry.load_skill(skill_name)
+
+    @mcp.tool(
+        description=f"Load full resource file, script, or function for a specific skill.{skills_info}"
+    )
+    def read_skill_resource(skill_name: str, resource_name: str, args: dict | None = None) -> str:
+        """Load full resource file, script, or function for a specific skill."""
+        result = registry.read_skill_resource(skill_name, resource_name, args)
+        return str(result) if not isinstance(result, str) else result
+
+    @mcp.tool(
+        description=f"Execute skill scripts or functions with optional arguments.{skills_info}"
+    )
+    def run_skill(skill_name: str, function_name: str, args: dict | None = None) -> str:
+        """Execute skill scripts or functions with optional arguments."""
+        return registry.run_skill(skill_name, function_name, args)
+
+    return mcp

structured_skills-0.1.1/src/structured_skills/skill_registry.py

@@ -0,0 +1,226 @@
+import re
+import subprocess
+from dataclasses import dataclass
+from difflib import get_close_matches
+from pathlib import Path
+from typing import Any, Literal
+
+from structured_skills.cst.utils import execute_script as execute_script_impl
+from structured_skills.cst.utils import extract_function_info
+from structured_skills.validator import find_skill_md, parse_frontmatter, validate
+
+
+def _sanitize_skill_name(name: str) -> str:
+    """
+    Convert a skill name to a valid Python identifier.
+
+    - Replaces hyphens and spaces with underscores
+    - Removes invalid characters
+    - Ensures it doesn't start with a number
+    """
+    # Replace common separators with underscores
+    sanitized = name.replace("-", "_").replace(" ", "_")
+    # Remove any characters that aren't alphanumeric or underscore
+    sanitized = re.sub(r"[^a-zA-Z0-9_]", "", sanitized)
+    # Ensure it doesn't start with a number
+    if sanitized and sanitized[0].isdigit():
+        sanitized = "_" + sanitized
+    return sanitized
+
+
+@dataclass
+class Skill:
+    name: str
+    description: str
+    directory: Path
+    content: str
+
+
+class SkillRegistry:
+    def __init__(self, skill_root_dir: Path, exclude_skills: list[str] = []):
+        self.skill_root_dir = Path(skill_root_dir)
+        self._skills: list[Skill] | None = None
+        self._exclude_skills: list[str] = exclude_skills
+
+    def _load_skills(self) -> list[Skill]:
+        skills = []
+        for skill_dir in self.skill_root_dir.glob("*"):
+            if skill_dir.is_dir() and len(validate(skill_dir)) == 0:
+                skill_md = find_skill_md(skill_dir)
+                if skill_md:
+                    content = skill_md.read_text()
+                    metadata, body = parse_frontmatter(content)
+                    if metadata["name"] in self._exclude_skills:
+                        continue
+                    skills.append(
+                        Skill(
+                            name=metadata["name"],
+                            description=metadata["description"],
+                            directory=skill_dir,
+                            content=body,
+                        )
+                    )
+        if not skills:
+            raise Exception(f"No skills found in the directory: {self.skill_root_dir}")
+        return skills
+
+    @property
+    def skills(self) -> list[Skill]:
+        if self._skills is None:
+            self._skills = self._load_skills()
+        return self._skills
+
+    def get_skill_by_name(self, name: str) -> Skill | None:
+        for skill in self.skills:
+            if skill.name == name:
+                return skill
+        return None
+
+    def get_skill_names(self) -> list[str]:
+        return [s.name for s in self.skills]
+
+    def find_similar_skill_names(self, name: str) -> list[str]:
+        return get_close_matches(name, self.get_skill_names(), n=3, cutoff=0.6)
+
+    def list_skills(self) -> dict[str, str]:
+        return {s.name: s.description for s in self.skills}
+
+    def load_skill(self, skill_name: str) -> str:
+        skill = self.get_skill_by_name(skill_name)
+        if skill:
+            return skill.content
+
+        similar = self.find_similar_skill_names(skill_name)
+        close_matches_info = f" Did you mean {similar}?" if similar else ""
+        raise Exception(f"[load_skill] Could not find: {skill_name}.{close_matches_info}")
+
+    def read_skill_resource(
+        self, skill_name: str, resource_name: str, args: dict[str, Any] | None = None
+    ) -> str | dict[str, str]:
+        skill = self.get_skill_by_name(skill_name)
+        if not skill:
+            similar = self.find_similar_skill_names(skill_name)
+            close_matches_info = f" Did you mean {similar}?" if similar else ""
+            raise Exception(
+                f"[read_skill_resource] Could not find: {skill_name}.{close_matches_info}"
+            )
+
+        target_skill_dir = skill.directory
+
+        exact_file_match = list(target_skill_dir.glob(resource_name)) + list(
+            target_skill_dir.glob(f"*/{resource_name}")
+        )
+        if exact_file_match:
+            file_target = exact_file_match.pop()
+            return file_target.read_text()
+
+        if "." in resource_name:
+            raise Exception(f"[read_skill_resource] Unable to find resource: {resource_name}")
+
+        script_path = target_skill_dir / f"scripts/{resource_name}.py"
+        if script_path.exists():
+            if args is None:
+                return script_path.read_text()
+            else:
+                cmd = [str(script_path)]
+                for key, val in args.items():
+                    cmd.append(f"--{key}")
+                    cmd.append(f"{val}")
+                result = subprocess.run(cmd, capture_output=True, text=True)
+                return result.stdout
+
+        scripts_dir = target_skill_dir / "scripts"
+        if scripts_dir.exists():
+            for script in scripts_dir.glob("*.py"):
+                content = script.read_text()
+                if f"def {resource_name}(" in content:
+                    if args is None:
+                        info = extract_function_info(content, resource_name)
+                        return str(info)
+                    else:
+                        return execute_script_impl(content, resource_name, args or {})
+
+        raise Exception(f"[read_skill_resource] Unable to find resource: {resource_name}")
+
+    def run_skill(
+        self,
+        skill_name: str,
+        function_or_script_name: str,
+        args: dict[str, Any] | None = None,
+    ) -> str:
+        skill = self.get_skill_by_name(skill_name)
+        if not skill:
+            similar = self.find_similar_skill_names(skill_name)
+            close_matches_info = f" Did you mean {similar}?" if similar else ""
+            raise Exception(f"[run_skill] Could not find: {skill_name}.{close_matches_info}")
+
+        target_skill_dir = skill.directory
+
+        script_path = target_skill_dir / "scripts" / function_or_script_name
+        if script_path.exists():
+            cmd = [str(script_path)]
+            for key, val in (args or {}).items():
+                cmd.append(f"--{key}")
+                cmd.append(f"{val}")
+            result = subprocess.run(cmd, capture_output=True, text=True)
+            return result.stdout
+
+        scripts_dir = target_skill_dir / "scripts"
+        if scripts_dir.exists():
+            for script in scripts_dir.glob("*.py"):
+                content = script.read_text()
+                if f"def {function_or_script_name}(" in content:
+                    return str(execute_script_impl(content, function_or_script_name, args or {}))
+
+        raise Exception(
+            f"[run_skill] Failed to execute {skill_name} {function_or_script_name} {args}"
+        )
+
+
+def get_tool(
+    registry: SkillRegistry,
+    tool_name: Literal["list_skills", "load_skill", "read_skill_resource", "run_skill"],
+):
+    def add_docstring(description: str):
+        def inner(obj):
+            obj.__doc__ = description
+            return obj
+
+        return inner
+
+    skill_names = registry.get_skill_names()
+    skills_info = f"\n\nAvailable skills: {', '.join(skill_names)}"
+
+    @add_docstring(
+        f"List all available skills. Returns a mapping of skill names to their descriptions.{skills_info}"
+    )
+    def list_skills() -> dict[str, str]:
+        return registry.list_skills()
+
+    @add_docstring(f"Load full instructions for a specific skill by name.{skills_info}")
+    def load_skill(skill_name: str) -> str:
+        return registry.load_skill(skill_name)
+
+    @add_docstring(
+        f"Load full resource file, script, or function for a specific skill.{skills_info}"
+    )
+    def read_skill_resource(
+        skill_name: str, resource_name: str, args: dict[str, Any] | None = None
+    ) -> str | dict[str, str]:
+        return registry.read_skill_resource(skill_name, resource_name, args)
+
+    @add_docstring(f"Execute skill scripts or functions with optional arguments.{skills_info}")
+    def run_skill(
+        skill_name: str,
+        function_or_script_name: str,
+        args: dict[str, Any] | None = None,
+    ) -> str:
+        return registry.run_skill(skill_name, function_or_script_name, args)
+
+    tools = {
+        "list_skills": list_skills,
+        "load_skill": load_skill,
+        "read_skill_resource": read_skill_resource,
+        "run_skill": run_skill,
+    }
+    return tools[tool_name]

structured_skills-0.1.1/src/structured_skills/smolagents.py

@@ -0,0 +1,119 @@
+from typing import TYPE_CHECKING
+
+from structured_skills.skill_registry import SkillRegistry
+
+if TYPE_CHECKING:
+    from smolagents import Tool  # type: ignore
+
+
+def create_smolagents_tools(
+    registry: SkillRegistry, tools: list[str] | None = None
+) -> list["Tool"]:
+    """
+    Create smolagents Tool instances from a SkillRegistry.
+
+    Args:
+        registry: The SkillRegistry to create tools from
+        tools: Optional list of tool names to create. If None, creates all tools.
+               Valid names: "list_skills", "load_skill", "read_skill_resource", "run_skill"
+
+    Returns:
+        List of smolagents Tool instances
+    """
+    from smolagents import Tool  # type: ignore
+
+    tool_names = tools or [
+        "list_skills",
+        "load_skill",
+        "read_skill_resource",
+        "run_skill",
+    ]
+    result: list[Tool] = []
+
+    skill_names = registry.get_skill_names()
+    skills_info = f"Available skills: {', '.join(skill_names)}"
+
+    class ListSkillsTool(Tool):
+        name = "list_skills"
+        description = f"List all available skills. Returns a mapping of skill names to their descriptions. {skills_info}"
+        inputs = {}
+        output_type = "object"
+
+        def forward(self) -> dict[str, str]:
+            return registry.list_skills()
+
+    class LoadSkillTool(Tool):
+        name = "load_skill"
+        description = f"Load full instructions for a specific skill by name. {skills_info}"
+        inputs = {
+            "skill_name": {
+                "type": "string",
+                "description": "Name of the skill to load",
+            },
+        }
+        output_type = "string"
+
+        def forward(self, skill_name: str) -> str:
+            return registry.load_skill(skill_name)
+
+    class ReadSkillResourceTool(Tool):
+        name = "read_skill_resource"
+        description = (
+            f"Load full resource file, script, or function for a specific skill. {skills_info}"
+        )
+        inputs = {
+            "skill_name": {
+                "type": "string",
+                "description": "Name of the skill",
+            },
+            "resource_name": {
+                "type": "string",
+                "description": "Name of the resource to read",
+            },
+            "args": {
+                "type": "object",
+                "description": "Optional arguments for the resource",
+                "nullable": True,
+            },
+        }
+        output_type = "string"
+
+        def forward(self, skill_name: str, resource_name: str, args: dict | None = None) -> str:
+            result = registry.read_skill_resource(skill_name, resource_name, args)
+            return str(result) if not isinstance(result, str) else result
+
+    class RunSkillTool(Tool):
+        name = "run_skill"
+        description = f"Execute skill scripts or functions with optional arguments. {skills_info}"
+        inputs = {
+            "skill_name": {
+                "type": "string",
+                "description": "Name of the skill",
+            },
+            "function_name": {
+                "type": "string",
+                "description": "Name of the function or script to run",
+            },
+            "args": {
+                "type": "object",
+                "description": "Optional arguments for the function",
+                "nullable": True,
+            },
+        }
+        output_type = "string"
+
+        def forward(self, skill_name: str, function_name: str, args: dict | None = None) -> str:
+            return registry.run_skill(skill_name, function_name, args)
+
+    tool_classes = {
+        "list_skills": ListSkillsTool,
+        "load_skill": LoadSkillTool,
+        "read_skill_resource": ReadSkillResourceTool,
+        "run_skill": RunSkillTool,
+    }
+
+    for name in tool_names:
+        if name in tool_classes:
+            result.append(tool_classes[name]())
+
+    return result

structured_skills-0.1.1/src/structured_skills/validator.py

@@ -0,0 +1,267 @@
+"""
+Structured Skills Validation Logic.
+
+Extended from: https://github.com/agentskills/agentskills/tree/main
+"""
+
+import argparse
+import unicodedata
+from pathlib import Path
+from typing import Optional
+
+import strictyaml
+
+MAX_SKILL_NAME_LENGTH = 64
+MAX_DESCRIPTION_LENGTH = 1024
+MAX_COMPATIBILITY_LENGTH = 500
+
+# Allowed frontmatter fields per Agent Skills Spec
+ALLOWED_FIELDS = {
+    "name",
+    "description",
+    "license",
+    "allowed-tools",
+    "metadata",
+    "compatibility",
+}
+
+
+def find_skill_md(skill_dir: Path) -> Optional[Path]:
+    """Find the SKILL.md file in a skill directory.
+
+    Prefers SKILL.md (uppercase) but accepts skill.md (lowercase).
+
+    Args:
+        skill_dir: Path to the skill directory
+
+    Returns:
+        Path to the SKILL.md file, or None if not found
+    """
+    for name in ("SKILL.md", "skill.md"):
+        path = skill_dir / name
+        if path.exists():
+            return path
+    return None
+
+
+def parse_frontmatter(content: str) -> tuple[dict, str]:
+    """Parse YAML frontmatter from SKILL.md content.
+
+    Args:
+        content: Raw content of SKILL.md file
+
+    Returns:
+        Tuple of (metadata dict, markdown body)
+
+    Raises:
+        ValueError: If frontmatter is missing or invalid
+    """
+    if not content.startswith("---"):
+        raise ValueError("SKILL.md must start with YAML frontmatter (---)")
+
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        raise ValueError("SKILL.md frontmatter not properly closed with ---")
+
+    frontmatter_str = parts[1]
+    body = parts[2].strip()
+
+    try:
+        parsed = strictyaml.load(frontmatter_str)
+        metadata = parsed.data
+    except strictyaml.YAMLError as e:
+        raise ValueError(f"Invalid YAML in frontmatter: {e}")
+
+    if not isinstance(metadata, dict):
+        raise ValueError("SKILL.md frontmatter must be a YAML mapping")
+
+    if "metadata" in metadata and isinstance(metadata["metadata"], dict):
+        metadata["metadata"] = {str(k): str(v) for k, v in metadata["metadata"].items()}
+
+    return metadata, body
+
+
+def find_scripts(skill_dir: Path) -> list[Path]:
+    """Checks the validity of python files in scripts/ (if exists)
+
+    Args:
+        skill_dir: Path to the skill directory
+
+    Raises:
+        ValueError: if scripts/ folder exists without any python files
+    """
+    script_path = skill_dir.joinpath("scripts")
+    if not script_path.exists():
+        return []
+
+    scripts: list[Path] = list(script_path.glob("*.py"))
+    if len(scripts) == 0:
+        raise ValueError("scripts/ directory exists but no Python scripts found")
+    return scripts
+
+
+def _validate_name(name: str, skill_dir: Optional[Path] = None) -> list[str]:
+    """Validate skill name format and directory match.
+
+    Skill names support i18n characters (Unicode letters) plus hyphens.
+    Names must be lowercase and cannot start/end with hyphens.
+    """
+    errors = []
+
+    if not name or not isinstance(name, str) or not name.strip():
+        errors.append("Field 'name' must be a non-empty string")
+        return errors
+
+    name = unicodedata.normalize("NFKC", name.strip())
+
+    if len(name) > MAX_SKILL_NAME_LENGTH:
+        errors.append(
+            f"Skill name '{name}' exceeds {MAX_SKILL_NAME_LENGTH} character limit "
+            f"({len(name)} chars)"
+        )
+
+    if name != name.lower():
+        errors.append(f"Skill name '{name}' must be lowercase")
+
+    if name.startswith("-") or name.endswith("-"):
+        errors.append("Skill name cannot start or end with a hyphen")
+
+    if "--" in name:
+        errors.append("Skill name cannot contain consecutive hyphens")
+
+    if not all(c.isalnum() or c == "-" for c in name):
+        errors.append(
+            f"Skill name '{name}' contains invalid characters. "
+            "Only letters, digits, and hyphens are allowed."
+        )
+
+    if skill_dir is not None:
+        dir_name = unicodedata.normalize("NFKC", skill_dir.name)
+        if dir_name != name:
+            errors.append(f"Directory name '{skill_dir.name}' must match skill name '{name}'")
+
+    return errors
+
+
+def _validate_description(description: str) -> list[str]:
+    """Validate description format."""
+    errors = []
+
+    if not description or not isinstance(description, str) or not description.strip():
+        errors.append("Field 'description' must be a non-empty string")
+        return errors
+
+    if len(description) > MAX_DESCRIPTION_LENGTH:
+        errors.append(
+            f"Description exceeds {MAX_DESCRIPTION_LENGTH} character limit "
+            f"({len(description)} chars)"
+        )
+
+    return errors
+
+
+def _validate_compatibility(compatibility: str) -> list[str]:
+    """Validate compatibility format."""
+    errors = []
+
+    if not isinstance(compatibility, str):
+        errors.append("Field 'compatibility' must be a string")
+        return errors
+
+    if len(compatibility) > MAX_COMPATIBILITY_LENGTH:
+        errors.append(
+            f"Compatibility exceeds {MAX_COMPATIBILITY_LENGTH} character limit "
+            f"({len(compatibility)} chars)"
+        )
+
+    return errors
+
+
+def _validate_metadata_fields(metadata: dict) -> list[str]:
+    """Validate that only allowed fields are present."""
+    errors = []
+
+    extra_fields = set(metadata.keys()) - ALLOWED_FIELDS
+    if extra_fields:
+        errors.append(
+            f"Unexpected fields in frontmatter: {', '.join(sorted(extra_fields))}. "
+            f"Only {sorted(ALLOWED_FIELDS)} are allowed."
+        )
+
+    return errors
+
+
+def validate_metadata(metadata: dict, skill_dir: Optional[Path] = None) -> list[str]:
+    """Validate parsed skill metadata.
+
+    This is the core validation function that works on already-parsed metadata,
+    avoiding duplicate file I/O when called from the parser.
+
+    Args:
+        metadata: Parsed YAML frontmatter dictionary
+        skill_dir: Optional path to skill directory (for name-directory match check)
+
+    Returns:
+        List of validation error messages. Empty list means valid.
+    """
+    errors = []
+    errors.extend(_validate_metadata_fields(metadata))
+
+    if "name" not in metadata:
+        errors.append("Missing required field in frontmatter: name")
+    else:
+        errors.extend(_validate_name(metadata["name"], skill_dir))
+
+    if "description" not in metadata:
+        errors.append("Missing required field in frontmatter: description")
+    else:
+        errors.extend(_validate_description(metadata["description"]))
+
+    if "compatibility" in metadata:
+        errors.extend(_validate_compatibility(metadata["compatibility"]))
+
+    return errors
+
+
+def validate(skill_dir: Path) -> list[str]:
+    """Validate a skill directory.
+
+    Args:
+        skill_dir: Path to the skill directory
+
+    Returns:
+        List of validation error messages. Empty list means valid.
+    """
+    skill_dir = Path(skill_dir)
+
+    if not skill_dir.exists():
+        return [f"Path does not exist: {skill_dir}"]
+
+    if not skill_dir.is_dir():
+        return [f"Not a directory: {skill_dir}"]
+
+    skill_md = find_skill_md(skill_dir)
+    if skill_md is None:
+        return ["Missing required file: SKILL.md"]
+
+    try:
+        content = skill_md.read_text()
+        metadata, _ = parse_frontmatter(content)
+    except ValueError as e:
+        return [str(e)]
+
+    try:
+        _ = find_scripts(skill_dir)
+    except ValueError as e:
+        return [str(e)]
+
+    return validate_metadata(metadata, skill_dir)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        prog="SkillStructParser", description="Structured Skill Parsing"
+    )
+    parser.add_argument("skill_dir")
+    args = parser.parse_args()
+    validate(Path(args.skill_dir))