skillbridge-ai 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Tristan Herpich
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,173 @@
1
+ Metadata-Version: 2.4
2
+ Name: skillbridge-ai
3
+ Version: 0.1.0
4
+ Summary: Discover and safely invoke application capabilities through portable manifests
5
+ Author: SkillBridge contributors
6
+ License: MIT
7
+ Keywords: agents,skills,discovery,cli,interop
8
+ Requires-Python: >=3.10
9
+ Description-Content-Type: text/markdown
10
+ License-File: LICENSE
11
+ Dynamic: license-file
12
+
13
+ ![SkillBridge banner](assets/banner.svg)
14
+
15
+ # SkillBridge
16
+
17
+ **Discover application capabilities without requiring every application to implement an agent protocol.** A small, language-neutral, local-first proof of concept.
18
+
19
+ > **Status: v0.1.0 MVP.** The working features are local Markdown/JSON discovery, permission-gated command execution, and an optional token-protected Python HTTP bridge. **Not yet implemented:** automatic scanning of installed apps, MCP/OpenAPI adapters, native Rust core/DLL, npx installer, sandboxed execution, or automatic LLM integration. This is not an MCP implementation.
20
+
21
+ ## Install in seconds
22
+
23
+ Requires Python 3.10+ and Git. **The package is not published to PyPI yet.** After downloading or cloning this repository:
24
+
25
+ ```bash
26
+ python -m pip install -e .
27
+ skillbridge discover examples/manifests
28
+ skillbridge inspect examples/manifests
29
+ ```
30
+
31
+ For a clean virtual environment:
32
+
33
+ ```bash
34
+ python -m venv .venv
35
+ # Windows PowerShell:
36
+ .venv\Scripts\Activate.ps1
37
+ # Linux/macOS:
38
+ # source .venv/bin/activate
39
+ python -m pip install -e .
40
+ ```
41
+
42
+ ## Zero-server discovery
43
+
44
+ Create `skillbridge.json` in any application folder:
45
+
46
+ ```json
47
+ {
48
+ "app": "TestApp",
49
+ "skills": [
50
+ {
51
+ "name": "greet",
52
+ "description": "Say hello to a user",
53
+ "type": "command",
54
+ "inputs": {"name": "string"},
55
+ "argv": ["python", "hello.py", "{name}"]
56
+ }
57
+ ]
58
+ }
59
+ ```
60
+
61
+ A compatible agent or tool runner can discover it with:
62
+
63
+ ```bash
64
+ skillbridge discover ./testapp
65
+ ```
66
+
67
+ Alternatively, create `SKILL.md` or `AGENT.md`. SkillBridge will read it as **documentation only**, not silently execute commands mentioned in Markdown.
68
+
69
+ ### Call a command (requires explicit approval)
70
+
71
+ ```bash
72
+ skillbridge call examples/manifests greet --args '{"name":"Forge"}' --allow-execute
73
+ ```
74
+
75
+ On PowerShell, quoting JSON varies by shell. The CLI deliberately refuses execution without `--allow-execute`. Commands use argv arrays and `shell=False`, but this **does not sandbox** programs. Only run manifests you trust.
76
+
77
+ ## Python: expose real functions
78
+
79
+ ```python
80
+ from skillbridge import Bridge
81
+
82
+ bridge = Bridge("TestApp")
83
+ bridge.expose("greet", "Say hello", lambda name: f"Hi {name}", {"name": "string"})
84
+ bridge.serve() # 127.0.0.1:8765, prints generated bearer token
85
+ ```
86
+
87
+ Run `python examples/python/app.py`. A client with the token can then request:
88
+
89
+ ```bash
90
+ curl -H "Authorization: Bearer YOUR_TOKEN" http://127.0.0.1:8765/manifest
91
+ curl -X POST http://127.0.0.1:8765/call -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"skill":"greet","args":{"name":"Forge"}}'
92
+ ```
93
+
94
+ **Keep the token private.** The HTTP bridge is loopback-only, not production-hardened, and functions run with your application's permissions. Do not expose it to untrusted users.
95
+
96
+ ## Examples in five languages
97
+
98
+ The same `skillbridge discover` JSON output can be consumed by any language. The examples demonstrate **CLI interoperability**, not native bindings or direct function exposure for every language.
99
+
100
+ | Language | Example | Run from directory |
101
+ | --- | --- | --- |
102
+ | Python | [`examples/python/app.py`](examples/python/app.py) | `python app.py` |
103
+ | TypeScript / Node.js | [`examples/typescript/demo.mjs`](examples/typescript/demo.mjs) | `node demo.mjs` |
104
+ | Go | [`examples/go/main.go`](examples/go/main.go) | `go run main.go` |
105
+ | Rust | [`examples/rust/main.rs`](examples/rust/main.rs) | `rustc main.rs -o demo && ./demo` |
106
+ | C++ | [`examples/cpp/main.cpp`](examples/cpp/main.cpp) | `g++ main.cpp -o demo && ./demo` |
107
+
108
+ Run the cross-language examples from their own folders after installing the CLI.
109
+
110
+ ## Architecture
111
+
112
+ ```text
113
+ Existing app -> skillbridge.json / SKILL.md
114
+ |
115
+ Agent / SDK -> discovery CLI -> JSON capabilities
116
+ |
117
+ explicit approval
118
+ |
119
+ argv execution
120
+
121
+ Python app -> Bridge.expose() -> local HTTP /manifest + /call
122
+ ```
123
+
124
+ **Design direction:** add pluggable adapters for MCP, OpenAPI, HTTP and native ABI while retaining one capability schema. Discovery is read-only; execution is separately authorized. No LLM is required to test the bridge.
125
+
126
+ ## Security boundaries
127
+
128
+ - Local discovery never runs a command.
129
+ - Commands require `--allow-execute` each invocation.
130
+ - Command inputs are type-checked; arguments are passed without a shell.
131
+ - The optional HTTP server binds to loopback and requires a bearer token.
132
+ - **No process isolation or sandbox exists in this MVP.** A malicious approved manifest can execute arbitrary programs. Inspect manifests before approving.
133
+ - Avoid exposing arbitrary SQL or filesystem operations. Design narrow, least-privilege skills.
134
+
135
+ ## Test
136
+
137
+ ```bash
138
+ python -m unittest discover -s tests -v
139
+ python -m build # optional: first pip install build
140
+ ```
141
+
142
+ ## How to publish `pip install skillbridge`
143
+
144
+ `pip install skillbridge` only works after you publish a package with that exact name to [PyPI](https://pypi.org/). **Check name availability first**; this repository does not claim the name is available.
145
+
146
+ 1. Create a PyPI account and configure trusted publishing (recommended) or an API token.
147
+ 2. Update `name`, `version`, authors, and project metadata in `pyproject.toml`.
148
+ 3. Run `python -m pip install build twine` then `python -m build`.
149
+ 4. Validate with `python -m twine check dist/*` and publish with `python -m twine upload dist/*` (or use trusted publishing in CI).
150
+ 5. After publication: `python -m pip install skillbridge`.
151
+
152
+ For a GitHub install **before** PyPI publication, replace `OWNER/REPO` with your actual GitHub path:
153
+
154
+ ```bash
155
+ python -m pip install 'git+https://github.com/OWNER/REPO.git'
156
+ ```
157
+
158
+ ## Roadmap
159
+
160
+ - [x] Local JSON/Markdown discovery
161
+ - [x] CLI read-only inspection and opt-in execution
162
+ - [x] Python HTTP bridge with token auth
163
+ - [x] Cross-language CLI examples
164
+ - [ ] MCP/OpenAPI discovery adapters
165
+ - [ ] Signed manifests and explicit permission scopes
166
+ - [ ] Sandboxed execution via isolated processes / WASM
167
+ - [ ] Native Rust core with C ABI (.dll/.so/.dylib)
168
+ - [ ] npm/npx convenience CLI
169
+ - [ ] Auto-discovery and Forge integration
170
+
171
+ ## Contributing
172
+
173
+ Issues and pull requests welcome. Please include a reproducible example and tests for behavior changes. See [LICENSE](LICENSE) (MIT).
@@ -0,0 +1,161 @@
1
+ ![SkillBridge banner](assets/banner.svg)
2
+
3
+ # SkillBridge
4
+
5
+ **Discover application capabilities without requiring every application to implement an agent protocol.** A small, language-neutral, local-first proof of concept.
6
+
7
+ > **Status: v0.1.0 MVP.** The working features are local Markdown/JSON discovery, permission-gated command execution, and an optional token-protected Python HTTP bridge. **Not yet implemented:** automatic scanning of installed apps, MCP/OpenAPI adapters, native Rust core/DLL, npx installer, sandboxed execution, or automatic LLM integration. This is not an MCP implementation.
8
+
9
+ ## Install in seconds
10
+
11
+ Requires Python 3.10+ and Git. **The package is not published to PyPI yet.** After downloading or cloning this repository:
12
+
13
+ ```bash
14
+ python -m pip install -e .
15
+ skillbridge discover examples/manifests
16
+ skillbridge inspect examples/manifests
17
+ ```
18
+
19
+ For a clean virtual environment:
20
+
21
+ ```bash
22
+ python -m venv .venv
23
+ # Windows PowerShell:
24
+ .venv\Scripts\Activate.ps1
25
+ # Linux/macOS:
26
+ # source .venv/bin/activate
27
+ python -m pip install -e .
28
+ ```
29
+
30
+ ## Zero-server discovery
31
+
32
+ Create `skillbridge.json` in any application folder:
33
+
34
+ ```json
35
+ {
36
+ "app": "TestApp",
37
+ "skills": [
38
+ {
39
+ "name": "greet",
40
+ "description": "Say hello to a user",
41
+ "type": "command",
42
+ "inputs": {"name": "string"},
43
+ "argv": ["python", "hello.py", "{name}"]
44
+ }
45
+ ]
46
+ }
47
+ ```
48
+
49
+ A compatible agent or tool runner can discover it with:
50
+
51
+ ```bash
52
+ skillbridge discover ./testapp
53
+ ```
54
+
55
+ Alternatively, create `SKILL.md` or `AGENT.md`. SkillBridge will read it as **documentation only**, not silently execute commands mentioned in Markdown.
56
+
57
+ ### Call a command (requires explicit approval)
58
+
59
+ ```bash
60
+ skillbridge call examples/manifests greet --args '{"name":"Forge"}' --allow-execute
61
+ ```
62
+
63
+ On PowerShell, quoting JSON varies by shell. The CLI deliberately refuses execution without `--allow-execute`. Commands use argv arrays and `shell=False`, but this **does not sandbox** programs. Only run manifests you trust.
64
+
65
+ ## Python: expose real functions
66
+
67
+ ```python
68
+ from skillbridge import Bridge
69
+
70
+ bridge = Bridge("TestApp")
71
+ bridge.expose("greet", "Say hello", lambda name: f"Hi {name}", {"name": "string"})
72
+ bridge.serve() # 127.0.0.1:8765, prints generated bearer token
73
+ ```
74
+
75
+ Run `python examples/python/app.py`. A client with the token can then request:
76
+
77
+ ```bash
78
+ curl -H "Authorization: Bearer YOUR_TOKEN" http://127.0.0.1:8765/manifest
79
+ curl -X POST http://127.0.0.1:8765/call -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"skill":"greet","args":{"name":"Forge"}}'
80
+ ```
81
+
82
+ **Keep the token private.** The HTTP bridge is loopback-only, not production-hardened, and functions run with your application's permissions. Do not expose it to untrusted users.
83
+
84
+ ## Examples in five languages
85
+
86
+ The same `skillbridge discover` JSON output can be consumed by any language. The examples demonstrate **CLI interoperability**, not native bindings or direct function exposure for every language.
87
+
88
+ | Language | Example | Run from directory |
89
+ | --- | --- | --- |
90
+ | Python | [`examples/python/app.py`](examples/python/app.py) | `python app.py` |
91
+ | TypeScript / Node.js | [`examples/typescript/demo.mjs`](examples/typescript/demo.mjs) | `node demo.mjs` |
92
+ | Go | [`examples/go/main.go`](examples/go/main.go) | `go run main.go` |
93
+ | Rust | [`examples/rust/main.rs`](examples/rust/main.rs) | `rustc main.rs -o demo && ./demo` |
94
+ | C++ | [`examples/cpp/main.cpp`](examples/cpp/main.cpp) | `g++ main.cpp -o demo && ./demo` |
95
+
96
+ Run the cross-language examples from their own folders after installing the CLI.
97
+
98
+ ## Architecture
99
+
100
+ ```text
101
+ Existing app -> skillbridge.json / SKILL.md
102
+ |
103
+ Agent / SDK -> discovery CLI -> JSON capabilities
104
+ |
105
+ explicit approval
106
+ |
107
+ argv execution
108
+
109
+ Python app -> Bridge.expose() -> local HTTP /manifest + /call
110
+ ```
111
+
112
+ **Design direction:** add pluggable adapters for MCP, OpenAPI, HTTP and native ABI while retaining one capability schema. Discovery is read-only; execution is separately authorized. No LLM is required to test the bridge.
113
+
114
+ ## Security boundaries
115
+
116
+ - Local discovery never runs a command.
117
+ - Commands require `--allow-execute` each invocation.
118
+ - Command inputs are type-checked; arguments are passed without a shell.
119
+ - The optional HTTP server binds to loopback and requires a bearer token.
120
+ - **No process isolation or sandbox exists in this MVP.** A malicious approved manifest can execute arbitrary programs. Inspect manifests before approving.
121
+ - Avoid exposing arbitrary SQL or filesystem operations. Design narrow, least-privilege skills.
122
+
123
+ ## Test
124
+
125
+ ```bash
126
+ python -m unittest discover -s tests -v
127
+ python -m build # optional: first pip install build
128
+ ```
129
+
130
+ ## How to publish `pip install skillbridge`
131
+
132
+ `pip install skillbridge` only works after you publish a package with that exact name to [PyPI](https://pypi.org/). **Check name availability first**; this repository does not claim the name is available.
133
+
134
+ 1. Create a PyPI account and configure trusted publishing (recommended) or an API token.
135
+ 2. Update `name`, `version`, authors, and project metadata in `pyproject.toml`.
136
+ 3. Run `python -m pip install build twine` then `python -m build`.
137
+ 4. Validate with `python -m twine check dist/*` and publish with `python -m twine upload dist/*` (or use trusted publishing in CI).
138
+ 5. After publication: `python -m pip install skillbridge`.
139
+
140
+ For a GitHub install **before** PyPI publication, replace `OWNER/REPO` with your actual GitHub path:
141
+
142
+ ```bash
143
+ python -m pip install 'git+https://github.com/OWNER/REPO.git'
144
+ ```
145
+
146
+ ## Roadmap
147
+
148
+ - [x] Local JSON/Markdown discovery
149
+ - [x] CLI read-only inspection and opt-in execution
150
+ - [x] Python HTTP bridge with token auth
151
+ - [x] Cross-language CLI examples
152
+ - [ ] MCP/OpenAPI discovery adapters
153
+ - [ ] Signed manifests and explicit permission scopes
154
+ - [ ] Sandboxed execution via isolated processes / WASM
155
+ - [ ] Native Rust core with C ABI (.dll/.so/.dylib)
156
+ - [ ] npm/npx convenience CLI
157
+ - [ ] Auto-discovery and Forge integration
158
+
159
+ ## Contributing
160
+
161
+ Issues and pull requests welcome. Please include a reproducible example and tests for behavior changes. See [LICENSE](LICENSE) (MIT).
@@ -0,0 +1,19 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "skillbridge-ai"
7
+ version = "0.1.0"
8
+ description = "Discover and safely invoke application capabilities through portable manifests"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = {text = "MIT"}
12
+ authors = [{name = "SkillBridge contributors"}]
13
+ keywords = ["agents", "skills", "discovery", "cli", "interop"]
14
+
15
+ [project.scripts]
16
+ skillbridge = "skillbridge.cli:main"
17
+
18
+ [tool.setuptools.packages.find]
19
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,4 @@
1
+ """SkillBridge public API."""
2
+ from .core import discover, load_manifest, invoke, SkillBridgeError
3
+ from .server import Bridge
4
+ __all__ = ["discover", "load_manifest", "invoke", "SkillBridgeError", "Bridge"]
@@ -0,0 +1,33 @@
1
+ """CLI for discovery, inspection, and explicitly authorized execution."""
2
+ import argparse
3
+ import json
4
+ import sys
5
+ from .core import SkillBridgeError, discover, invoke
6
+
7
+ def main():
8
+ parser = argparse.ArgumentParser(prog="skillbridge", description="Discover app skills from a local manifest or Markdown")
9
+ sub = parser.add_subparsers(dest="action", required=True)
10
+ for command in ("discover", "inspect"):
11
+ sub.add_parser(command).add_argument("location")
12
+ call = sub.add_parser("call")
13
+ call.add_argument("location")
14
+ call.add_argument("skill")
15
+ call.add_argument("--args", default="{}", help="JSON object")
16
+ call.add_argument("--allow-execute", action="store_true", help="Explicitly authorize command execution")
17
+ args = parser.parse_args()
18
+ try:
19
+ manifest = discover(args.location)
20
+ if args.action == "discover":
21
+ result = {"app": manifest["app"], "skills": [{k: v for k, v in s.items() if k in ("name", "description", "type", "inputs")} for s in manifest["skills"]]}
22
+ elif args.action == "inspect":
23
+ result = {k: v for k, v in manifest.items() if not k.startswith("_")}
24
+ else:
25
+ result = invoke(manifest, args.skill, json.loads(args.args), allow_execute=args.allow_execute)
26
+ print(json.dumps(result, ensure_ascii=False, indent=2))
27
+ except (SkillBridgeError, ValueError) as exc:
28
+ print(json.dumps({"error": str(exc)}), file=sys.stderr)
29
+ return 1
30
+ return 0
31
+
32
+ if __name__ == "__main__":
33
+ raise SystemExit(main())
@@ -0,0 +1,94 @@
1
+ """Manifest-based discovery and intentionally restricted execution."""
2
+ from __future__ import annotations
3
+ import json
4
+ import re
5
+ import subprocess
6
+ from pathlib import Path
7
+ from typing import Any
8
+
9
+ class SkillBridgeError(Exception):
10
+ pass
11
+
12
+ NAME = re.compile(r"^[a-zA-Z][a-zA-Z0-9_.-]{0,79}$")
13
+
14
+ def load_manifest(path: str | Path) -> dict[str, Any]:
15
+ p = Path(path).expanduser().resolve()
16
+ if p.is_dir():
17
+ p = p / "skillbridge.json"
18
+ try:
19
+ data = json.loads(p.read_text(encoding="utf-8"))
20
+ except (OSError, ValueError) as exc:
21
+ raise SkillBridgeError(f"Cannot read manifest {p}: {exc}") from exc
22
+ if not isinstance(data, dict) or not isinstance(data.get("app"), str) or not isinstance(data.get("skills"), list):
23
+ raise SkillBridgeError("Manifest requires 'app' string and 'skills' array")
24
+ names = set()
25
+ for skill in data["skills"]:
26
+ if not isinstance(skill, dict) or not isinstance(skill.get("name"), str) or not NAME.fullmatch(skill["name"]):
27
+ raise SkillBridgeError("Each skill needs a valid name")
28
+ if skill["name"] in names:
29
+ raise SkillBridgeError("Duplicate skill name")
30
+ names.add(skill["name"])
31
+ if not isinstance(skill.get("description"), str):
32
+ raise SkillBridgeError("Each skill needs a description")
33
+ if skill.get("type") not in ("command", "documentation"):
34
+ raise SkillBridgeError("Supported types: command, documentation")
35
+ if skill["type"] == "command" and (not isinstance(skill.get("argv"), list) or not skill["argv"] or not all(isinstance(a, str) for a in skill["argv"])):
36
+ raise SkillBridgeError("Command skills require argv string array")
37
+ data["_manifest_path"] = str(p)
38
+ return data
39
+
40
+ def discover(location: str | Path) -> dict[str, Any]:
41
+ """Discover local manifests or Markdown docs; never execute during discovery."""
42
+ p = Path(location).expanduser().resolve()
43
+ if p.is_file() and p.suffix.lower() == ".md":
44
+ return {"app": p.parent.name, "skills": [{"name": "documentation", "description": p.read_text(encoding="utf-8"), "type": "documentation"}], "_manifest_path": str(p)}
45
+ if p.is_dir() and not (p / "skillbridge.json").exists():
46
+ for filename in ("SKILL.md", "AGENT.md", "README.md"):
47
+ if (p / filename).is_file():
48
+ return discover(p / filename)
49
+ raise SkillBridgeError(f"No skillbridge.json or skill documentation in {p}")
50
+ return load_manifest(p)
51
+
52
+ def invoke(manifest: dict[str, Any], name: str, arguments: dict[str, Any], *, allow_execute: bool = False, timeout: int = 10) -> Any:
53
+ """Execute only explicitly approved command skills; no shell interpolation."""
54
+ skill = next((s for s in manifest["skills"] if s["name"] == name), None)
55
+ if skill is None:
56
+ raise SkillBridgeError(f"Unknown skill: {name}")
57
+ if skill["type"] != "command":
58
+ raise SkillBridgeError("Documentation skills cannot be executed")
59
+ if not allow_execute:
60
+ raise SkillBridgeError("Execution denied by default; pass --allow-execute to approve this invocation")
61
+ if not isinstance(arguments, dict):
62
+ raise SkillBridgeError("Arguments must be a JSON object")
63
+ schema = skill.get("inputs", {})
64
+ if not isinstance(schema, dict):
65
+ raise SkillBridgeError("inputs must be an object")
66
+ if set(arguments) - set(schema):
67
+ raise SkillBridgeError("Unexpected input arguments")
68
+ for key, kind in schema.items():
69
+ if key not in arguments:
70
+ raise SkillBridgeError(f"Missing argument: {key}")
71
+ if kind not in ("string", "integer", "boolean"):
72
+ raise SkillBridgeError(f"Unsupported input type: {kind}")
73
+ value = arguments[key]
74
+ if not ((kind == "string" and isinstance(value, str)) or (kind == "integer" and type(value) is int) or (kind == "boolean" and type(value) is bool)):
75
+ raise SkillBridgeError(f"Invalid type for {key}: expected {kind}")
76
+ argv = []
77
+ for part in skill["argv"]:
78
+ matches = re.findall(r"\{([a-zA-Z][a-zA-Z0-9_]*)\}", part)
79
+ if "{" in part or "}" in part:
80
+ if len(matches) != 1 or part != "{" + matches[0] + "}":
81
+ raise SkillBridgeError("Arguments must occupy an entire argv element")
82
+ if matches:
83
+ key = matches[0]
84
+ if key not in arguments:
85
+ raise SkillBridgeError(f"Unknown placeholder: {key}")
86
+ argv.append(str(arguments[key]).lower() if type(arguments[key]) is bool else str(arguments[key]))
87
+ else:
88
+ argv.append(part)
89
+ base = Path(manifest["_manifest_path"]).parent
90
+ try:
91
+ result = subprocess.run(argv, cwd=base, capture_output=True, text=True, timeout=min(max(timeout, 1), 60), shell=False, check=False)
92
+ except (OSError, subprocess.TimeoutExpired) as exc:
93
+ raise SkillBridgeError(f"Execution failed: {exc}") from exc
94
+ return {"exit_code": result.returncode, "stdout": result.stdout[:65536], "stderr": result.stderr[:65536]}
@@ -0,0 +1,60 @@
1
+ """Optional Python in-process exposure for local agents (token protected)."""
2
+ import hmac
3
+ import json
4
+ import secrets
5
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
6
+
7
+ class Bridge:
8
+ def __init__(self, app: str, token: str | None = None):
9
+ self.app = app
10
+ self.token = token or secrets.token_urlsafe(32)
11
+ self._skills = {}
12
+
13
+ def expose(self, name: str, description: str, fn, inputs: dict[str, str]):
14
+ if not callable(fn) or not name or not description:
15
+ raise ValueError("A named callable and description are required")
16
+ if not all(t in ("string", "integer", "boolean") for t in inputs.values()):
17
+ raise ValueError("Unsupported input type")
18
+ self._skills[name] = (description, fn, inputs)
19
+
20
+ def serve(self, host="127.0.0.1", port=8765):
21
+ if host not in ("127.0.0.1", "localhost", "::1"):
22
+ raise ValueError("This MVP only binds to loopback")
23
+ bridge = self
24
+ class Handler(BaseHTTPRequestHandler):
25
+ def reply(self, code, payload):
26
+ data = json.dumps(payload).encode()
27
+ self.send_response(code)
28
+ self.send_header("Content-Type", "application/json")
29
+ self.send_header("Content-Length", str(len(data)))
30
+ self.end_headers()
31
+ self.wfile.write(data)
32
+ def authorized(self):
33
+ return hmac.compare_digest(self.headers.get("Authorization", ""), "Bearer " + bridge.token)
34
+ def do_GET(self):
35
+ if not self.authorized(): return self.reply(401, {"error": "Unauthorized"})
36
+ if self.path != "/manifest": return self.reply(404, {"error": "Not found"})
37
+ self.reply(200, {"app": bridge.app, "skills": [{"name": n, "description": d, "inputs": i} for n, (d, _, i) in bridge._skills.items()]})
38
+ def do_POST(self):
39
+ if not self.authorized(): return self.reply(401, {"error": "Unauthorized"})
40
+ if self.path != "/call": return self.reply(404, {"error": "Not found"})
41
+ try:
42
+ length = int(self.headers.get("Content-Length", "0"))
43
+ if not 0 < length <= 65536: return self.reply(413, {"error": "Invalid request size"})
44
+ body = json.loads(self.rfile.read(length))
45
+ name, args = body["skill"], body["args"]
46
+ if name not in bridge._skills or not isinstance(args, dict): return self.reply(400, {"error": "Invalid skill or arguments"})
47
+ _, fn, schema = bridge._skills[name]
48
+ if set(args) != set(schema): return self.reply(400, {"error": "Argument mismatch"})
49
+ for k, t in schema.items():
50
+ v = args[k]
51
+ if not ((t == "string" and isinstance(v, str)) or (t == "integer" and type(v) is int) or (t == "boolean" and type(v) is bool)):
52
+ return self.reply(400, {"error": "Invalid argument type"})
53
+ self.reply(200, {"result": fn(**args)})
54
+ except (ValueError, KeyError, TypeError) as exc:
55
+ self.reply(400, {"error": str(exc)})
56
+ except Exception:
57
+ self.reply(500, {"error": "Skill execution failed"})
58
+ server = ThreadingHTTPServer((host, port), Handler)
59
+ print(f"SkillBridge listening at http://{host}:{port}; token: {self.token}")
60
+ server.serve_forever()
@@ -0,0 +1,173 @@
1
+ Metadata-Version: 2.4
2
+ Name: skillbridge-ai
3
+ Version: 0.1.0
4
+ Summary: Discover and safely invoke application capabilities through portable manifests
5
+ Author: SkillBridge contributors
6
+ License: MIT
7
+ Keywords: agents,skills,discovery,cli,interop
8
+ Requires-Python: >=3.10
9
+ Description-Content-Type: text/markdown
10
+ License-File: LICENSE
11
+ Dynamic: license-file
12
+
13
+ ![SkillBridge banner](assets/banner.svg)
14
+
15
+ # SkillBridge
16
+
17
+ **Discover application capabilities without requiring every application to implement an agent protocol.** A small, language-neutral, local-first proof of concept.
18
+
19
+ > **Status: v0.1.0 MVP.** The working features are local Markdown/JSON discovery, permission-gated command execution, and an optional token-protected Python HTTP bridge. **Not yet implemented:** automatic scanning of installed apps, MCP/OpenAPI adapters, native Rust core/DLL, npx installer, sandboxed execution, or automatic LLM integration. This is not an MCP implementation.
20
+
21
+ ## Install in seconds
22
+
23
+ Requires Python 3.10+ and Git. **The package is not published to PyPI yet.** After downloading or cloning this repository:
24
+
25
+ ```bash
26
+ python -m pip install -e .
27
+ skillbridge discover examples/manifests
28
+ skillbridge inspect examples/manifests
29
+ ```
30
+
31
+ For a clean virtual environment:
32
+
33
+ ```bash
34
+ python -m venv .venv
35
+ # Windows PowerShell:
36
+ .venv\Scripts\Activate.ps1
37
+ # Linux/macOS:
38
+ # source .venv/bin/activate
39
+ python -m pip install -e .
40
+ ```
41
+
42
+ ## Zero-server discovery
43
+
44
+ Create `skillbridge.json` in any application folder:
45
+
46
+ ```json
47
+ {
48
+ "app": "TestApp",
49
+ "skills": [
50
+ {
51
+ "name": "greet",
52
+ "description": "Say hello to a user",
53
+ "type": "command",
54
+ "inputs": {"name": "string"},
55
+ "argv": ["python", "hello.py", "{name}"]
56
+ }
57
+ ]
58
+ }
59
+ ```
60
+
61
+ A compatible agent or tool runner can discover it with:
62
+
63
+ ```bash
64
+ skillbridge discover ./testapp
65
+ ```
66
+
67
+ Alternatively, create `SKILL.md` or `AGENT.md`. SkillBridge will read it as **documentation only**, not silently execute commands mentioned in Markdown.
68
+
69
+ ### Call a command (requires explicit approval)
70
+
71
+ ```bash
72
+ skillbridge call examples/manifests greet --args '{"name":"Forge"}' --allow-execute
73
+ ```
74
+
75
+ On PowerShell, quoting JSON varies by shell. The CLI deliberately refuses execution without `--allow-execute`. Commands use argv arrays and `shell=False`, but this **does not sandbox** programs. Only run manifests you trust.
76
+
77
+ ## Python: expose real functions
78
+
79
+ ```python
80
+ from skillbridge import Bridge
81
+
82
+ bridge = Bridge("TestApp")
83
+ bridge.expose("greet", "Say hello", lambda name: f"Hi {name}", {"name": "string"})
84
+ bridge.serve() # 127.0.0.1:8765, prints generated bearer token
85
+ ```
86
+
87
+ Run `python examples/python/app.py`. A client with the token can then request:
88
+
89
+ ```bash
90
+ curl -H "Authorization: Bearer YOUR_TOKEN" http://127.0.0.1:8765/manifest
91
+ curl -X POST http://127.0.0.1:8765/call -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"skill":"greet","args":{"name":"Forge"}}'
92
+ ```
93
+
94
+ **Keep the token private.** The HTTP bridge is loopback-only, not production-hardened, and functions run with your application's permissions. Do not expose it to untrusted users.
95
+
96
+ ## Examples in five languages
97
+
98
+ The same `skillbridge discover` JSON output can be consumed by any language. The examples demonstrate **CLI interoperability**, not native bindings or direct function exposure for every language.
99
+
100
+ | Language | Example | Run from directory |
101
+ | --- | --- | --- |
102
+ | Python | [`examples/python/app.py`](examples/python/app.py) | `python app.py` |
103
+ | TypeScript / Node.js | [`examples/typescript/demo.mjs`](examples/typescript/demo.mjs) | `node demo.mjs` |
104
+ | Go | [`examples/go/main.go`](examples/go/main.go) | `go run main.go` |
105
+ | Rust | [`examples/rust/main.rs`](examples/rust/main.rs) | `rustc main.rs -o demo && ./demo` |
106
+ | C++ | [`examples/cpp/main.cpp`](examples/cpp/main.cpp) | `g++ main.cpp -o demo && ./demo` |
107
+
108
+ Run the cross-language examples from their own folders after installing the CLI.
109
+
110
+ ## Architecture
111
+
112
+ ```text
113
+ Existing app -> skillbridge.json / SKILL.md
114
+ |
115
+ Agent / SDK -> discovery CLI -> JSON capabilities
116
+ |
117
+ explicit approval
118
+ |
119
+ argv execution
120
+
121
+ Python app -> Bridge.expose() -> local HTTP /manifest + /call
122
+ ```
123
+
124
+ **Design direction:** add pluggable adapters for MCP, OpenAPI, HTTP and native ABI while retaining one capability schema. Discovery is read-only; execution is separately authorized. No LLM is required to test the bridge.
125
+
126
+ ## Security boundaries
127
+
128
+ - Local discovery never runs a command.
129
+ - Commands require `--allow-execute` each invocation.
130
+ - Command inputs are type-checked; arguments are passed without a shell.
131
+ - The optional HTTP server binds to loopback and requires a bearer token.
132
+ - **No process isolation or sandbox exists in this MVP.** A malicious approved manifest can execute arbitrary programs. Inspect manifests before approving.
133
+ - Avoid exposing arbitrary SQL or filesystem operations. Design narrow, least-privilege skills.
134
+
135
+ ## Test
136
+
137
+ ```bash
138
+ python -m unittest discover -s tests -v
139
+ python -m build # optional: first pip install build
140
+ ```
141
+
142
+ ## How to publish `pip install skillbridge`
143
+
144
+ `pip install skillbridge` only works after you publish a package with that exact name to [PyPI](https://pypi.org/). **Check name availability first**; this repository does not claim the name is available.
145
+
146
+ 1. Create a PyPI account and configure trusted publishing (recommended) or an API token.
147
+ 2. Update `name`, `version`, authors, and project metadata in `pyproject.toml`.
148
+ 3. Run `python -m pip install build twine` then `python -m build`.
149
+ 4. Validate with `python -m twine check dist/*` and publish with `python -m twine upload dist/*` (or use trusted publishing in CI).
150
+ 5. After publication: `python -m pip install skillbridge`.
151
+
152
+ For a GitHub install **before** PyPI publication, replace `OWNER/REPO` with your actual GitHub path:
153
+
154
+ ```bash
155
+ python -m pip install 'git+https://github.com/OWNER/REPO.git'
156
+ ```
157
+
158
+ ## Roadmap
159
+
160
+ - [x] Local JSON/Markdown discovery
161
+ - [x] CLI read-only inspection and opt-in execution
162
+ - [x] Python HTTP bridge with token auth
163
+ - [x] Cross-language CLI examples
164
+ - [ ] MCP/OpenAPI discovery adapters
165
+ - [ ] Signed manifests and explicit permission scopes
166
+ - [ ] Sandboxed execution via isolated processes / WASM
167
+ - [ ] Native Rust core with C ABI (.dll/.so/.dylib)
168
+ - [ ] npm/npx convenience CLI
169
+ - [ ] Auto-discovery and Forge integration
170
+
171
+ ## Contributing
172
+
173
+ Issues and pull requests welcome. Please include a reproducible example and tests for behavior changes. See [LICENSE](LICENSE) (MIT).
@@ -0,0 +1,13 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ src/skillbridge/__init__.py
5
+ src/skillbridge/cli.py
6
+ src/skillbridge/core.py
7
+ src/skillbridge/server.py
8
+ src/skillbridge_ai.egg-info/PKG-INFO
9
+ src/skillbridge_ai.egg-info/SOURCES.txt
10
+ src/skillbridge_ai.egg-info/dependency_links.txt
11
+ src/skillbridge_ai.egg-info/entry_points.txt
12
+ src/skillbridge_ai.egg-info/top_level.txt
13
+ tests/test_core.py
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ skillbridge = skillbridge.cli:main
@@ -0,0 +1,23 @@
1
+ import json
2
+ import tempfile
3
+ import unittest
4
+ from pathlib import Path
5
+ from skillbridge import discover, invoke, SkillBridgeError
6
+
7
+ class CoreTests(unittest.TestCase):
8
+ def test_discovery_and_execution_gate(self):
9
+ with tempfile.TemporaryDirectory() as d:
10
+ p = Path(d)
11
+ (p / "skillbridge.json").write_text(json.dumps({"app": "Test", "skills": [{"name": "echo", "description": "Echo", "type": "command", "inputs": {"msg": "string"}, "argv": ["python", "-c", "import sys; print(sys.argv[1])", "{msg}"]}]}))
12
+ m = discover(p)
13
+ self.assertEqual(m["app"], "Test")
14
+ with self.assertRaises(SkillBridgeError): invoke(m, "echo", {"msg": "hi"})
15
+ self.assertIn("hi", invoke(m, "echo", {"msg": "hi"}, allow_execute=True)["stdout"])
16
+ with self.assertRaises(SkillBridgeError): invoke(m, "echo", {"msg": "hi", "bad": "x"}, allow_execute=True)
17
+ def test_markdown_discovery(self):
18
+ with tempfile.TemporaryDirectory() as d:
19
+ p = Path(d) / "SKILL.md"
20
+ p.write_text("# A skill")
21
+ self.assertEqual(discover(d)["skills"][0]["type"], "documentation")
22
+
23
+ if __name__ == "__main__": unittest.main()