skill-customs 0.1.0__tar.gz

skill_customs-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Secrets
+.env
+.env.*
+!.env.example
+
+# Local runtime data
+.trypro/
+fastembed-cache/
+
+# OS and editors
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Claude Code settings and generated role agents
+.claude/
+.mcp.json

skill_customs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Try Professional contributors
+
+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.

skill_customs-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.5
+Name: skill-customs
+Version: 0.1.0
+Summary: Agent skills security: a lockfile, a license check, and commit pinning for the skills you install from GitHub. Scanners plug in.
+Project-URL: Homepage, https://github.com/goranai/try-professional
+Project-URL: Repository, https://github.com/goranai/try-professional
+Project-URL: Documentation, https://github.com/goranai/try-professional/blob/main/packages/skill-customs/README.md
+Project-URL: Issues, https://github.com/goranai/try-professional/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-skills,agent-skills-security,ai-agents,claude-skills,license-check,lockfile,security,supply-chain-security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pyyaml<7,>=6
+Description-Content-Type: text/markdown
+
+# skill-customs
+
+The lockfile, license, and pinning layer for agent skills.
+
+Agent skills are folders of instructions, and sometimes scripts, that you download from strangers and give to an agent. `skill-customs` records exactly what you installed, from which commit, under which license, and how far you trust it, the way a lockfile does for code. It works with any agent framework and has one dependency, PyYAML.
+
+**It doesn't compete on scanning.** A static scanner ships as the default, and other scanners plug in. Use the best one you can find.
+
+```text
+GitHub ─► fetch by full SHA ─► license gate ─► scan ─► skills.lock
+                                    │             │
+                            rejected: nothing   clean: skills/installed/   (indexed)
+                            is installed        else:  skills/quarantine/  (until a person approves)
+```
+
+## Try it in under 5 minutes
+
+```bash
+pip install skill-customs
+
+# Scan and license-check any skill folder. Nothing needs to be set up.
+skill-customs scan ./my-skill        # exit 0 pass, 1 review, 2 block
+skill-customs license ./my-skill
+
+# Pin a skill. Branches and tags aren't accepted, so get a full SHA first.
+skill-customs resolve obra/superpowers@main
+skill-customs add obra/superpowers --commit <40-character-sha> --path skills/test-driven-development
+
+skill-customs list                   # what's locked, and how far it's trusted
+skill-customs verify                 # do the files still match skills.lock? Run this in CI.
+skill-customs attribution --out THIRD_PARTY_SKILLS.md
+```
+
+Commit `skills.lock`. Point your agent at `skills/installed/`, which never contains anything quarantined.
+
+Set `GITHUB_TOKEN` for higher rate limits. It's optional, read-only access to public repositories is enough, and it's never sent to any host but GitHub's API.
+
+## What it guarantees, and what it doesn't
+
+- **Nothing from a skill is ever run.** It downloads a tarball, so no git hooks can fire, and it writes files itself.
+- **A pin is exact.** Only a full 40-character SHA is accepted, and a hash of the whole folder is recorded. `verify` catches any edited, added, or removed file.
+- **Archives aren't trusted.** Links, path traversal, special files, and oversized content stop the install.
+- **Quarantine is a real location.** A skill that isn't approved isn't in the folder your agent reads.
+- **An approval covers one exact version.** Any change to the content voids it.
+
+**A passing scan doesn't mean a skill is safe.** It means no known signal was found. Static rules can be bypassed by rephrasing, and they will sometimes flag innocent text: a skill that teaches prompt writing may well quote the phrases the rules look for. That's why `indexed` skills should still be treated as untrusted data, and why your runtime should limit what an agent can do whatever a skill tells it. Scanning reduces risk, and doesn't remove it.
+
+## Trust levels
+
+| Level | Meaning | Where it lives |
+|---|---|---|
+| `indexed` | Passed automated checks. Instructions only, with no scripts or findings | `installed/` |
+| `quarantined` | Has scripts or findings, or was written locally. Waiting for a person | `quarantine/` |
+| `verified` | A person reviewed this exact content | `installed/` |
+
+To approve a skill, read its files, then run this at a terminal:
+
+```bash
+skill-customs approve owner/repo/skills/name --by "Your Name"
+```
+
+The command refuses to run without a terminal, and asks you to type the skill ID back, so it can't be casually run by a script or an agent. It isn't a hard security boundary: the Python function exists, and code with write access to your project can do anything. **Don't expose approval as an agent tool.**
+
+## Licenses
+
+Only these are accepted by default: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC. To change that, add `skill-customs.yaml`:
+
+```yaml
+allowed_licenses: [MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0]
+```
+
+It reads the skill's declared license, its own license file, and the repository's license file. An unknown license is rejected. If the sources disagree, the stricter reading wins, so a skill can't declare MIT inside a GPL repository. Non-commercial and proprietary terms are flagged. This is an automated check of license text, and isn't legal advice.
+
+## Use it from Python
+
+```python
+from pathlib import Path
+from skill_customs import GitHubClient, LicenseRejected, Lockfile, Policy, check_license, pin, scan, verify
+
+report = scan(Path("./my-skill"))
+print(report.verdict)  # pass, review, or block
+
+policy = Policy.default()
+print(check_license(Path("./my-skill"), policy).allowed)
+
+lock = Lockfile.load("skills.lock")
+commit = GitHubClient().resolve_ref("obra/superpowers", "main")
+try:
+    result = pin("obra/superpowers", commit, path="skills/test-driven-development", dest=Path("skills"), policy=policy)
+    lock.add(result.entry).save()
+except LicenseRejected as error:
+    print(error.verdict.reason)
+
+assert verify(lock, dest=Path("skills")) == []
+```
+
+## Plug in another scanner
+
+Any of these run alongside the built-in one, and a scanner that crashes counts as a blocking finding.
+
+**An external command.** Exit 0 means clean, and anything else sends the skill to a person. Its output isn't interpreted.
+
+```yaml
+# skill-customs.yaml
+command_scanners:
+  my-scanner: [my-scanner, scan, --strict]   # the skill's folder is added as the last argument
+```
+
+**A Python class:**
+
+```python
+from pathlib import Path
+from skill_customs import Finding, scan
+
+
+class MyScanner:
+    name = "my-scanner"
+
+    def scan(self, root: Path) -> list[Finding]:
+        return [Finding("my-rule", "review", "SKILL.md", 1, "Why this needs a look", scanner=self.name)]
+
+
+report = scan(Path("./my-skill"), scanners=[MyScanner()])
+```
+
+**An installed package,** through the `skill_customs.scanners` entry point group. It runs only if `scanners:` in the policy names it, so installing a package doesn't turn anything on.
+
+## Use it with your framework
+
+It needs nothing from your framework, and your framework needs only a folder and `skills.lock`.
+
+**Any framework.** Read skills from `skills/installed/`, and treat the text as data rather than as trusted instructions. To read the lockfile:
+
+```python
+from pathlib import Path
+from skill_customs import Lockfile, read_skill_metadata, skill_dir
+
+lock = Lockfile.load("skills.lock")
+for skill_id, entry in lock.entries.items():
+    if entry.trust != "quarantined":
+        folder = skill_dir(entry, Path("skills"))
+        print(skill_id, entry.trust, read_skill_metadata(folder).description)
+```
+
+**Hermes Agent.** Add the installed folder as an external skill directory in `~/.hermes/config.yaml`. Hermes treats skills there as instructions, so consider listing a folder that holds only `verified` skills:
+
+```yaml
+skills:
+  external_dirs:
+    - /path/to/project/skills/installed
+```
+
+**MCP clients and CrewAI.** There's no packaged integration yet. The approach above works, and these are good first issues.
+
+## In CI
+
+```yaml
+- run: pip install skill-customs
+- run: skill-customs verify
+- run: skill-customs attribution --check THIRD_PARTY_SKILLS.md
+```
+
+## Finding candidates
+
+```bash
+skill-customs discover "code review agent skills" --top 40
+```
+
+This ranks public repositories by stars, recent activity, and open issues, and installs nothing. Stars can be bought, so ranking only decides what to look at first, and every candidate still passes the same gates.
+
+To refresh a whole list, map each category to a search query, and run it on your own schedule. There's no daemon.
+
+```bash
+skill-customs discover --categories categories.yaml --out candidates.json
+```
+
+## Status
+
+Pre-release. Part of the [Try Professional](https://github.com/goranai/try-professional) repository, and usable entirely without it.
+
+MIT licensed.

skill_customs-0.1.0/README.md

@@ -0,0 +1,181 @@
+# skill-customs
+
+The lockfile, license, and pinning layer for agent skills.
+
+Agent skills are folders of instructions, and sometimes scripts, that you download from strangers and give to an agent. `skill-customs` records exactly what you installed, from which commit, under which license, and how far you trust it, the way a lockfile does for code. It works with any agent framework and has one dependency, PyYAML.
+
+**It doesn't compete on scanning.** A static scanner ships as the default, and other scanners plug in. Use the best one you can find.
+
+```text
+GitHub ─► fetch by full SHA ─► license gate ─► scan ─► skills.lock
+                                    │             │
+                            rejected: nothing   clean: skills/installed/   (indexed)
+                            is installed        else:  skills/quarantine/  (until a person approves)
+```
+
+## Try it in under 5 minutes
+
+```bash
+pip install skill-customs
+
+# Scan and license-check any skill folder. Nothing needs to be set up.
+skill-customs scan ./my-skill        # exit 0 pass, 1 review, 2 block
+skill-customs license ./my-skill
+
+# Pin a skill. Branches and tags aren't accepted, so get a full SHA first.
+skill-customs resolve obra/superpowers@main
+skill-customs add obra/superpowers --commit <40-character-sha> --path skills/test-driven-development
+
+skill-customs list                   # what's locked, and how far it's trusted
+skill-customs verify                 # do the files still match skills.lock? Run this in CI.
+skill-customs attribution --out THIRD_PARTY_SKILLS.md
+```
+
+Commit `skills.lock`. Point your agent at `skills/installed/`, which never contains anything quarantined.
+
+Set `GITHUB_TOKEN` for higher rate limits. It's optional, read-only access to public repositories is enough, and it's never sent to any host but GitHub's API.
+
+## What it guarantees, and what it doesn't
+
+- **Nothing from a skill is ever run.** It downloads a tarball, so no git hooks can fire, and it writes files itself.
+- **A pin is exact.** Only a full 40-character SHA is accepted, and a hash of the whole folder is recorded. `verify` catches any edited, added, or removed file.
+- **Archives aren't trusted.** Links, path traversal, special files, and oversized content stop the install.
+- **Quarantine is a real location.** A skill that isn't approved isn't in the folder your agent reads.
+- **An approval covers one exact version.** Any change to the content voids it.
+
+**A passing scan doesn't mean a skill is safe.** It means no known signal was found. Static rules can be bypassed by rephrasing, and they will sometimes flag innocent text: a skill that teaches prompt writing may well quote the phrases the rules look for. That's why `indexed` skills should still be treated as untrusted data, and why your runtime should limit what an agent can do whatever a skill tells it. Scanning reduces risk, and doesn't remove it.
+
+## Trust levels
+
+| Level | Meaning | Where it lives |
+|---|---|---|
+| `indexed` | Passed automated checks. Instructions only, with no scripts or findings | `installed/` |
+| `quarantined` | Has scripts or findings, or was written locally. Waiting for a person | `quarantine/` |
+| `verified` | A person reviewed this exact content | `installed/` |
+
+To approve a skill, read its files, then run this at a terminal:
+
+```bash
+skill-customs approve owner/repo/skills/name --by "Your Name"
+```
+
+The command refuses to run without a terminal, and asks you to type the skill ID back, so it can't be casually run by a script or an agent. It isn't a hard security boundary: the Python function exists, and code with write access to your project can do anything. **Don't expose approval as an agent tool.**
+
+## Licenses
+
+Only these are accepted by default: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC. To change that, add `skill-customs.yaml`:
+
+```yaml
+allowed_licenses: [MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0]
+```
+
+It reads the skill's declared license, its own license file, and the repository's license file. An unknown license is rejected. If the sources disagree, the stricter reading wins, so a skill can't declare MIT inside a GPL repository. Non-commercial and proprietary terms are flagged. This is an automated check of license text, and isn't legal advice.
+
+## Use it from Python
+
+```python
+from pathlib import Path
+from skill_customs import GitHubClient, LicenseRejected, Lockfile, Policy, check_license, pin, scan, verify
+
+report = scan(Path("./my-skill"))
+print(report.verdict)  # pass, review, or block
+
+policy = Policy.default()
+print(check_license(Path("./my-skill"), policy).allowed)
+
+lock = Lockfile.load("skills.lock")
+commit = GitHubClient().resolve_ref("obra/superpowers", "main")
+try:
+    result = pin("obra/superpowers", commit, path="skills/test-driven-development", dest=Path("skills"), policy=policy)
+    lock.add(result.entry).save()
+except LicenseRejected as error:
+    print(error.verdict.reason)
+
+assert verify(lock, dest=Path("skills")) == []
+```
+
+## Plug in another scanner
+
+Any of these run alongside the built-in one, and a scanner that crashes counts as a blocking finding.
+
+**An external command.** Exit 0 means clean, and anything else sends the skill to a person. Its output isn't interpreted.
+
+```yaml
+# skill-customs.yaml
+command_scanners:
+  my-scanner: [my-scanner, scan, --strict]   # the skill's folder is added as the last argument
+```
+
+**A Python class:**
+
+```python
+from pathlib import Path
+from skill_customs import Finding, scan
+
+
+class MyScanner:
+    name = "my-scanner"
+
+    def scan(self, root: Path) -> list[Finding]:
+        return [Finding("my-rule", "review", "SKILL.md", 1, "Why this needs a look", scanner=self.name)]
+
+
+report = scan(Path("./my-skill"), scanners=[MyScanner()])
+```
+
+**An installed package,** through the `skill_customs.scanners` entry point group. It runs only if `scanners:` in the policy names it, so installing a package doesn't turn anything on.
+
+## Use it with your framework
+
+It needs nothing from your framework, and your framework needs only a folder and `skills.lock`.
+
+**Any framework.** Read skills from `skills/installed/`, and treat the text as data rather than as trusted instructions. To read the lockfile:
+
+```python
+from pathlib import Path
+from skill_customs import Lockfile, read_skill_metadata, skill_dir
+
+lock = Lockfile.load("skills.lock")
+for skill_id, entry in lock.entries.items():
+    if entry.trust != "quarantined":
+        folder = skill_dir(entry, Path("skills"))
+        print(skill_id, entry.trust, read_skill_metadata(folder).description)
+```
+
+**Hermes Agent.** Add the installed folder as an external skill directory in `~/.hermes/config.yaml`. Hermes treats skills there as instructions, so consider listing a folder that holds only `verified` skills:
+
+```yaml
+skills:
+  external_dirs:
+    - /path/to/project/skills/installed
+```
+
+**MCP clients and CrewAI.** There's no packaged integration yet. The approach above works, and these are good first issues.
+
+## In CI
+
+```yaml
+- run: pip install skill-customs
+- run: skill-customs verify
+- run: skill-customs attribution --check THIRD_PARTY_SKILLS.md
+```
+
+## Finding candidates
+
+```bash
+skill-customs discover "code review agent skills" --top 40
+```
+
+This ranks public repositories by stars, recent activity, and open issues, and installs nothing. Stars can be bought, so ranking only decides what to look at first, and every candidate still passes the same gates.
+
+To refresh a whole list, map each category to a search query, and run it on your own schedule. There's no daemon.
+
+```bash
+skill-customs discover --categories categories.yaml --out candidates.json
+```
+
+## Status
+
+Pre-release. Part of the [Try Professional](https://github.com/goranai/try-professional) repository, and usable entirely without it.
+
+MIT licensed.

skill_customs-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "skill-customs"
+dynamic = ["version"]
+description = "Agent skills security: a lockfile, a license check, and commit pinning for the skills you install from GitHub. Scanners plug in."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["agent-skills", "agent-skills-security", "claude-skills", "ai-agents", "lockfile", "license-check", "supply-chain-security", "security"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Topic :: Software Development :: Build Tools",
+  "Typing :: Typed",
+]
+dependencies = ["pyyaml>=6,<7"]
+
+[project.urls]
+Homepage = "https://github.com/goranai/try-professional"
+Repository = "https://github.com/goranai/try-professional"
+Documentation = "https://github.com/goranai/try-professional/blob/main/packages/skill-customs/README.md"
+Issues = "https://github.com/goranai/try-professional/issues"
+
+[project.scripts]
+skill-customs = "skill_customs.cli:main"
+
+[tool.hatch.version]
+path = "src/skill_customs/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/skill_customs"]

skill_customs-0.1.0/src/skill_customs/__init__.py

@@ -0,0 +1,77 @@
+"""skill-customs: the lockfile, license, and pinning layer for agent skills.
+
+Fetching never runs anything from a skill. A passing scan means no known signal was
+found. It does not mean a skill is safe.
+"""
+
+from .attribution import render_attribution
+from .discover import Candidate, SkillFile, discover, list_skill_paths, search_skill_files
+from .errors import (
+    ApprovalError,
+    FetchError,
+    LicenseRejected,
+    LockfileError,
+    NotASkill,
+    SkillCustomsError,
+    UnsafeArchive,
+)
+from .fetch import GitHubClient, is_full_sha
+from .frontmatter import SkillMetadata, read_skill_metadata
+from .hashing import content_hash
+from .install import PinResult, approve, pin, pin_local, remove, skill_dir, verify
+from .licenses import LicenseVerdict, check_license
+from .lockfile import Approval, LockEntry, Lockfile
+from .policy import Policy
+from .scan import (
+    BuiltinScanner,
+    CommandScanner,
+    Finding,
+    Scanner,
+    ScanReport,
+    decide_trust,
+    scan,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Approval",
+    "ApprovalError",
+    "BuiltinScanner",
+    "Candidate",
+    "CommandScanner",
+    "FetchError",
+    "Finding",
+    "GitHubClient",
+    "LicenseRejected",
+    "LicenseVerdict",
+    "LockEntry",
+    "Lockfile",
+    "LockfileError",
+    "NotASkill",
+    "PinResult",
+    "Policy",
+    "ScanReport",
+    "Scanner",
+    "SkillCustomsError",
+    "SkillFile",
+    "SkillMetadata",
+    "UnsafeArchive",
+    "__version__",
+    "approve",
+    "check_license",
+    "content_hash",
+    "decide_trust",
+    "discover",
+    "is_full_sha",
+    "list_skill_paths",
+    "pin",
+    "pin_local",
+    "read_skill_metadata",
+    "remove",
+    "render_attribution",
+    "scan",
+    "search_skill_files",
+    "skill_dir",
+    "verify",
+]

skill_customs-0.1.0/src/skill_customs/attribution.py

@@ -0,0 +1,32 @@
+"""Generate THIRD_PARTY_SKILLS.md from the lockfile, so it can't drift from what's installed."""
+
+from __future__ import annotations
+
+from .lockfile import Lockfile
+
+HEADER = """# Third-party skills
+
+Generated by `skill-customs attribution` from `skills.lock`. Don't edit by hand.
+"""
+
+
+def _cell(text: str) -> str:
+    """Skill names come from outside. Keep them from breaking out of a table cell."""
+    return text.replace("|", "\\|").replace("\n", " ")
+
+
+def render_attribution(lock: Lockfile) -> str:
+    entries = [lock.entries[key] for key in sorted(lock.entries) if lock.entries[key].host != "local"]
+    if not entries:
+        return HEADER + "\nNo third-party skills are installed.\n"
+    lines = [HEADER, "| Skill | Source | Commit | License | Commercial use | Trust |", "|---|---|---|---|---|---|"]
+    for entry in entries:
+        source = f"https://github.com/{entry.repo}"
+        lines.append(
+            f"| {_cell(entry.skill_id)} | {source} | `{entry.commit[:12]}` | {_cell(entry.license_spdx or 'unknown')} "
+            f"| {entry.commercial_use} | {entry.trust} |"
+        )
+    restricted = [e.skill_id for e in entries if e.commercial_use != "allowed"]
+    if restricted:
+        lines += ["", "## Check before commercial use", ""] + [f"- {_cell(skill)}" for skill in restricted]
+    return "\n".join(lines) + "\n"