Skip to content
Back to search

skills-compat-manager

Cross-platform compatibility layer for AI agent skills — pre-flight dependency checks, MCP-native, works with Claude Code, Cursor, Codex CLI, OpenCode and more

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hnaymyh123-henry--skills-compat-manager/badge.svg)](/listings/hnaymyh123-henry--skills-compat-manager)

HTML

<a href="/listings/hnaymyh123-henry--skills-compat-manager"><img src="/api/listings/hnaymyh123-henry--skills-compat-manager/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install

pip install git+https://github.com/hnaymyh123-henry/skills-compat-manager.git

# Optional: enable AI-powered COMPAT.yaml inference
pip install "git+https://github.com/hnaymyh123-henry/skills-compat-manager.git#egg=skills-compat[ai]"

Setup

# Auto-detect installed platforms (Claude Code, Cursor, etc.)
# and configure MCP server entries
skills-compat setup --skill-library ~/my-skills

Scan

# Scan a single skill
skills-compat scan pdf

# Scan all skills in your library
skills-compat scan

# JSON output for automation
skills-compat scan --json

Infer COMPAT.yaml with AI

# Let AI analyze your SKILL.md and generate COMPAT.yaml
skills-compat infer my-skill

# Infer for all skills that don't have COMPAT.yaml yet
skills-compat infer --all

