broskill 0.1.0__py3-none-any.whl

broskill/__init__.py

@@ -0,0 +1,14 @@
+from broskill.data_specs.skill import Skill, SkillStatus
+from broskill.data_specs.tool import Arg, Tool
+from broskill.processing.skill import SkillControl
+from broskill.processing.tool import ToolControl
+
+__version__ = "0.1.0"
+__all__ = [
+    "Arg",
+    "Skill",
+    "SkillControl",
+    "SkillStatus",
+    "Tool",
+    "ToolControl"
+]

broskill/data_specs/skill.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+
+
+class SkillStatus(StrEnum):
+    STABLE = 'stable'
+    EXPERIMENT = 'experiment'
+    DEPRECATED = 'deprecated'
+
+@dataclass
+class Skill:
+    name:str = field(
+        metadata={'description': "a skill name in frontmatter"}
+    )
+    description:str = field(
+        metadata={'description': "a description of the skill in frontmatter"}
+    )
+    version:str = field(
+        metadata={'description': "a skill's version recommending as v0.1.0 (vMajor.Minor.Patch)"}
+    )
+    path:Path = field(
+        metadata={'description': "a directory path of the skill."}
+    )
+    tags:list[str] | None = field(
+        metadata={'description': "tags will use later for searching and filtering"}, 
+        default=None
+    )
+    keywords:list[str] | None = field(
+        metadata={'description': "keywords will use later for searching and filtering"}, 
+        default=None
+    )
+    default:bool = field(
+        metadata={'description': "default here tells a program that this skill must be loaded or display"}, 
+        default=False
+    )
+    status:SkillStatus | None = field(
+        metadata={'description': "status will be: stable if you test it and pass, experiment if you are in developing phase, deprecated if you plan not to use it."}, 
+        default=SkillStatus.EXPERIMENT
+    )

broskill/data_specs/tool.py

@@ -0,0 +1,54 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+DTYPE_MAP = {
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+}
+
+@dataclass
+class Arg:
+    name:str = field(
+        metadata={"description": "the argument's name, taken from its dest in get_args()"}
+    )
+    type:Any = field(
+        metadata={"description": "the argument's Python type (e.g. str, int) from get_args(), converted to its JSON-schema type string (e.g. 'string', 'integer') on init"}
+    )
+    description:str | None = field(
+        metadata={"description": "the argument's help text, taken from get_args()"},
+        default=None
+    )
+    required:bool | None = field(
+        metadata={"description": "whether the argument is required to call the tool"},
+        default=True
+    )
+
+    def __post_init__(self):
+        """Resolve `type` to its JSON-schema string, if given as a Python type.
+
+        Raises:
+            ValueError: If `type` is a Python type not in `DTYPE_MAP`.
+        """
+        if isinstance(self.type, str):
+            return
+        if self.type not in DTYPE_MAP:
+            raise ValueError(f"Unsupported type for arg '{self.name}': {self.type}")
+        self.type = DTYPE_MAP[self.type]
+
+@dataclass
+class Tool:
+    name:str = field(
+        metadata={"description": "the tool's name, taken from the script's filename"}
+    )
+    description:str = field(
+        metadata={"description": "the tool's description, taken from get_args()'s parser description"}
+    )
+    args:list[Arg] = field(
+        metadata={"description": "the tool's arguments"}
+    )
+    path:Path = field(
+        metadata={"description": "the path to the script that implements this tool"}
+    )

broskill/processing/path.py

@@ -0,0 +1,38 @@
+import re
+from pathlib import Path
+
+
+def strip_path(path: str) -> str:
+    """Stripping the path in to the bare path
+    Args:
+        path (str): The path to be stripped
+    Returns:
+        str: The stripped path
+    Examples:
+        >>> path = strip_path(path='*/references/*')
+        >>> print(path)
+        references
+    """
+    path = re.sub(r'^[*/]+', '', path)
+    path = re.sub(r'[*/]+$', '', path)
+    return path
+
+def find_root(start: Path | None = None, marker: str = "skills") -> Path:
+    """Walk upward from `start` (default: cwd) looking for a folder
+    containing `marker`, the same trick git uses for `.git`.
+
+    Args:
+        start (Path): Where to begin the search. Defaults to Path.cwd().
+        marker (str): Folder name that identifies the project root.
+
+    Returns:
+        Path: The first ancestor (including `start`) containing `marker/`.
+
+    Raises:
+        ValueError: If no ancestor contains `marker/`.
+    """
+    current = (start or Path.cwd()).resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / marker).is_dir():
+            return candidate
+    raise ValueError(f"No '{marker}/' folder found in {current} or any parent")

