@opvs-ai/skills

@opvs-ai/skills

Skill Factory for opvsHUB — generates typed OpenClaw gateway plugins from schema.yaml API definitions.

Install

# From the private OPVS registry
npm install @opvs-ai/skills --registry https://npm.opvs.ai

Usage

Generate plugins from schema.yaml files

# Generate a single skill
opvs-skills generate agentboard --skills-dir ./skills --plugins-dir ./plugins

# Generate all skills
opvs-skills generate --all --skills-dir ./skills --plugins-dir ./plugins

# Generate all + bundle for gateway deployment
opvs-skills generate --all \
  --skills-dir ./skills \
  --plugins-dir ./plugins \
  --bundle ./bundle/index.ts

# Generate all + MCP tool definitions
opvs-skills generate --all \
  --skills-dir ./skills \
  --plugins-dir ./plugins \
  --mcp ./mcp/generated-tools.ts

Validate schemas

opvs-skills validate --skills-dir ./skills

List skills with tier status

opvs-skills list --skills-dir ./skills

Emit runtime-native skill bundles (W2.3)

emit-runtime re-emits opvsHUB skills as runtime-native skill/rule bundles for non-OpenClaw agent runtimes. Each runtime has its own filesystem convention; the generator handles the path + frontmatter shape per runtime.

Runtime	Drop path inside --out	Frontmatter shape
claude-code	.claude/skills/<prefix>-<name>/SKILL.md	name, description (per Claude Code skills)
antigravity	.agent/skills/<prefix>-<name>/SKILL.md	name, description (per Antigravity skills codelab)
cursor	.cursor/rules/<prefix>-<name>.mdc	description, alwaysApply (per Cursor rules)
windsurf	.windsurf/rules/<prefix>-<name>.md (capped at 12,000 chars)	trigger, description (per Windsurf memories)

# Emit a single skill for Claude Code
opvs-skills emit-runtime claude-code \
  --skills-dir ./skills \
  --out ./opvs-runtime-bundle/claude \
  --skill vayapin

# Emit all skills for Cursor
opvs-skills emit-runtime cursor \
  --skills-dir ./skills \
  --out ./opvs-runtime-bundle/cursor

# Restrict to an allowlist
opvs-skills emit-runtime windsurf \
  --skills-dir ./skills \
  --out ./opvs-runtime-bundle/windsurf \
  --allowlist vayapin,agentboard,opvs-foundation

# Dry-run (print what would be written without touching disk)
opvs-skills emit-runtime antigravity \
  --skills-dir ./skills \
  --out /tmp/scratch \
  --dry-run

--prefix <prefix> controls the filename / directory prefix (default opvs). The user drops the contents of --out into a target project root to activate the skills.

End-to-end verification status (2026-05-15):

Runtime	Status
claude-code	Live-verified — fresh project + dropped bundle → claude --print discovers /opvs-vayapin, lists methods + env vars. Session log: tests/fixtures/e2e/claude-code-session.md
cursor	Verified via Claude-equivalent rule-injection simulation — rule body fed as system prompt yields a correct, contextual answer. Session log: tests/fixtures/e2e/cursor-session.md
windsurf	Format-level verified only — file lands at .windsurf/rules/, frontmatter parses, body kept under the 12k char cap. IDE-side activation untested (Windsurf is GUI-only).
antigravity	Format-level verified only — file lands at .agent/skills/<slug>/SKILL.md, frontmatter matches the docs. IDE-side activation untested.

What it generates

From a single schema.yaml:

Output	Purpose
{skill}.ts plugin	TypeScript plugin with api.registerTool() calls — native LLM tools
skills.yaml manifest	Tier 1 discovery index (one line per skill)
index.ts bundle	All plugins merged into one file for gateway deployment
generated-tools.ts	MCP tool definitions for the @opvs-ai/mcp server

schema.yaml format

name: my-skill
version: "1.0.0"
description: What this skill does
category: utility
base_url: /api/v1/my-service
auth:
  type: pat
  header: Authorization
  prefix: Bearer
  env_var: OPVS_PAT

methods:
  listItems:
    description: List all items
    http: GET /items
    params:
      status:
        type: enum
        values: [active, archived]
        required: false
    response:
      format: yaml

See the opvsHUB repo for all skill schemas and full documentation.

Programmatic API

import { generateFromSchema } from "@opvs-ai/skills";

const schemaYaml = fs.readFileSync("schema.yaml", "utf-8");
const result = generateFromSchema(schemaYaml);

// result.plugin   — TypeScript plugin code
// result.manifest — skills.yaml entry
// result.skillMd  — updated SKILL.md (if applicable)

OpenAPI ↔ schema.yaml drift detection (check / fix)

A.4 / A.6 in B1 Bundle 1 (2026-05-22) were both release-process bugs — agentboard_reorderColumns had a stale param shape and agentboard_updateColumn was missing from the published MCP entirely. Both were caused by schema.yaml drifting from the live FastAPI OpenAPI spec with nobody noticing until customer-facing tools 422'd.

opvs-skills check is the gate that prevents this from happening again. Point it at any FastAPI service's /openapi.json and it compares the live spec to your schema.yaml on a per-operation basis.

# Local smoke (boot the service first):
docker compose --profile queue up -d agentboard
sleep 20
opvs-skills check --skill agentboard --against http://localhost:8100/openapi.json
# Exit 1 on drift + structured report on stdout
# Exit 0 + "All schema methods match the live OpenAPI spec." when clean

# Against a checked-in OpenAPI export (no service boot needed):
opvs-skills check --skill agentboard --against ./openapi-agentboard.json

# JSON output for machine consumption:
opvs-skills check --skill agentboard --against http://localhost:8100/openapi.json --format json

# Skip known unbacked operations (e.g. routes intentionally not on the agent surface):
opvs-skills check --skill agentboard --against ... --ignore "GET /docs,GET /openapi.json"

The diff reports four drift classes per operation:

• schema_only_fields — schema declares a param the API doesn't accept (column_ids after the rename)
• api_only_fields — API requires a param the schema is missing (columns after the rename)
• required_mismatch — both sides know the field but disagree on required
• type_mismatch — both sides know the field but disagree on primitive type

Plus two operation-level diffs:

• schema_only_op — schema declares an http: route the API doesn't expose
• api_only_op — API exposes a route no schema method binds to (this is what would have caught updateColumn)

fix — emit a hand-apply checklist

opvs-skills fix --skill agentboard --against http://localhost:8100/openapi.json --out fix.md

fix deliberately does NOT mutate schema.yaml in place. Descriptions are hand-crafted and an automated rewrite risks stamping over them. The output is a markdown checklist with concrete per-field instructions you can copy into the YAML by hand.

CI gate

The .github/workflows/tests.yml workflow runs opvs-skills check against three core services on every PR (agentboard, agentdocs, agentmemory). A drift report blocks merge until either the schema or the API is updated. This is the gate that catches A.4/A.6-class regressions before they hit npm publish.

Requirements

• Node.js >= 18
• OpenClaw gateway for plugin deployment