@shanmukhdheekonda/skillporter 0.0.0-stage → 2.0.1

package/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.

package/README.md

@@ -1,3 +1,231 @@
-# Temporary Holding Version
+# SKILLPORTER
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## 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 uvx from PyPI (zero install)
+uvx skillporter diagnose .
+
+# 2. Install globally via uv tool or pipx from PyPI
+uv tool install skillporter
+pipx install skillporter
+
+# 3. Run via npx from npm (or directly from GitHub)
+npx @shanmukhdheekonda/skillporter diagnose .
+npx github:Shanmukh-l33t/skillporter diagnose .
+
+# 4. 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
+```
+
+### 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 skillporter mcp
+codex mcp add skillporter -- uvx 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).

package/npm/README.md

@@ -0,0 +1,25 @@
+# skillporter (NPX Wrapper)
+
+**ONE SKILL. EVERY AGENT.**
+
+This npm package provides the zero-install `npx skillporter` CLI launcher for the [Skillporter](https://github.com/Shanmukh-l33t/skillporter) universal Agent Skill package manager.
+
+## Usage
+
+```bash
+# Diagnose skill reachability and SHA-256 drift across harnesses
+npx skillporter diagnose .
+
+# Install a skill from GitHub across all detected harnesses
+npx skillporter add owner/repository --harness all
+
+# Static security & supply-chain scan
+npx skillporter scan .
+
+# Synchronize skills from skillporter.yaml
+npx skillporter sync
+```
+
+## Architecture
+
+`npx skillporter` is a thin Node.js launcher that invokes the bundled, zero-dependency `skillporter.pyz` Python core (or delegates to `uvx skillporter`), ensuring 100% identical behavior across `npx`, `uvx`, `pipx`, and standalone binaries.

package/npm/bin/skillporter.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * Skillporter NPX Launcher
+ *
+ * Thin Node.js wrapper that delegates 100% of execution to the authoritative
+ * Skillporter Python core (bundled `skillporter.pyz`, local `python3`/`python`,
+ * or `uvx skillporter`). Never duplicates business logic.
+ */
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const args = process.argv.slice(2);
+const bundledPyz = path.join(__dirname, "skillporter.pyz");
+const repoRoot = path.resolve(__dirname, "..", "..");
+
+function hasCommand(cmd, checkArgs = ["--version"]) {
+  const res = spawnSync(cmd, checkArgs, { stdio: "ignore" });
+  return res.status === 0;
+}
+
+function runAndExit(cmd, cmdArgs, extraEnv = {}) {
+  const res = spawnSync(cmd, cmdArgs, {
+    stdio: "inherit",
+    env: Object.assign({}, process.env, extraEnv),
+  });
+  if (res.error) {
+    console.error(`skillporter launcher error: ${res.error.message}`);
+    process.exit(2);
+  }
+  process.exit(res.status !== null ? res.status : 1);
+}
+
+// 1. Prefer bundled zero-dependency zipapp with python3 / python / py -3
+if (fs.existsSync(bundledPyz)) {
+  for (const py of ["python3", "python"]) {
+    if (hasCommand(py)) {
+      runAndExit(py, [bundledPyz, ...args]);
+    }
+  }
+  if (process.platform === "win32" && hasCommand("py", ["-3", "--version"])) {
+    runAndExit("py", ["-3", bundledPyz, ...args]);
+  }
+}
+
+// 2. Fallback: run from source checkout if inside the repository
+if (fs.existsSync(path.join(repoRoot, "skillporter", "__main__.py"))) {
+  for (const py of ["python3", "python"]) {
+    if (hasCommand(py)) {
+      runAndExit(py, ["-m", "skillporter", ...args], { PYTHONPATH: repoRoot });
+    }
+  }
+}
+
+// 3. Fallback: delegate to uvx if installed
+if (hasCommand("uvx")) {
+  runAndExit("uvx", ["skillporter", ...args]);
+}
+
+console.error(
+  "error: Skillporter requires Python 3.9+ or `uvx` in PATH.\n" +
+    "Install Python from https://www.python.org/ or uv from https://docs.astral.sh/uv/"
+);
+process.exit(2);

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@shanmukhdheekonda/skillporter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.1",
+  "description": "ONE SKILL. EVERY AGENT. Universal package manager, validator, security scanner, and synchronizer for AI-agent skills.",
+  "keywords": [
+    "agent-skills",
+    "ai-agents",
+    "claude-code",
+    "codex",
+    "cursor",
+    "windsurf",
+    "github-copilot",
+    "gemini-cli",
+    "hermes",
+    "openclaw",
+    "openhands",
+    "goose",
+    "mcp"
+  ],
+  "homepage": "https://github.com/Shanmukh-l33t/skillporter",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Shanmukh-l33t/skillporter.git"
+  },
+  "license": "MIT",
+  "author": "Shanmukh Dheekonda",
+  "bin": {
+    "skillporter": "./npm/bin/skillporter.js",
+    "skillporter-cli": "./npm/bin/skillporter.js"
+  },
+  "files": [
+    "npm/bin/skillporter.js",
+    "npm/bin/skillporter.pyz",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}