broskill/processing/skill.py

@@ -0,0 +1,169 @@
+import re
+from pathlib import Path
+
+import yaml
+
+from broskill.data_specs.skill import Skill
+
+
+def split_frontmatter(text: str) -> tuple[dict, str]:
+    """Split a SKILL.md file's text into its frontmatter and body.
+
+    Args:
+        text (str): Raw file contents, expected to start with a `---`
+            delimited YAML block followed by the markdown body.
+
+    Returns:
+        tuple[dict, str]: The parsed frontmatter as a dict, and the
+            remaining body text with surrounding whitespace stripped.
+
+    Raises:
+        ValueError: If no `---` delimited frontmatter block is found.
+    """
+    match = re.match(r'^---\n(.*?)\n---\n?(.*)', text, re.DOTALL)
+    if not match:
+        raise ValueError('No frontmatter block found')
+    metadata = yaml.safe_load(match.group(1)) or {}
+    body = match.group(2).strip()
+    return metadata, body
+
+class SkillControl:
+    """Discovers, loads, and reads skills from a skills directory.
+
+    `root` is the skills directory itself (e.g. `project_root / "skills"`),
+    not the project root — every method searches directly under `root`,
+    with no implicit `"skills"` subfolder appended.
+
+    Skills loaded via `load_skill`/`list_skills` are cached on `self.skills`
+    (keyed by skill name), so later calls that only need a skill's path
+    (`load_skill_extension`) don't need to search the filesystem again.
+
+    Attributes:
+        root (Path): Default skills directory (e.g. `project_root / "skills"`),
+            not the project root.
+        skills (dict[str, Skill]): Skills loaded so far, keyed by name.
+    """
+
+    def __init__(self, root:Path):
+        """Initialize the controller.
+
+        Args:
+            root (Path): Default skills directory (e.g. `project_root / "skills"`),
+                not the project root.
+        """
+        self.root:Path = root
+        self.skills:dict[str, Skill] = {}
+
+    def get_skill_path(self, skill_name:str)->Path | None:
+        """Get a previously loaded skill's directory path.
+
+        Args:
+            skill_name (str): Name of the skill, as registered by `load_skill`.
+
+        Returns:
+            Path | None: The skill's directory, or None if it hasn't been
+                loaded yet (call `load_skill` first).
+        """
+        skill = self.skills.get(skill_name, None)
+        if skill:
+            return skill.path
+        return None
+
+    def get_root(self, root:Path|None)->Path|None:
+        """Resolve the skills directory to use for a call.
+
+        Args:
+            root (Path | None): An explicit skills directory to use, or None
+                to fall back to `self.root`.
+
+        Returns:
+            Path | None: `root` if given, otherwise `self.root`.
+        """
+        if root is None:
+            return self.root
+        return root
+
+    def list_skills(self, root:Path|None=None)->list[Skill]|list:
+        """List and load every skill under the skills directory.
+
+        Args:
+            root (Path | None): Skills directory to search. Defaults to `self.root`.
+
+        Returns:
+            list[Skill]: Every skill discovered by scanning `root` for
+                `SKILL.md` files.
+
+        Raises:
+            FileNotFoundError: If `root` doesn't exist.
+        """
+        root = self.get_root(root)
+        if not root.exists():
+            raise FileNotFoundError(f"Skills directory not found: {root}")
+        skills = list(root.rglob("SKILL.md"))
+        _ = [self.load_skill(s.parent.name, root) for s in skills]
+        return list(self.skills.values())
+
+    def load_skill(self, skill_name:str, root:Path|None=None)->str|None:
+        """Load a skill by name and register it into `self.skills`.
+
+        Args:
+            skill_name (str): Name of the skill's directory under the skills directory.
+            root (Path | None): Skills directory to search. Defaults to `self.root`.
+
+        Returns:
+            Skill | None: The loaded skill, or None if no directory named
+                `skill_name` exists under `root`.
+
+        Raises:
+            ValueError: If a path named `skill_name` exists but none of the
+                matches is a valid skill directory, or if its `SKILL.md`
+                frontmatter doesn't match the `Skill` dataclass fields.
+            FileNotFoundError: If the matched directory has no `SKILL.md`.
+        """
+        root = self.get_root(root)
+        skills = list(root.rglob(skill_name))
+        if len(skills) == 0:
+            return None
+        candidates = [s for s in skills if s.is_dir() and s.exists()]
+        if not candidates:
+            raise ValueError(f"No skill directory found for '{skill_name}' under {root}")
+        skill = candidates[0]
+        skill_md = skill / "SKILL.md"
+        if not skill_md.is_file():
+            raise FileNotFoundError(f"'{skill_md}' not found for skill '{skill_name}'")
+        text = skill_md.read_text(encoding='utf-8')
+        metadata, body = split_frontmatter(text)
+        try:
+            _skill = Skill(**metadata, path=skill)
+        except TypeError as e:
+            raise ValueError(f"'{skill_md}' frontmatter doesn't match the Skill schema: {e}") from e
+        self.skills[skill_name] = _skill
+        return body
+
+    def load_skill_extension(self, skill_name:str, path:str, root:Path|None=None)->str|None:
+        """Load any skill artifact under its `references/`, `scripts/`, or `assets/` folder.
+
+        Args:
+            skill_name (str): Name of the skill, as registered by `load_skill`.
+            path (str): Path to the artifact, relative to the skill's directory
+                (e.g. `references/script.md`, `scripts/read_file.py`).
+            root (Path | None): Project root, currently unused directly (the
+                skill's own registered path is used) but accepted for a
+                consistent signature with the other loaders.
+
+        Returns:
+            str | None: The artifact's text content, or None if `path` doesn't
+                exist under the skill's directory.
+
+        Raises:
+            ValueError: If `skill_name` hasn't been loaded yet — call
+                `load_skill` first.
+        """
+        root = self.get_root(root)
+        skill_path = self.get_skill_path(skill_name)
+        if skill_path is None:
+            raise ValueError(f"Skill '{skill_name}' is not loaded — call load_skill first")
+        target = skill_path / path
+        if target.is_file():
+            return target.read_text(encoding='utf-8')
+        return None

