skillporter 2.0.0__tar.gz

skillporter-2.0.0/LICENSE

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

skillporter-2.0.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: skillporter
+Version: 2.0.0
+Summary: ONE SKILL. EVERY AGENT. Universal package manager, validator, security scanner, and synchronizer for AI-agent skills across 19+ harnesses.
+Author: Shanmukh Dheekonda
+License: MIT
+Project-URL: Homepage, https://github.com/Shanmukh-l33t/skillporter
+Project-URL: Issues, https://github.com/Shanmukh-l33t/skillporter/issues
+Project-URL: Changelog, https://github.com/Shanmukh-l33t/skillporter/blob/main/CHANGELOG.md
+Keywords: agent-skills,claude-code,codex,cursor,windsurf,github-copilot,gemini-cli,hermes,openclaw,openhands,goose,mcp,developer-tools
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# SKILLPORTER
+
+## ONE SKILL. EVERY AGENT.
+
+**Install, manage, validate, security-scan, and synchronize AI-agent skills across the entire agent ecosystem.**
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
+[![Harnesses: 19 Verified](https://img.shields.io/badge/harnesses-19%20supported-00b4d8)](docs/harnesses/README.md)
+[![Tests: 60 Passing](https://img.shields.io/badge/tests-60%20passing-brightgreen)](tests/)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-success)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+<p align="center">
+  <img src="docs/assets/demo.svg" alt="Skillporter Terminal Demonstration" width="860" />
+</p>
+
+Every AI coding and autonomous agent harness reads skills from a **different directory**:
+
+| Harness | Project Path | Personal / Global Path | Support |
+|---|---|---|---|
+| **Claude Code** | `.claude/skills/` | `~/.claude/skills/` | `NATIVE` |
+| **OpenAI Codex** | `.agents/skills/` | `~/.agents/skills/` | `NATIVE` |
+| **Cursor** | `.agents/skills/`, `.cursor/skills/` (+2 compat) | `~/.agents/skills/`, `~/.cursor/skills/` | `NATIVE` |
+| **GitHub Copilot** | `.github/skills/`, `.agents/skills/` (+1 compat) | `~/.copilot/skills/`, `~/.agents/skills/` | `NATIVE` |
+| **Gemini CLI** | `.agents/skills/`, `.gemini/skills/` | `~/.agents/skills/`, `~/.gemini/skills/` | `NATIVE` |
+| **Google Antigravity** | `.agents/skills/` (+1 compat) | `~/.gemini/config/skills/` | `NATIVE` |
+| **Windsurf** | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` | `NATIVE` |
+| **Cline** | `.cline/skills/`, `.clinerules/skills/` (+2 compat) | `~/.cline/skills/` | `NATIVE` |
+| **Roo Code** | `.roo/skills/`, `.agents/skills/` | `~/.roo/skills/`, `~/.agents/skills/` | `NATIVE` |
+| **OpenCode** | `.opencode/skills/`, `.agents/skills/` (+1 compat) | `~/.config/opencode/skills/` (+2 compat) | `NATIVE` |
+| **Zed** | `.agents/skills/` | `~/.agents/skills/` | `NATIVE` |
+| **Replit Agent** | `.agents/skills/`, `.claude/skills/` | `~/.config/agents/skills/` | `NATIVE` |
+| **JetBrains Junie** | `.junie/skills/`, `.agents/skills/` | `~/.junie/skills/`, `~/.agents/skills/` | `NATIVE` |
+| **Hermes Agent** | `.hermes/skills/` | `$HERMES_HOME/skills/<category>/<name>` | `NATIVE` |
+| **OpenClaw** | `.openclaw/skills/`, `skills/`, `.agents/skills/` | `~/.openclaw/skills/`, `~/.agents/skills/` | `NATIVE` |
+| **OpenHands** | `.agents/skills/`, `.openhands/skills/` | `~/.agents/skills/`, `~/.openhands/skills/` | `NATIVE` |
+| **Goose** | `.agents/skills/`, `.goose/skills/` | `~/.agents/skills/`, `~/.config/goose/skills/` | `NATIVE` |
+| **Continue** | `.continue/skills/` (`.continue/rules/` adapted) | `~/.continue/skills/` | `COMPATIBLE` |
+| **Aider / AiderDesk** | `.aider-desk/skills/` (`CONVENTIONS.md` adapted) | `~/.aider-desk/skills/` | `ADAPTED` |
+
+A skill authored for Claude Code in `.claude/skills/` is silently invisible to OpenAI Codex, Gemini CLI, Zed, and Windsurf. Hand-rolled symlinks break in Docker build contexts, `git worktree`, and Windows checkouts — while manual copies silently drift out of sync.
+
+**Skillporter solves the entire lifecycle:** one command resolves skills from GitHub or local paths, runs a static security and supply-chain scan, deduplicates shared destinations (`.agents/skills`), tracks ownership and SHA-256 content hashes, detects content drift across copies, and supports deterministic lockfiles (`skillporter.lock`) and transactional rollback.
+
+---
+
+## One-Command Installation & Zero-Install Execution
+
+```bash
+# 1. Run immediately via npx directly from GitHub (zero install)
+npx github:Shanmukh-l33t/skillporter diagnose .
+
+# 2. Run immediately via uvx directly from GitHub (zero install)
+uvx --from git+https://github.com/Shanmukh-l33t/skillporter skillporter diagnose .
+
+# 3. Install globally via curl (Linux/macOS — bypasses PEP 668 externally-managed-environment)
+curl -fsSL https://raw.githubusercontent.com/Shanmukh-l33t/skillporter/main/install.sh | sh
+
+# 4. Install globally via uv tool or pipx directly from GitHub
+uv tool install git+https://github.com/Shanmukh-l33t/skillporter
+pipx install git+https://github.com/Shanmukh-l33t/skillporter
+```
+
+### Native Agent Integration (MCP Server)
+
+Register Skillporter directly inside Claude Code, Codex, Cursor, Windsurf, or Hermes so your agent can diagnose, scan, and synchronize skills on command:
+
+```bash
+claude mcp add skillporter -- uvx --from git+https://github.com/Shanmukh-l33t/skillporter skillporter mcp
+codex mcp add skillporter -- uvx --from git+https://github.com/Shanmukh-l33t/skillporter skillporter mcp
+```
+
+---
+
+## 60-Second Quick Start
+
+```bash
+# 1. Detect which AI agent harnesses are installed or active in your repo
+skillporter detect .
+
+# 2. Install a skill from GitHub across all detected harnesses (validates + security-scans first)
+skillporter add anthropics/skills --skill pdf --harness all
+
+# 3. Diagnose reachability, broken symlinks, duplicate loading, and SHA-256 content drift
+skillporter diagnose .
+
+# 4. Run a static supply-chain security scan on any skill directory
+skillporter scan .
+
+# 5. Initialize skillporter.yaml, synchronize teammates, and pin skillporter.lock
+skillporter init
+skillporter sync
+skillporter lock
+```
+
+---
+
+## Real-World Evidence: Why Skillporter Exists
+
+Built after auditing the exact failure modes reported across upstream agent ecosystems:
+
+- **[agentskills/agentskills#15](https://github.com/agentskills/agentskills/issues/15)** (130+ comments) — *"Claude is looking at `.claude/skills/` and GitHub Copilot is looking at `.github/skills/`… create symlinks that match the specific folder of each harness"*
+- **[thn-inc/claude-tweaks#3000](https://github.com/thn-inc/claude-tweaks/issues/3000)** — skill resolution misses `.agents/skills` when the symlink is absent or inside a **git worktree**
+- **[openclaw/openclaw#14593](https://github.com/openclaw/openclaw/issues/14593)** — symlinked skill installs fail inside Docker build contexts
+- **[squne121/loop-protocol](https://github.com/squne121/loop-protocol/issues)** — replacing broken Codex skill symlinks with a fail-closed `.agents/skills` bridge
+
+---
+
+## Key Features
+
+### 1. Universal Source Resolution (`skillporter add`)
+Install skills from:
+- **GitHub shorthand**: `skillporter add owner/repo` or `skillporter add owner/repo/skills/my-skill@v1.2.0`
+- **GitHub tree URLs**: `skillporter add https://github.com/owner/repo/tree/main/skills/my-skill`
+- **Git URLs & commit SHAs**: `skillporter add https://example.com/skills.git --ref ceb64c6`
+- **ZIP & tar.gz archives**: `skillporter add ./bundle.zip` (hardened against Zip-Slip and symlink escapes)
+- **Registry slugs**: `skillporter add registry:anthropics/skills`
+- **Local directories**: `skillporter add ./authoring/my-skill --harness claude-code --harness codex`
+
+### 2. SHA-256 Content-Drift & Duplicate Detection (`skillporter diagnose`)
+Competing tools copy files once and report success forever. Skillporter hashes every file inside every installed skill copy (`SHA-256`).
+- **Drift**: If you edit `.claude/skills/my-skill/SKILL.md` and forget to update `.agents/skills/my-skill/SKILL.md`, `skillporter diagnose` flags `DRIFT` with the exact diverging hashes and exits `1`.
+- **Duplicate loading**: If a skill is installed in both `.agents/skills` and `.cursor/skills`, `diagnose` flags `DUPLICATE` so Cursor does not load the same skill twice.
+
+### 3. Static Security & Supply-Chain Protection (`skillporter scan`)
+Agent skills contain natural-language instructions and executable scripts. Before installing any skill, Skillporter inspects all Markdown and script files for:
+- **Embedded secrets & private keys** (`sec-private-key`, `sec-aws-key`, `sec-github-token`, `sec-api-key`)
+- **Prompt injection & covert overrides** (`sec-prompt-override`, `sec-hidden-unicode`, `sec-html-comment-instruction`)
+- **Dangerous execution patterns** (`sec-curl-pipe-sh`, `sec-reverse-shell`, `sec-credential-harvest`, `sec-dynamic-eval`)
+- **Filesystem escapes** (`sec-symlink-escape`, `sec-path-traversal`, `sec-binary-artifact`)
+
+*Transparency note: Static scanning inspects files for known dangerous patterns and structural escapes; it does not guarantee runtime safety.*
+
+### 4. Manifest (`skillporter.yaml`), Lockfile (`skillporter.lock`) & Rollback
+Declare your project's skills in `skillporter.yaml`:
+
+```yaml
+schema_version: 1
+project: acme-platform
+scope: project
+strategy: copy
+security_policy: HIGH
+harnesses:
+  - claude-code
+  - codex
+  - cursor
+  - github-copilot
+skills:
+  - name: skillporter
+    source: Shanmukh-l33t/skillporter/skills/skillporter
+    ref: main
+```
+
+Run `skillporter sync` to reconcile the workspace, `skillporter lock` to pin exact git commits and SHA-256 tree hashes in `skillporter.lock`, and `skillporter rollback <skill>` to restore the previous snapshot from `.skillporter/backups/` if an update introduces a regression.
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `skillporter add <source>` | Resolve, validate, security-scan, and install skills from GitHub, Git, archive, or local path |
+| `skillporter diagnose [path]` | Check reachability, broken symlinks, SHA-256 content drift, duplicates, and spec compliance |
+| `skillporter doctor [path] [--fix]` | Run full workspace health check and optionally auto-repair missing/drifted installs |
+| `skillporter scan [path]` | Run static supply-chain and prompt-injection security assessment |
+| `skillporter validate [path]` | Validate `SKILL.md` frontmatter and body against the [Agent Skills spec](https://agentskills.io/specification) |
+| `skillporter inspect <source>` | Inspect a local or remote skill package (files, scripts, security, adapted previews) before installing |
+| `skillporter detect [path]` | Detect which AI agent harnesses are installed on the machine or active in the project |
+| `skillporter matrix` | Print the 19-harness compatibility and verification matrix (`--json` supported) |
+| `skillporter init [path]` | Generate `skillporter.yaml` from discovered skills and active harnesses |
+| `skillporter sync [path]` | Reconcile workspace skills across target harnesses and update `skillporter.lock` |
+| `skillporter lock [path]` | Write deterministic `skillporter.lock` with SHA-256 content tree hashes |
+| `skillporter list [path]` | List managed and discovered skills with ownership, hashes, and active harnesses |
+| `skillporter update [skill]` | Update tracked skills from their recorded upstream source |
+| `skillporter rollback <skill>` | Restore a skill to its previous backup snapshot in `.skillporter/backups/` |
+| `skillporter install <path>` | Low-level local directory installer (`--strategy copy\|symlink`, `--adapt`, `--force`) |
+| `skillporter remove <skill>` | Remove a skill from target harnesses (`uninstall` alias supported) |
+| `skillporter search [query]` | Search the seed and configured skill registry catalog |
+| `skillporter info <target>` | Show detailed metadata for a harness adapter or registry package |
+| `skillporter pack [path]` | Build an immutable `.tar.gz` release archive and `provenance.json` checksum manifest |
+| `skillporter mcp` | Start the zero-dependency stdio JSON-RPC 2.0 MCP server |
+
+### Exit Codes (CI Contract)
+- `0` — Clean / all checks passed
+- `1` — Findings detected (missing reachability, content drift, broken symlink, spec error, or security policy block)
+- `2` — Usage or runtime error (invalid path, unknown harness, unsafe overwrite refusal)
+
+---
+
+## GitHub Action Integration
+
+Validate `SKILL.md` compliance, scan for security risks, and verify harness reachability automatically on every pull request:
+
+```yaml
+name: Skillporter Check
+on: [push, pull_request]
+jobs:
+  skills:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Shanmukh-l33t/skillporter@v2
+        with:
+          command: validate
+          path: .
+          run-security-scan: "true"
+```
+
+---
+
+## Documentation
+
+- [Getting Started](docs/getting-started/README.md)
+- [Installation & Distribution (uvx, npx, binaries, MCP)](docs/installation/README.md)
+- [Supported Harnesses & Evidence Directory (19 Harnesses)](docs/harnesses/README.md)
+- [CLI Command Reference](docs/commands/README.md)
+- [Configuration (`skillporter.yaml` & `skillporter.lock`)](docs/configuration/README.md)
+- [Security & Supply-Chain Model](docs/security/README.md)
+- [System Architecture](ARCHITECTURE.md)
+- [Adapter Development SDK](docs/adapters/README.md)
+- [Registry & Immutable Packaging](docs/registry/README.md)
+- [Troubleshooting](docs/troubleshooting/README.md)
+- [Contributing Guide](CONTRIBUTING.md)
+- [Product Roadmap](ROADMAP.md)
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

skillporter-2.0.0/README.md

@@ -0,0 +1,230 @@
+# SKILLPORTER
+
+## ONE SKILL. EVERY AGENT.
+
+**Install, manage, validate, security-scan, and synchronize AI-agent skills across the entire agent ecosystem.**
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
+[![Harnesses: 19 Verified](https://img.shields.io/badge/harnesses-19%20supported-00b4d8)](docs/harnesses/README.md)
+[![Tests: 60 Passing](https://img.shields.io/badge/tests-60%20passing-brightgreen)](tests/)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-success)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+<p align="center">
+  <img src="docs/assets/demo.svg" alt="Skillporter Terminal Demonstration" width="860" />
+</p>
+
+Every AI coding and autonomous agent harness reads skills from a **different directory**:
+
+| Harness | Project Path | Personal / Global Path | Support |
+|---|---|---|---|
+| **Claude Code** | `.claude/skills/` | `~/.claude/skills/` | `NATIVE` |
+| **OpenAI Codex** | `.agents/skills/` | `~/.agents/skills/` | `NATIVE` |
+| **Cursor** | `.agents/skills/`, `.cursor/skills/` (+2 compat) | `~/.agents/skills/`, `~/.cursor/skills/` | `NATIVE` |
+| **GitHub Copilot** | `.github/skills/`, `.agents/skills/` (+1 compat) | `~/.copilot/skills/`, `~/.agents/skills/` | `NATIVE` |
+| **Gemini CLI** | `.agents/skills/`, `.gemini/skills/` | `~/.agents/skills/`, `~/.gemini/skills/` | `NATIVE` |
+| **Google Antigravity** | `.agents/skills/` (+1 compat) | `~/.gemini/config/skills/` | `NATIVE` |
+| **Windsurf** | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` | `NATIVE` |
+| **Cline** | `.cline/skills/`, `.clinerules/skills/` (+2 compat) | `~/.cline/skills/` | `NATIVE` |
+| **Roo Code** | `.roo/skills/`, `.agents/skills/` | `~/.roo/skills/`, `~/.agents/skills/` | `NATIVE` |
+| **OpenCode** | `.opencode/skills/`, `.agents/skills/` (+1 compat) | `~/.config/opencode/skills/` (+2 compat) | `NATIVE` |
+| **Zed** | `.agents/skills/` | `~/.agents/skills/` | `NATIVE` |
+| **Replit Agent** | `.agents/skills/`, `.claude/skills/` | `~/.config/agents/skills/` | `NATIVE` |
+| **JetBrains Junie** | `.junie/skills/`, `.agents/skills/` | `~/.junie/skills/`, `~/.agents/skills/` | `NATIVE` |
+| **Hermes Agent** | `.hermes/skills/` | `$HERMES_HOME/skills/<category>/<name>` | `NATIVE` |
+| **OpenClaw** | `.openclaw/skills/`, `skills/`, `.agents/skills/` | `~/.openclaw/skills/`, `~/.agents/skills/` | `NATIVE` |
+| **OpenHands** | `.agents/skills/`, `.openhands/skills/` | `~/.agents/skills/`, `~/.openhands/skills/` | `NATIVE` |
+| **Goose** | `.agents/skills/`, `.goose/skills/` | `~/.agents/skills/`, `~/.config/goose/skills/` | `NATIVE` |
+| **Continue** | `.continue/skills/` (`.continue/rules/` adapted) | `~/.continue/skills/` | `COMPATIBLE` |
+| **Aider / AiderDesk** | `.aider-desk/skills/` (`CONVENTIONS.md` adapted) | `~/.aider-desk/skills/` | `ADAPTED` |
+
+A skill authored for Claude Code in `.claude/skills/` is silently invisible to OpenAI Codex, Gemini CLI, Zed, and Windsurf. Hand-rolled symlinks break in Docker build contexts, `git worktree`, and Windows checkouts — while manual copies silently drift out of sync.
+
+**Skillporter solves the entire lifecycle:** one command resolves skills from GitHub or local paths, runs a static security and supply-chain scan, deduplicates shared destinations (`.agents/skills`), tracks ownership and SHA-256 content hashes, detects content drift across copies, and supports deterministic lockfiles (`skillporter.lock`) and transactional rollback.
+
+---
+
+## One-Command Installation & Zero-Install Execution
+
+```bash
+# 1. Run immediately via npx directly from GitHub (zero install)
+npx github:Shanmukh-l33t/skillporter diagnose .
+
+# 2. Run immediately via uvx directly from GitHub (zero install)
+uvx --from git+https://github.com/Shanmukh-l33t/skillporter skillporter diagnose .
+
+# 3. Install globally via curl (Linux/macOS — bypasses PEP 668 externally-managed-environment)
+curl -fsSL https://raw.githubusercontent.com/Shanmukh-l33t/skillporter/main/install.sh | sh
+
+# 4. Install globally via uv tool or pipx directly from GitHub
+uv tool install git+https://github.com/Shanmukh-l33t/skillporter
+pipx install git+https://github.com/Shanmukh-l33t/skillporter
+```
+
+### Native Agent Integration (MCP Server)
+
+Register Skillporter directly inside Claude Code, Codex, Cursor, Windsurf, or Hermes so your agent can diagnose, scan, and synchronize skills on command:
+
+```bash
+claude mcp add skillporter -- uvx --from git+https://github.com/Shanmukh-l33t/skillporter skillporter mcp
+codex mcp add skillporter -- uvx --from git+https://github.com/Shanmukh-l33t/skillporter skillporter mcp
+```
+
+---
+
+## 60-Second Quick Start
+
+```bash
+# 1. Detect which AI agent harnesses are installed or active in your repo
+skillporter detect .
+
+# 2. Install a skill from GitHub across all detected harnesses (validates + security-scans first)
+skillporter add anthropics/skills --skill pdf --harness all
+
+# 3. Diagnose reachability, broken symlinks, duplicate loading, and SHA-256 content drift
+skillporter diagnose .
+
+# 4. Run a static supply-chain security scan on any skill directory
+skillporter scan .
+
+# 5. Initialize skillporter.yaml, synchronize teammates, and pin skillporter.lock
+skillporter init
+skillporter sync
+skillporter lock
+```
+
+---
+
+## Real-World Evidence: Why Skillporter Exists
+
+Built after auditing the exact failure modes reported across upstream agent ecosystems:
+
+- **[agentskills/agentskills#15](https://github.com/agentskills/agentskills/issues/15)** (130+ comments) — *"Claude is looking at `.claude/skills/` and GitHub Copilot is looking at `.github/skills/`… create symlinks that match the specific folder of each harness"*
+- **[thn-inc/claude-tweaks#3000](https://github.com/thn-inc/claude-tweaks/issues/3000)** — skill resolution misses `.agents/skills` when the symlink is absent or inside a **git worktree**
+- **[openclaw/openclaw#14593](https://github.com/openclaw/openclaw/issues/14593)** — symlinked skill installs fail inside Docker build contexts
+- **[squne121/loop-protocol](https://github.com/squne121/loop-protocol/issues)** — replacing broken Codex skill symlinks with a fail-closed `.agents/skills` bridge
+
+---
+
+## Key Features
+
+### 1. Universal Source Resolution (`skillporter add`)
+Install skills from:
+- **GitHub shorthand**: `skillporter add owner/repo` or `skillporter add owner/repo/skills/my-skill@v1.2.0`
+- **GitHub tree URLs**: `skillporter add https://github.com/owner/repo/tree/main/skills/my-skill`
+- **Git URLs & commit SHAs**: `skillporter add https://example.com/skills.git --ref ceb64c6`
+- **ZIP & tar.gz archives**: `skillporter add ./bundle.zip` (hardened against Zip-Slip and symlink escapes)
+- **Registry slugs**: `skillporter add registry:anthropics/skills`
+- **Local directories**: `skillporter add ./authoring/my-skill --harness claude-code --harness codex`
+
+### 2. SHA-256 Content-Drift & Duplicate Detection (`skillporter diagnose`)
+Competing tools copy files once and report success forever. Skillporter hashes every file inside every installed skill copy (`SHA-256`).
+- **Drift**: If you edit `.claude/skills/my-skill/SKILL.md` and forget to update `.agents/skills/my-skill/SKILL.md`, `skillporter diagnose` flags `DRIFT` with the exact diverging hashes and exits `1`.
+- **Duplicate loading**: If a skill is installed in both `.agents/skills` and `.cursor/skills`, `diagnose` flags `DUPLICATE` so Cursor does not load the same skill twice.
+
+### 3. Static Security & Supply-Chain Protection (`skillporter scan`)
+Agent skills contain natural-language instructions and executable scripts. Before installing any skill, Skillporter inspects all Markdown and script files for:
+- **Embedded secrets & private keys** (`sec-private-key`, `sec-aws-key`, `sec-github-token`, `sec-api-key`)
+- **Prompt injection & covert overrides** (`sec-prompt-override`, `sec-hidden-unicode`, `sec-html-comment-instruction`)
+- **Dangerous execution patterns** (`sec-curl-pipe-sh`, `sec-reverse-shell`, `sec-credential-harvest`, `sec-dynamic-eval`)
+- **Filesystem escapes** (`sec-symlink-escape`, `sec-path-traversal`, `sec-binary-artifact`)
+
+*Transparency note: Static scanning inspects files for known dangerous patterns and structural escapes; it does not guarantee runtime safety.*
+
+### 4. Manifest (`skillporter.yaml`), Lockfile (`skillporter.lock`) & Rollback
+Declare your project's skills in `skillporter.yaml`:
+
+```yaml
+schema_version: 1
+project: acme-platform
+scope: project
+strategy: copy
+security_policy: HIGH
+harnesses:
+  - claude-code
+  - codex
+  - cursor
+  - github-copilot
+skills:
+  - name: skillporter
+    source: Shanmukh-l33t/skillporter/skills/skillporter
+    ref: main
+```
+
+Run `skillporter sync` to reconcile the workspace, `skillporter lock` to pin exact git commits and SHA-256 tree hashes in `skillporter.lock`, and `skillporter rollback <skill>` to restore the previous snapshot from `.skillporter/backups/` if an update introduces a regression.
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `skillporter add <source>` | Resolve, validate, security-scan, and install skills from GitHub, Git, archive, or local path |
+| `skillporter diagnose [path]` | Check reachability, broken symlinks, SHA-256 content drift, duplicates, and spec compliance |
+| `skillporter doctor [path] [--fix]` | Run full workspace health check and optionally auto-repair missing/drifted installs |
+| `skillporter scan [path]` | Run static supply-chain and prompt-injection security assessment |
+| `skillporter validate [path]` | Validate `SKILL.md` frontmatter and body against the [Agent Skills spec](https://agentskills.io/specification) |
+| `skillporter inspect <source>` | Inspect a local or remote skill package (files, scripts, security, adapted previews) before installing |
+| `skillporter detect [path]` | Detect which AI agent harnesses are installed on the machine or active in the project |
+| `skillporter matrix` | Print the 19-harness compatibility and verification matrix (`--json` supported) |
+| `skillporter init [path]` | Generate `skillporter.yaml` from discovered skills and active harnesses |
+| `skillporter sync [path]` | Reconcile workspace skills across target harnesses and update `skillporter.lock` |
+| `skillporter lock [path]` | Write deterministic `skillporter.lock` with SHA-256 content tree hashes |
+| `skillporter list [path]` | List managed and discovered skills with ownership, hashes, and active harnesses |
+| `skillporter update [skill]` | Update tracked skills from their recorded upstream source |
+| `skillporter rollback <skill>` | Restore a skill to its previous backup snapshot in `.skillporter/backups/` |
+| `skillporter install <path>` | Low-level local directory installer (`--strategy copy\|symlink`, `--adapt`, `--force`) |
+| `skillporter remove <skill>` | Remove a skill from target harnesses (`uninstall` alias supported) |
+| `skillporter search [query]` | Search the seed and configured skill registry catalog |
+| `skillporter info <target>` | Show detailed metadata for a harness adapter or registry package |
+| `skillporter pack [path]` | Build an immutable `.tar.gz` release archive and `provenance.json` checksum manifest |
+| `skillporter mcp` | Start the zero-dependency stdio JSON-RPC 2.0 MCP server |
+
+### Exit Codes (CI Contract)
+- `0` — Clean / all checks passed
+- `1` — Findings detected (missing reachability, content drift, broken symlink, spec error, or security policy block)
+- `2` — Usage or runtime error (invalid path, unknown harness, unsafe overwrite refusal)
+
+---
+
+## GitHub Action Integration
+
+Validate `SKILL.md` compliance, scan for security risks, and verify harness reachability automatically on every pull request:
+
+```yaml
+name: Skillporter Check
+on: [push, pull_request]
+jobs:
+  skills:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Shanmukh-l33t/skillporter@v2
+        with:
+          command: validate
+          path: .
+          run-security-scan: "true"
+```
+
+---
+
+## Documentation
+
+- [Getting Started](docs/getting-started/README.md)
+- [Installation & Distribution (uvx, npx, binaries, MCP)](docs/installation/README.md)
+- [Supported Harnesses & Evidence Directory (19 Harnesses)](docs/harnesses/README.md)
+- [CLI Command Reference](docs/commands/README.md)
+- [Configuration (`skillporter.yaml` & `skillporter.lock`)](docs/configuration/README.md)
+- [Security & Supply-Chain Model](docs/security/README.md)
+- [System Architecture](ARCHITECTURE.md)
+- [Adapter Development SDK](docs/adapters/README.md)
+- [Registry & Immutable Packaging](docs/registry/README.md)
+- [Troubleshooting](docs/troubleshooting/README.md)
+- [Contributing Guide](CONTRIBUTING.md)
+- [Product Roadmap](ROADMAP.md)
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

skillporter-2.0.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "skillporter"
+version = "2.0.0"
+description = "ONE SKILL. EVERY AGENT. Universal package manager, validator, security scanner, and synchronizer for AI-agent skills across 19+ harnesses."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Shanmukh Dheekonda" }]
+keywords = [
+  "agent-skills",
+  "claude-code",
+  "codex",
+  "cursor",
+  "windsurf",
+  "github-copilot",
+  "gemini-cli",
+  "hermes",
+  "openclaw",
+  "openhands",
+  "goose",
+  "mcp",
+  "developer-tools",
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Build Tools",
+  "Topic :: Software Development :: Quality Assurance",
+  "Topic :: Security",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff>=0.6"]
+
+[project.scripts]
+skillporter = "skillporter.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Shanmukh-l33t/skillporter"
+Issues = "https://github.com/Shanmukh-l33t/skillporter/issues"
+Changelog = "https://github.com/Shanmukh-l33t/skillporter/blob/main/CHANGELOG.md"
+
+[tool.setuptools]
+packages = ["skillporter"]
+
+[tool.setuptools.package-data]
+skillporter = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

skillporter-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

skillporter-2.0.0/skillporter/__init__.py

@@ -0,0 +1,16 @@
+"""skillporter — Universal package manager and diagnostics engine for AI-agent skills.
+
+ONE SKILL. EVERY AGENT.
+
+Install, validate, scan, synchronize, and manage Agent Skills across 19+ AI
+coding and autonomous agent harnesses (Claude Code, OpenAI Codex, Cursor,
+GitHub Copilot, Gemini CLI, Google Antigravity, Windsurf, Cline, Roo Code,
+OpenCode, Zed, Replit Agent, JetBrains Junie, Hermes Agent, OpenClaw,
+OpenHands, Goose, Continue, and Aider).
+"""
+
+from __future__ import annotations
+
+__version__ = "2.0.0"
+
+__all__ = ["__version__"]

skillporter-2.0.0/skillporter/__main__.py

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

skillporter-2.0.0/skillporter/atomic.py

@@ -0,0 +1,55 @@
+"""Crash-safe file writes.
+
+A plain ``Path.write_text`` truncates the destination and then streams the new
+content. If the process dies (OOM, Ctrl-C, power loss) between those two steps,
+the user is left with a truncated or empty file — for skillporter that means a
+corrupted state file, manifest or lockfile, which is precisely the
+"failed operations must not leave the environment inconsistent" case.
+
+``atomic_write_text`` writes to a sibling temp file in the *same directory*
+(same filesystem, so ``os.replace`` is atomic) and renames it into place.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import tempfile
+from pathlib import Path
+
+
+def atomic_write_text(path: Path, content: str, *, encoding: str = "utf-8") -> None:
+    """Write *content* to *path* atomically.
+
+    The destination is either the previous content or the complete new content —
+    never a partial write. File permissions of an existing destination are
+    preserved so we do not silently widen them.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    existing_mode: int | None = None
+    try:
+        if path.exists():
+            existing_mode = path.stat().st_mode & 0o777
+    except OSError:
+        existing_mode = None
+
+    fd, tmp_name = tempfile.mkstemp(
+        dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp"
+    )
+    tmp = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "w", encoding=encoding, newline="\n") as fh:
+            fh.write(content)
+            fh.flush()
+            os.fsync(fh.fileno())
+        if existing_mode is not None:
+            with contextlib.suppress(OSError):
+                os.chmod(tmp, existing_mode)
+        os.replace(tmp, path)
+    except BaseException:
+        # Never leave a temp file behind, even on KeyboardInterrupt.
+        with contextlib.suppress(OSError):
+            tmp.unlink()
+        raise