Taming Chaotic AI Agent Skills with skill-mcp: versioning, rollback, and orchestration

Core Idea: Skills as Packages

skill-mcp treats an AI skill as a software package. Each skill resides in a directory with the following layout:

my-skill/
├── manifest.json    # package metadata (name, version, entry)
├── SKILL.md        # main prompt content
├── references/      # supporting files
└── templates/      # template files

The manifest.json follows the npm package schema, e.g.:

{
  "name": "my-skill",
  "version": "0.0.1",
  "entry": "SKILL.md",
  "files": ["references/examples.md"]
}

Skill metadata (slug, version, category, tags, status, visibility, content hash) is stored in a SQLite table ( src/db/schema.ts), enabling version history, rollback, and deduplication via content hashes.

Version management is exposed through a CLI:

skill-mcp versions <slug>          # show version history
skill-mcp rollback <slug> --to 0.0.1  # rollback to a specific version

Three Deployment Modes (single codebase)

Scenario A – Local Standalone : communication via stdio, storage local, suited for individual developers.

Scenario B – Hybrid : local MCP communicates via stdio, remote shared storage accessed over HTTP with API‑key protection; ideal for multiple local clients sharing a skill library. Topology:

Claude IDE ↔ stdio ↔ MCP(local) ↔ HTTP+API Key ↔ storage service ↔ local FS + SQLite

.

Scenario C – Distributed : communication via HTTP/SSE, storage can be local or remote, intended for production, high‑concurrency, containerized deployments.

Environment variables ( DATABASE_PATH, STORAGE_BASE_PATH, CACHE_FILE_DIR) allow overriding default paths ( ~/.skill-mcp/).

Exposed MCP Tools

skill-mcp does not execute skills itself; it exposes five tools (source: src/mcp/tools/registry.ts) for AI clients: skill_list – list all published skills, optional tag filtering. skill_view – retrieve the full entry content of a skill (the SKILL.md file). skill_file – read arbitrary files inside a skill package (path array). skill_pipeline – execute a DAG‑style workflow of skills. skill_feedback – submit usage feedback for a skill.

Tech stack: @modelcontextprotocol/sdk ^1.12.1, better-sqlite3 + drizzle-orm, commander ^13, zod ^3.24, pino, prom-client, tests with vitest ^3. Requires Node.js >= 22.0.0.

Lightweight Pipeline Engine

The pipeline is a scheduler, not a full workflow engine. According to docs/ADVANCED/PIPELINE-ENGINE.md, it lets an AI agent invoke multiple skills in DAG order. It performs:

Topological sorting using Kahn’s algorithm ( src/dag.ts).

Parallel batch execution with Promise.allSettled; any stage failure aborts subsequent batches.

Example batch layout:

Batch 1: [read-pr]               → serial
Batch 2: [security-scan, style-check] → parallel
Batch 3: [generate-report]       → after Batch 2

Pipeline definitions use a YAML syntax inspired by GitHub Actions, supporting expressions such as ${{ inputs.xxx }}, ${{ stages.xxx.outputs }}, and ${{ stages.xxx.outputs.yyy }}. Sample stage:

stages:
  security-scan:
    skill: security-scanner
    depends_on: [read-pr]
    inputs:
      code: ${{ stages.read-pr.outputs.diff }}

Compared with heavyweight orchestrators (LangGraph, CrewAI, Airflow, Temporal), skill‑mcp targets the smaller problem space of AI skill management, keeping complexity low.

Security at Import Time

Import validation is performed in src/utils/security.ts with three safeguards:

Prompt‑injection scanning using regexes for patterns like ignore previous instructions or you are now a….

Path‑traversal protection via validateFilePath(), rejecting paths containing .. or absolute paths.

File‑type whitelist via isTextFile(), allowing only text formats (md, txt, json, yaml, ts, py, etc.).

Permissions are enforced by tag intersection: a skill with no tags is public; if a user’s role tags intersect the skill’s tags, access is granted; otherwise it is denied.

Honest Limitations and CLI Scope

Unimplemented features listed in the documentation include: condition and retry fields in pipeline YAML are defined but not functional.

Execution state is kept only in memory, not persisted.

No web UI; the CLI provides ASCII‑based visualizations.

The CLI ( src/cli/index.ts) covers the full skill lifecycle (import, list, info, search, update, remove, versions, rollback, lint), pipeline validation and graph generation, role management, service start, and release commands (patch/minor/major/alpha/beta/rc/dev).

Quality signals include bilingual README, extensive documentation sections (ARCHITECTURE, QUICK_START, SCENARIOS, API_REFERENCE, ADVANCED, TESTING_GUIDE, PUBLISHING, DEVELOPMENT, ORGANIZATION), CI pipeline ( ci.yml) with lint, type‑checking, tests, and coverage, and unit/integration/e2e test suites.

Project Maturity

skill‑mcp is an early‑stage project (version 0.1.0, first release 2026‑05‑06, few stars). Production‑grade usage is recommended to start with Scenario A (local) to validate the workflow before moving to hybrid or distributed deployments.

Conclusion

Since its open‑source release in November 2024, MCP has become a de‑facto standard for connecting AI applications to external systems. skill‑mcp leverages MCP’s Tools and system prompts to provide a self‑hosted solution for AI skill management, offering versioning, rollback, lightweight DAG scheduling, and import‑time security checks. It is positioned as a niche “skill management + lightweight scheduling” alternative to heavyweight orchestrators.

Source repository: https://github.com/BeCrafter/skill-mcp