broskill/processing/tool.py

@@ -0,0 +1,108 @@
+import importlib.util
+from typing import Any
+
+from broskill.data_specs.tool import Arg, Tool
+from broskill.processing.skill import SkillControl
+
+
+def to_args(args: dict) -> list[Any]:
+    """Convert a dict of tool arguments into a CLI argument list.
+
+    Args:
+        args (dict): Argument names mapped to their values, e.g. `{"path": "a.md"}`.
+
+    Returns:
+        list[Any]: A flat `--name value` list suitable for `subprocess.run`,
+            e.g. `["--path", "a.md"]`. Empty list if `args` is falsy.
+    """
+    if not args:
+        return []
+    args_list = []
+    for k, v in args.items():
+        args_list.extend([f"--{k}", v])
+    return args_list
+
+
+class ToolControl:
+    """Loads a skill's `scripts/*.py` files as callable `Tool` schemas.
+
+    Composes with a `SkillControl` for skill_name -> directory resolution,
+    so both classes share one source of truth for where a skill lives.
+    Every script must define a module-level `get_args()` returning an
+    `argparse.ArgumentParser` (see `skills/create-skill/references/script.md`);
+    that parser is introspected to build the `Tool`/`Arg` schema.
+
+    Attributes:
+        skills (SkillControl): Used to resolve a skill name to its directory.
+        tools (dict[str, Tool]): Tools loaded so far, keyed by `"skill_name:path"`.
+    """
+
+    def __init__(self, skills: SkillControl):
+        """Initialize the controller.
+
+        Args:
+            skills (SkillControl): The skill controller to resolve skill
+                directories through.
+        """
+        self.skills = skills
+        self.tools: dict[str, Tool] = {}
+
+    def load_tool(self, skill_name: str, path: str) -> Tool:
+        """Load a skill's script as a `Tool` schema, caching the result.
+
+        Args:
+            skill_name (str): Name of the skill, as registered by `self.skills.load_skill`.
+            path (str): Path to the script, relative to the skill's directory
+                (e.g. `scripts/read_file.py`).
+
+        Returns:
+            Tool: The tool schema built from the script's `get_args()` parser.
+
+        Raises:
+            ValueError: If `skill_name` isn't loaded, the file can't be loaded
+                as a Python module, it has no `get_args()`, or one of its
+                arguments uses a type `Arg` doesn't recognize (see `DTYPE_MAP`
+                in `broskill.data_specs.tool`).
+            FileNotFoundError: If `path` doesn't exist under the skill's directory.
+        """
+        skill_path = self.skills.get_skill_path(skill_name)
+        if skill_path is None:
+            raise ValueError(f"Skill '{skill_name}' is not loaded — call load_skill first")
+
+        cache_key = f"{skill_name}:{path}"
+        if cache_key in self.tools:
+            return self.tools[cache_key]
+
+        script_path = skill_path / path
+        if not script_path.is_file():
+            raise FileNotFoundError(f"Script not found: {script_path}")
+
+        spec = importlib.util.spec_from_file_location(script_path.stem, script_path)
+        if spec is None or spec.loader is None:
+            raise ValueError(f"Could not load '{script_path}' as a Python module")
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+
+        if not hasattr(module, "get_args"):
+            raise ValueError(f"'{script_path}' must define a get_args() function")
+        parser = module.get_args()
+
+        args = []
+        for action in parser._actions:
+            if action.dest == "help":
+                continue
+            try:
+                args.append(
+                    Arg(
+                        name=action.dest,
+                        type=action.type,
+                        description=action.help,
+                        required=action.required,
+                    )
+                )
+            except ValueError as e:
+                raise ValueError(f"{e} (in '{script_path}')") from e
+
+        tool = Tool(name=script_path.stem, description=parser.description, args=args, path=script_path)
+        self.tools[cache_key] = tool
+        return tool