# Choose AI provider: openai, claude, or rules (no API key needed)
skills-compat infer my-skill --provider rules

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 434 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="docs/architecture.svg" alt="Skills Compat Manager" width="640"/>
  3. </p>
  4. <h1 align="center">Skills Compat Manager</h1>
  5. <p align="center">
  6. <strong>Stop your AI agent from failing halfway through a skill.</strong><br/>
  7. One library for all your agent skills — with a pre-flight check built in.
  8. </p>
  9. <p align="center">
  10. <a href="#quick-start"><img src="https://img.shields.io/badge/Get_Started-2_min-blue?style=for-the-badge" alt="Quick Start"/></a>
  11. <img src="https://img.shields.io/badge/MCP-native-orange?style=for-the-badge" alt="MCP native"/>
  12. <img src="https://img.shields.io/badge/Python-3.11+-green?style=for-the-badge" alt="Python 3.11+"/>
  13. <img src="https://img.shields.io/badge/License-MIT-lightgrey?style=for-the-badge" alt="MIT License"/>
  14. </p>
  15. <p align="center">
  16. <a href="#quick-start">Quick Start</a> ·
  17. <a href="#how-it-works">How It Works</a> ·
  18. <a href="#cli-reference">CLI</a> ·
  19. <a href="#mcp-server">MCP Server</a> ·
  20. <a href="README.zh-CN.md">中文文档</a>
  21. </p>
  22. ---
  23. ## Why You'll Want This
  24. You've built (or downloaded) a bunch of AI agent skills. They work on your machine — until they don't.
  25. > *"It worked in Claude Code but Cursor can't run it."*
  26. > *"The agent started the task, then died on `ModuleNotFoundError: pandas`."*
  27. > *"I set `OPENAI_API_KEY` locally but the agent still returned an empty string."*
  28. **Skills Compat Manager fixes this in two moves:**
  29. 🗂️ **One library, every agent.** Drop your skills into a single folder. Claude Code, Cursor, Codex CLI, OpenCode — they all read from the same place via MCP. No more copy-pasting skills across tool configs.
  30. 🛡️ **Pre-flight check before execution.** Every time an agent loads a skill, we scan your environment against the skill's declared dependencies (packages · CLI tools · env vars · platform capabilities) and inject a **hard compatibility protocol** at the top. Missing `pandas`? The agent stops and asks *before* burning 10k tokens.
  31. Think of it as **`package.json` + a lockfile checker** — but for AI agent skills.
  32. ---
  33. ## See It In Action
  34. ```
  35. Agent: loading skill "pdf-tools" via MCP...
  36. ⚠ COMPATIBILITY DELTA — pdf-tools @ claude_code
  37. Status: BLOCKED
  38. Code Dependencies:
  39. - pandas: missing → pip install pandas
  40. - pypdf: available (4.0.1)
  41. External Services:
  42. - OPENAI_API_KEY: missing
  43. ─── AGENT PROTOCOL ───
  44. If Status is BLOCKED:
  45. 1. DO NOT execute the skill body below.
  46. 2. Report the missing dependencies to the user, verbatim.
  47. 3. Ask the user how to proceed.
  48. Agent (to you): Before I run pdf-tools, I need two things installed:
  49. 1. pandas (pip install pandas)
  50. 2. OPENAI_API_KEY environment variable
  51. How would you like to proceed?
  52. ```
  53. **The agent knows what's missing before it writes a single line of code.**
  54. <p align="center">
  55. <img src="docs/screenshots/ph-scan.png" alt="skills-compat scan output" width="860"/>
  56. </p>
  57. ---
  58. ## What This Tool Does — and Doesn't
  59. **Does**
  60. - Detects presence of Python packages, CLI binaries, environment variables, and declared platform capabilities
  61. - Surfaces missing deps to the agent *before* skill execution via a structured Delta
  62. - Provides a standardized, agent-readable compatibility protocol (OK / DEGRADED / BLOCKED)
  63. - Generates `COMPAT.yaml` via AI inference or static rules
  64. **Doesn't (yet)**
  65. - Validate package versions unless explicitly declared in `COMPAT.yaml`
  66. - Verify API keys are valid, active, or have quota remaining
  67. - Runtime-test platform capabilities — it trusts the platform's declared caps
  68. - Prevent a non-compliant agent from ignoring the compatibility block
  69. This is an **advisory layer with a hard protocol**, not a sandbox.
  70. ---
  71. ## The Problem, In Detail
  72. AI agent "skills" are reusable instruction files (`SKILL.md`) that tell an agent how to perform a task — parse a PDF, manage an Obsidian vault, generate a frontend design.
  73. A skill can silently depend on things that aren't always there:
  74. | Dimension | Example | What goes wrong |
  75. |---|---|---|
  76. | Python packages | `pandas`, `python-docx` | `ModuleNotFoundError` mid-task |
  77. | CLI tools | `pdftotext`, `ffmpeg` | Agent generates a command that doesn't exist |
  78. | Env variables | `VAULT_PATH`, `OPENAI_API_KEY` | Silent empty-string fallback, corrupted output |
  79. | Platform capabilities | `bash`, `web_search` | Agent tries to use a tool the platform doesn't have |
  80. Without a pre-flight check, the agent loads the skill, starts working, and fails halfway through — wasting tokens, time, and user trust.
  81. ---
  82. ## The Solution
  83. Skills Compat Manager scans your skills **before** the agent runs them, computes a structured **Delta** (gap analysis), and injects it into the skill content at load time.
  84. ```
  85. ┌─────────────────────────────────┐
  86. │ Agent loads "pdf" skill via MCP │
  87. └────────────────┬────────────────┘
  88. ▼
  89. ┌─────────────────────────────┐
  90. │ Scanner checks COMPAT.yaml │
  91. │ against runtime environment │
  92. └────────────────┬────────────┘
  93. ▼
  94. ┌─────────────────────────────────────────────┐
  95. │ ⚠ Compatibility Delta — pdf @ claude_code │
  96. │ │
  97. │ Code Deps: │
  98. │ ✓ pypdf ........ installed (4.0.1) │
  99. │ ✗ camelot-py ... missing [optional] │
  100. │ → pip install camelot-py │
  101. │ │
  102. │ System Tools: │
  103. │ ✗ pdftotext .... missing [optional] │
  104. │ → brew install poppler │
  105. │ │
  106. │ Status: DEGRADED │
  107. │ Proceed with caution — optional deps missing│
  108. └─────────────────────────────────────────────┘
  109. ▼
  110. ┌─────────────────────────────┐
  111. │ Agent sees the Delta BEFORE │
  112. │ the skill content begins │
  113. │ → adapts or warns the user │
  114. └─────────────────────────────┘
  115. ```
  116. The agent now **knows what's missing** before it writes a single line of code.
  117. ---
  118. ## Architecture
  119. <p align="center">
  120. <img src="docs/architecture.svg" alt="Skills Compat Manager architecture" width="860"/>
  121. </p>
  122. ---
  123. ## The Four-Dimensional Framework
  124. Every skill's dependencies are classified into four dimensions:
  125. <p align="center">
  126. <img src="docs/fourdim.svg" alt="COMPAT.yaml four dimensions" width="720"/>
  127. </p>
  128. <p align="center">
  129. <img src="docs/screenshots/ph-compat.png" alt="COMPAT.yaml example" width="860"/>
  130. </p>
  131. Example `COMPAT.yaml`:
  132. ```yaml
  133. schema_version: "2.0"
  134. requires:
  135. code_deps:
  136. - name: pandas
  137. description: "Data manipulation and analysis"
  138. required: true
  139. - name: seaborn
  140. description: "Statistical visualization"
  141. required: false
  142. system_tools:
  143. - name: pdftotext
  144. required: false
  145. external_services:
  146. - name: VAULT_PATH
  147. description: "Obsidian vault location"
  148. required: true
  149. runtime_capabilities:
  150. - name: bash
  151. required: true
  152. - name: file_write
  153. required: true
  154. ```
  155. > Don't want to write this by hand? Run `skills-compat infer <skill>` and AI generates it from your SKILL.md.
  156. ---
  157. ## Quick Start
  158. ### Install
  159. ```bash
  160. pip install git+https://github.com/hnaymyh123-henry/skills-compat-manager.git
  161. # Optional: enable AI-powered COMPAT.yaml inference
  162. pip install "git+https://github.com/hnaymyh123-henry/skills-compat-manager.git#egg=skills-compat[ai]"
  163. ```
  164. ### Setup
  165. ```bash
  166. # Auto-detect installed platforms (Claude Code, Cursor, etc.)
  167. # and configure MCP server entries
  168. skills-compat setup --skill-library ~/my-skills
  169. ```
  170. ### Scan
  171. ```bash
  172. # Scan a single skill
  173. skills-compat scan pdf
  174. # Scan all skills in your library
  175. skills-compat scan
  176. # JSON output for automation
  177. skills-compat scan --json
  178. ```
  179. ### Infer COMPAT.yaml with AI
  180. ```bash
  181. # Let AI analyze your SKILL.md and generate COMPAT.yaml
  182. skills-compat infer my-skill
  183. # Infer for all skills that don't have COMPAT.yaml yet
  184. skills-compat infer --all
  185. # Choose AI provider: openai, claude, or rules (no API key needed)
  186. skills-compat infer my-skill --provider rules
  187. ```
  188. ---
  189. ## How It Works
  190. <p align="center">
  191. <img src="docs/screenshots/ph-howitworks.png" alt="How It Works — 4 steps" width="860"/>
  192. </p>
  193. ### For AI Agents (MCP Server)
  194. The MCP server is the primary runtime interface. When an agent calls `get_skill`:
  195. 1. **Reads** the original `SKILL.md` content
  196. 2. **Scans** the runtime environment (installed packages, CLI tools, env vars)
  197. 3. **Computes** a Delta against the platform's capability profile
  198. 4. **Injects** the Delta block at the top of the skill content
  199. 5. **Returns** the augmented content to the agent
  200. The agent sees the compatibility status **before** the skill instructions begin, and can decide how to proceed.
  201. ### For Developers (CLI)
  202. The CLI is your setup and diagnostic tool:
  203. ```
  204. skills-compat setup → Auto-detect platforms, configure MCP
  205. skills-compat status → Overview of library health
  206. skills-compat scan → Run Delta analysis, see what's missing
  207. skills-compat verify → CI-friendly status check (exit code = status)
  208. skills-compat infer → AI-generate COMPAT.yaml from SKILL.md
  209. skills-compat fix → Interactive fix: suggest → run → re-verify
  210. skills-compat serve → Start the MCP server manually
  211. skills-compat config → View/update configuration
  212. ```
  213. `verify` returns exit code `0` (OK), `1` (DEGRADED), `2` (BLOCKED), `3` (UNSCANNED), or `4` (error) — drop it into CI with `skills-compat verify pdf && deploy`.
  214. `fix` closes the loop: for every missing dep it asks the LLM for 2–3 fix paths (each tagged `SAFE`/`MANUAL` + `agent_or_user`/`user_only`), runs the SAFE ones through a sandbox allowlist, re-scans, and prints the status transition (e.g. `BLOCKED → DEGRADED`). Use `--auto` for CI, `--yes` to skip confirmation prompts.
  215. ---
  216. ## MCP Server
  217. ### Configuration
  218. Add to your MCP client configuration:
  219. **Claude Code** (`~/.claude/settings.json`):
  220. ```json
  221. {
  222. "mcpServers": {
  223. "skills-compat": {
  224. "command": "skills-compat",
  225. "args": ["serve"],
  226. "env": {
  227. "SKILL_LIBRARY": "/path/to/your/skills"
  228. }
  229. }
  230. }
  231. }
  232. ```
  233. **Cursor** (`.cursor/mcp.json`):
  234. ```json
  235. {
  236. "mcpServers": {
  237. "skills-compat": {
  238. "command": "skills-compat",
  239. "args": ["serve"],
  240. "env": {
  241. "SKILL_LIBRARY": "/path/to/your/skills"
  242. }
  243. }
  244. }
  245. }
  246. ```
  247. Or let the CLI do it automatically:
  248. ```bash
  249. skills-compat setup --skill-library /path/to/your/skills
  250. ```
  251. ### Available Tools
  252. | Tool | Description |
  253. |---|---|
  254. | `list_skills` | List all skills in the library |
  255. | `get_skill` | Load skill content with Delta block injected |
  256. | `scan_skills` | Run compatibility scan across all skills |
  257. | `get_skill_info` | Get metadata and COMPAT.yaml for a skill |
  258. | `search_skills` | Search skills by keyword |
  259. | `suggest_fix` | Get AI-powered fix suggestions (each path tagged with actor + safety) |
  260. | `apply_fix` | Execute a SAFE fix command through a sandbox allowlist, then re-scan |
  261. | `refresh_runtime` | Re-detect the runtime environment |
  262. ---
  263. ## Supported Platforms
  264. <p align="center">
  265. <img src="docs/screenshots/ph-platforms.png" alt="Supported platforms" width="860"/>
  266. </p>
  267. | Platform | Capabilities | Confidence | Auto-detected |
  268. |---|---|---|---|
  269. | Claude Code | `bash` `file_read` `file_write` `web_search` `web_fetch` `python_runtime` `lsp` `notebook` `subagent` `monitor` | verified | ✓ |
  270. | Cursor | `bash` `file_read` `file_write` `web_search` | partial | ✓ |
  271. | Codex CLI | `bash` `file_read` `file_write` `python_runtime` | verified | ✓ |
  272. | OpenCode | `bash` `file_read` `file_write` `web_search` `web_fetch` `python_runtime` `lsp` | verified | ✓ |
  273. | Claude Desktop | `file_read` `file_write` | partial | ✓ |
  274. Confidence levels reflect how well the capability list has been verified against official documentation (`verified` = sourced from official docs, `partial` = docs incomplete or inaccessible, `unverified` = best-effort estimate). See `data/platform_profiles.yaml` for sources and verification dates.
  275. A few platform-specific notes worth knowing: Codex CLI has network blocked by default in all sandbox modes — there is no built-in `web_search`. Claude Desktop's native tool set is minimal; most capabilities (web, shell, full filesystem) come from user-installed MCP servers, not built-ins.
  276. Platform detection happens automatically via the MCP handshake (`clientInfo.name`) — no manual configuration needed. **Adding a new platform** requires only editing `data/platform_profiles.yaml`. If your agent platform supports self-reporting via `capabilities.experimental["skills-compat:platform-tools"]` in the MCP `initialize` handshake, its capabilities are used directly and take priority over the static profile.
  277. ---
  278. ## AI Features
  279. ### Multi-Provider Inference
  280. COMPAT.yaml inference supports three providers with automatic fallback:
  281. ```
  282. OpenAI (gpt-4o) → Anthropic Claude → Rules-based (no API key)
  283. ```
  284. The AI analyzes your SKILL.md content and produces a complete COMPAT.yaml with:
  285. - **stdlib filtering** — Python standard library modules are automatically excluded
  286. - **PyPI name resolution** — Import names are mapped to correct pip package names (`yaml` → `pyyaml`, `cv2` → `opencv-python`)
  287. - **required/optional classification** — Each dependency is judged as required or optional based on its role in the skill
  288. ### Fix Suggestions
  289. When the scanner finds a missing dependency, `suggest_fix` generates 2–3 actionable solution paths. Every path is classified on two axes so the agent knows exactly what it can do autonomously:
  290. ```
  291. Path A: Install [SAFE · agent_or_user · low effort]
  292. → pip install camelot-py
  293. Path B: Use alternative library [MANUAL · user_only · medium effort]
  294. → Edit SKILL.md to use tabula-py instead
  295. Path C: Mark as optional [MANUAL · user_only · low effort]
  296. → Accept graceful degradation
  297. ```
  298. - `SAFE` + `agent_or_user` → the agent may execute it via `apply_fix` (or `skills-compat fix --auto`), subject to the allowlist (`pip`/`npm`/`yarn`/`mkdir`/`touch`) and a hard denylist (`sudo`, `rm`, `|sh`, `>/etc`, `&&rm`, etc.).
  299. - `MANUAL` or `user_only` → the agent surfaces the commands to the human, never runs them.
  300. ---
  301. ## Project Structure
  302. ```
  303. skills-compat-manager/
  304. ├── app/
  305. │ ├── cli.py # CLI entry point (9 commands)
  306. │ ├── mcp_server.py # MCP stdio server (8 tools)
  307. │ ├── scanner.py # Delta computation engine; reads COMPAT.yaml from central store
  308. │ ├── ai_engine.py # AI inference (OpenAI / Claude / rules)
  309. │ ├── models.py # Pydantic data models
  310. │ ├── config.py # Settings & paths; loads platform profiles from data/
  311. │ ├── runtime_detector.py # OS / pip / CLI / env detection
  312. │ ├── skill_manager.py # Skill discovery; writes COMPAT.yaml to central store
  313. │ ├── platform_resolver.py # MCP handshake resolution + experimental capability hook
  314. │ ├── platform_detector.py # Installed platform detection
  315. │ ├── tool_registry.py # MCP tool registry & platform capability lookup
  316. │ └── mcp_configurator.py # Auto-configure MCP entries for detected platforms
  317. ├── data/
  318. │ └── platform_profiles.yaml # Platform capability definitions — edit to add/update platforms
  319. └── tests/
  320. ├── test_scanner.py
  321. ├── test_mcp_server.py
  322. ├── test_ai_engine.py
  323. └── test_cli.py
  324. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.