SuperSkill

Overview Schema Source Related Servers Discussions Admin

spec

Destructive

Create, list, track, approve, and freeze deterministic plan documents with a fixed skeleton; approval requires zero gaps, and freezing pins a content hash to enforce immutability.

Instructions

Manage deterministic plan specs. Actions: create, status, approve, freeze, list. Specs use a fixed skeleton (goal, non-goals, constraints, context, files, acceptance, risks, rollback). Approve requires zero gaps; freeze pins a content hash and makes the spec immutable.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "spec"
  }
}

Input Schema

Name	Required	Description
`goal`	No	What this work must achieve
`spec`	No	Spec reference for status/approve/freeze (NNN, NNN-slug, or path)
`risks`	No	Known risks
`title`	No	Spec title (required for create)
`action`	Yes	Spec action
`context`	No	Background context
`project`	No	Project slug (auto-detected if omitted)
`rollback`	No	How to undo this work
`non_goals`	No	Explicitly out of scope
`acceptance`	No	Acceptance criteria; each item needs a command or a manual reason
`constraints`	No	Hard constraints
`allowed_files`	No	Globs this work may touch
`workspace_path`	No	Absolute thread workspace directory; must map to this project. Omit only when the server cwd is the thread workspace.
`forbidden_files`	No	Globs this work must not touch

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.15.1Oct 15, 2026

addedInput schema / properties / acceptance / items / additionalProperties
```
Added value: +false
```

addedInput schema / properties / workspace_path

Added value: +{
+  "description": "Absolute thread workspace directory; must map to this project. Omit only when the server cwd is the thread workspace.",
+  "type": "string"
+}

Addedv0.13.0Oct 12, 2026

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description adds meaningful behavioral context beyond the destructiveHint annotation: approve requires zero gaps, freeze pins a content hash and makes the spec immutable. These are consequential state changes an agent needs to know. It doesn't explain which specific actions are destructive (annotations only say destructiveHint=true globally) or what status returns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences: purpose, action enumeration, and two critical behavioral rules. Front-loaded and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter tool with 100% schema coverage, the description targets the highest-value gaps: the action lifecycle and the invariants of approve/freeze. Missing is any guidance on the workspace_path fallback behavior or how 'gaps' are detected, but the core is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are fully documented in the schema. The description mentions the fixed skeleton (goal, non-goals, constraints, context, files, acceptance, risks, rollback), which loosely maps to some fields but doesn't add syntax or constraint detail beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Manage deterministic plan specs') and explicitly enumerates the five actions (create, status, approve, freeze, list), which maps directly to the action enum. No sibling tool in the list covers plan-spec lifecycle, so it's distinguishable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides action-specific rules ('Approve requires zero gaps', 'freeze pins a content hash and makes the spec immutable'), which implies the conditions for those actions. However, it doesn't say when to use spec vs. siblings like tickets, gate, or task, nor does it explain create-vs-list decision logic.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.