broskill-0.1.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: broskill
+Version: 0.1.0
+Summary: Lightweight, quick-loading skill loader for agentic projects — discovers skills (SKILL.md + references/scripts/assets), loads their instructions, and turns their scripts into callable tools.
+Project-URL: Repository, https://github.com/datanooblol/broskill
+Project-URL: Changelog, https://github.com/datanooblol/broskill/blob/main/VERSIONS.md
+Author: datanooblol
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0.3
+Description-Content-Type: text/markdown
+
+# broskill
+
+yo. **broskill** is a lightweight, quick-loading skill loader for agentic projects — a "skill" being a folder with instructions (`SKILL.md`) plus optional reference docs, python scripts as tools, and static assets. broskill's whole job is finding those folders, loading them, and turning their scripts into callable tools. That's it. That's the lib.
+
+part of the **bro lib family** — small, opinionated, do-one-thing tools built to stop us from writing the same glue code every time we spin up a new agentic project.
+
+## why this exists
+
+every time you start a new agent project you end up rebuilding the same boring plumbing: some way to discover "skills," some way to load their instructions, some way to turn a script into a tool the model can call. broskill is that plumbing, ripped out of real projects where we got tired of writing it again and again.
+
+**heads up:** this is an opinionated lib. it works one way — SKILL.md + `references/` + `scripts/` + `assets/`, discovered off a `skills/` folder. if that convention fits your project, great, you just saved yourself a bunch of setup. if it doesn't, this probably isn't your lib, and that's fine — go build your own, that's basically how broskill got made in the first place. inspired by real work and real struggle. voilà, here it is.
+
+## install
+
+```bash
+uv pip install -e .
+```
+
+## the shape of a skill
+
+```
+skills/
+  read-file/
+    SKILL.md              # frontmatter (name, description, version, ...) + instructions
+    references/
+      script.md            # optional deep-dive docs, loaded on demand
+    scripts/
+      read_file.py          # a get_args()-based python script -> becomes a callable tool
+    assets/
+      template.md            # optional static files a skill hands out
+```
+
+`SKILL.md`'s frontmatter has to match the [`Skill`](src/broskill/data_specs/skill.py) dataclass field-for-field (`name`, `description`, `version` required; `tags`, `keywords`, `default`, `status` optional). Want to build one from scratch? There's a skill for that: [`skills/create-skill`](skills/create-skill/SKILL.md).
+
+## quick start
+
+### load skills — `SkillControl`
+
+```python
+from broskill.processing.path import find_root
+from broskill.processing.skill import SkillControl
+
+root = find_root()  # walks up 'til it finds a skills/ folder
+sc = SkillControl(root=root / "skills")
+
+for skill in sc.list_skills():
+    print(skill.name, "-", skill.description)
+
+body = sc.load_skill("read-file")          # -> SKILL.md's instructions, as a str
+ref = sc.load_skill_extension("read-file", "references/script.md")
+```
+
+Full runnable version: [`examples/case1.py`](examples/case1.py).
+
+### turn a script into a tool — `ToolControl`
+
+```python
+from broskill.processing.skill import SkillControl
+from broskill.processing.tool import ToolControl, to_args
+import subprocess, sys
+
+sc = SkillControl(root=root / "skills")
+sc.load_skill("read-file")
+
+tc = ToolControl(sc)
+tool = tc.load_tool("read-file", "scripts/list_files.py")
+# tool.name, tool.description, tool.args -> ready to hand to an LLM's tool schema
+
+result = subprocess.run(
+    [sys.executable, str(tool.path), *to_args({"path": "skills/**/*.md"})],
+    capture_output=True, text=True,
+)
+```
+
+A script only needs one thing to become a tool: a module-level `get_args()` returning an `argparse.ArgumentParser`. broskill reads that parser and builds the schema for you — no separate tool-definition file to keep in sync. See [`skills/create-skill/references/script.md`](skills/create-skill/references/script.md) for the full contract.
+
+Full runnable version: [`examples/case2.py`](examples/case2.py).
+
+## running the tests
+
+```bash
+uv run pytest
+uv run ruff check
+```
+
+## more
+
+- [`VERSIONS.md`](VERSIONS.md) — changelog
+- [`LICENSE`](LICENSE) — MIT
+- [`skills/create-skill`](skills/create-skill/SKILL.md) — a skill that helps you build more skills
+- [`skills/read-file`](skills/read-file/SKILL.md) — the skill used in both examples above, a decent reference for what a real skill looks like
+
+stay chill, ship skills. 🤙

