Superskill module

Superskill is a repo-local module that turns skills + scenarios into:

• model settings (temperature mapping with model-family exceptions)
• output contracts (low narration, high signal)
• a strict agent-to-agent handoff packet (schema-validated)
• retry/convergence behavior that reduces roundtrips (policy + optional retry-plan CLI)
• trace + outcome logging and human-reviewed policy proposals (no automatic policy writes)

This folder is designed to be vendored into other repos or installed from npm. The package @nareshdama/superskill-policy-engine is published on the public npm registry.

| Where | Link | |-------|------| | GitHub | github.com/nareshdama/Superskill | | npm package | npmjs.com/package/@nareshdama/superskill-policy-engine |

Install from npm

npm i @nareshdama/superskill-policy-engine

(npm install @nareshdama/superskill-policy-engine is equivalent.)

Run the CLI without a global install:

npx @nareshdama/superskill-policy-engine --help
npx @nareshdama/superskill-policy-engine compile-prompt --provider openai --environment terminal --intent implement --scenario normal

Import the library (Node 18+):

import { /* see docs/PROGRAMMATIC_API.md */ } from "@nareshdama/superskill-policy-engine";

Community

| Resource | Purpose | |----------|---------| | CONTRIBUTING.md | Git workflow, dev setup, PR checklist | | Handbook.md | Developer handbook for fusing external cookbooks / OSS patterns into Superskill artifacts | | CHANGELOG.md | Versioned change log (SemVer; current: 1.0.0) | | CODE_OF_CONDUCT.md | Community standards (Contributor Covenant 2.1) | | SECURITY.md | How to report vulnerabilities privately | | Issues | Bugs and feature discussion |

Entry points

• Config: superskill.yaml (at repo root when using this package directly)
• Policies: policies/
• Schemas: schemas/ (handoff, trace line, outcome line, proposal file, …)
• Docs: docs/ — start with docs/CURRENT_DEVELOPMENT.md and docs/ROADMAP.md
• CLI: cli/src/index.mjs (see cli/README.md)

Current status (Phases 1–6 baseline)

Roadmap phases 1 through 6 are implemented at baseline:

• Phase 1–2: policy resolution and prompts; runner-facing validation (validate-output, validate-tool-args, retry-plan, runner-dry-run).
• Phase 3: handoff + trace (read-handoff, trace-append, trace-tail).
• Phase 4: outcomes and outcomes-report / proposal artifacts.
• Phase 5: tests, docs/PROGRAMMATIC_API.md, validate-proposal.
• Phase 6 (sandbox + approvals): declarative tool policy (policies/tool-policy.yaml) + runner capability profiles (policies/runner-capabilities.yaml); pre-call gate check-tool-call (exit 0/1/2 for auto/ask/deny); prompt blocks injected into compile-prompt; approval handoff block + request-approval / grant-approval workflow; canonical gate trace events feeding per-tool aggregates and tightening/loosening proposals.

The CLI does not call model APIs — runners own transport and keys. The gate is read-only; sandboxing is the runner's responsibility, and Superskill refuses to recommend plans that exceed the runner's declared capabilities.

Next steps and out-of-scope items are listed under Future development scope in docs/ROADMAP.md.

Docs (current set)

| Doc | Purpose | |-----|---------| | docs/CURRENT_DEVELOPMENT.md | What is implemented now (by phase). | | docs/ROADMAP.md | Snapshot, roadmap, future dev scope, completed milestones. | | docs/PHASE4_WORKFLOW.md | Log → report → proposal → PR. | | docs/HANDOFF_PROTOCOL.md | Handoff packet protocol. | | docs/TEMPERATURE_LAYER.md | Temperature layer. | | docs/POLICY_CHANGE_PLAYBOOK.md | Policy changes + resources/skills/. | | docs/PROGRAMMATIC_API.md | Embeds: lib/ exports. | | docs/PUBLISHING_NPM.md | npm publishing. | | docs/TOOL_GATE.md | Sandbox + approvals: check-tool-call, decideToolCall. |

Goals

• Fewer API calls by default (converge via policy, not rerolls)
• Less hallucination (verified pointers + schema gating)
• Maximum actionable output (structured work items)

npm (reference)

• Status: Published — install with npm i @nareshdama/superskill-policy-engine
• Registry: npmjs.com/package/@nareshdama/superskill-policy-engine
• Package name: @nareshdama/superskill-policy-engine
• Binary: superskill (via npx or after npm i / npm install)
• Develop in this repo: npm run smoke, npm test (from clone root)

Publishing workflow: docs/PUBLISHING_NPM.md.