broskill-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+broskill/__init__.py,sha256=VDKp94tx9alpwa69Ca1ZvHMxMncXAdUoc0z7cMcAlWI,334
+broskill/data_specs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+broskill/data_specs/skill.py,sha256=XmZAi4qhqD9pTsv7AeeSoZ9RjibAu3fyS-ZtQ2HzNnc,1375
+broskill/data_specs/tool.py,sha256=dEuafTTAyf7cYlhYcn0Ir--_SjzV3gqA8ebetMQTINs,1739
+broskill/processing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+broskill/processing/path.py,sha256=UbPo84sS7OcblBx4A3r0h9pN_K6ls4xD1Z4n9AeRwTE,1194
+broskill/processing/skill.py,sha256=Mc0OCvkFkJ3lUuX7SILnc9_VNDa3UX3UtyEj59SR5jg,6462
+broskill/processing/tool.py,sha256=i4iaEkybDHrOiO_I_Xhd5hRrBSi_lVLUVPZ3x309cTc,4066
+broskill-0.1.0.dist-info/METADATA,sha256=y8cni_eMO6rx4qNn4yPsQb3aUoyHVRHG_XxUR7Jq8U8,4629
+broskill-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+broskill-0.1.0.dist-info/licenses/LICENSE,sha256=n-AwFsgZAbsTeTLfRf93WkKsAgYP_qZUDlNmf5jwZlM,1067
+broskill-0.1.0.dist-info/RECORD,,

broskill-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

broskill-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 doublebank
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.