@gobing-ai/superskill 0.1.7 → 0.2.0

package/templates/skill/pattern.md

@@ -0,0 +1,95 @@
+---
+name: <!-- NAME -->
+description: <!-- DESCRIPTION -->
+license: Apache-2.0
+metadata:
+  author: "[author]"
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+---
+
+# <!-- NAME -->
+
+<!-- DESCRIPTION -->
+
+## Overview
+
+This skill teaches a design pattern for solving a recurring class of problems. It provides decision criteria, core principles, and trade-off analysis — not a step-by-step procedure.
+
+## When to use this pattern
+
+Use this pattern when you need to:
+
+- Make an architectural or design decision between competing approaches
+- Evaluate trade-offs along multiple dimensions (complexity, scalability, blast radius)
+- Apply a proven mental model to a new problem that fits the pattern shape
+- Cross-check a proposed solution against known anti-patterns
+- Document the reasoning behind a design choice for future reference
+
+## When NOT to use this pattern
+
+Avoid this pattern when:
+
+- A single obvious solution exists — applying a decision framework adds overhead
+- The problem is unique enough that no proven pattern applies
+
+## Core principles
+
+### Principle 1: Favor simplicity
+
+Prefer the simplest solution that meets the requirements. Never add abstraction for a single use case — three similar lines beat a premature abstraction.
+
+### Principle 2: Verify before asserting
+
+Every claim about behavior, performance, or compatibility must be grounded in evidence. Cite the source — docs, tests, or command output.
+
+### Principle 3: Match conventions
+
+Conformance beats personal taste inside an existing codebase. If a convention seems actively harmful, surface it as a question — do not silently diverge.
+
+## Implementation guide
+
+### Step 1: Identify the problem shape
+
+Confirm the problem matches this pattern's trigger conditions. If it doesn't, consider an alternative pattern.
+
+### Step 2: Evaluate trade-offs
+
+Assess the approach against the dimensions below. Document the reasoning.
+
+### Step 3: Validate the decision
+
+Cross-check the decision against project conventions, existing patterns, and acceptance criteria. Cite evidence.
+
+## Trade-offs
+
+| Aspect | Pros | Cons |
+|--------|------|------|
+| Simplicity | Easy to understand and maintain | May not cover edge cases |
+| Flexibility | Adapts to varying requirements | Adds complexity when over-applied |
+| Consistency | Aligns with proven practice | May not fit novel problems |
+
+## Behavior
+
+This skill acts as a **pattern**: a decision framework and mental model. When invoked, it guides the agent through evaluating trade-offs and selecting an approach — it does not execute code directly.
+
+## Gotchas
+
+1. **Don't apply blindly**: Always verify the problem matches the pattern's trigger conditions before applying it. Forcing a pattern onto a mismatched problem creates unnecessary complexity.
+2. **Don't skip trade-off analysis**: The value of a pattern is in the explicit trade-off evaluation. Skipping straight to a solution loses the reasoning that makes the pattern reusable.
+3. **Don't ignore conventions**: A pattern that contradicts project conventions must be surfaced, not silently applied. Conformance beats theoretical purity.
+
+## Platform Notes
+
+### Claude Code
+
+Use `$ARGUMENTS` for parameter references. Use `Skill()` for skill delegation.
+
+### Codex / OpenClaw / OpenCode / Antigravity
+
+Run commands via Bash tool. Arguments provided in chat.
+
+---
+
+**Template type**: pattern
+**Purpose**: Decision frameworks and mental models for design decisions

package/templates/skill/reference.md

@@ -0,0 +1,102 @@
+---
+name: <!-- NAME -->
+description: <!-- DESCRIPTION -->
+license: Apache-2.0
+metadata:
+  author: "[author]"
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+---
+
+# <!-- NAME -->
+
+<!-- DESCRIPTION -->
+
+## Overview
+
+This skill provides a reference lookup for API details, configuration keys, command flags, and technical specifications. Use it to verify facts before generating code or making claims.
+
+## When to use
+
+Use this skill when you need to:
+
+- Look up an API signature, flag, or configuration key before using it
+- Verify version-specific behavior of a library or tool
+- Cross-check a claim against authoritative documentation
+- Find the correct syntax for a command or configuration
+- Validate that a field, option, or path exists before referencing it
+
+## Quick reference
+
+| Category | Item | Description |
+|----------|------|-------------|
+| Commands | `scaffold <name>` | Create new content from a template |
+| Commands | `evaluate <name>` | Score content quality (0.0–1.0) |
+| Commands | `validate <name>` | Structural + schema validation |
+| Flags | `--template <tier>` | Select a template tier |
+| Flags | `--target <agent>` | Target agent platform |
+| Flags | `--force` | Overwrite existing files |
+| Flags | `--json` | Machine-readable output |
+
+## Detailed reference
+
+### Commands
+
+#### scaffold
+
+Creates a new content file from a resolved template. For the skill type, writes `<name>/SKILL.md` inside a directory; all other types write flat `<name>.md`.
+
+```bash
+superskill skill scaffold my-skill --description "A test skill"
+```
+
+#### evaluate
+
+Scores content quality across 5 dimensions: completeness, clarity, trigger-accuracy, anti-hallucination, and conciseness. Returns an aggregate score (0.0–1.0) with per-dimension findings.
+
+```bash
+superskill skill evaluate my-skill
+```
+
+#### validate
+
+Structural and schema validation. Checks frontmatter fields, body structure, link integrity, and format compliance. Use `--strict` for all optional checks.
+
+```bash
+superskill skill validate my-skill --strict
+```
+
+### Template tiers
+
+| Tier | Purpose | Body shape |
+|------|---------|------------|
+| `technique` | Step-by-step workflows | Workflow + steps + verification |
+| `pattern` | Decision frameworks | Trade-offs + principles + when-to-use |
+| `reference` | Lookup tables | Quick-reference + detailed docs |
+
+A freshly scaffolded skill PASSes the project's own evaluator out of the box.
+
+## Behavior
+
+This skill acts as a **reference**: a lookup table and documentation source. When invoked, it provides authoritative information — it does not execute workflows or make decisions. Always cite this reference when answering factual questions about the system.
+
+## Gotchas
+
+1. **Don't guess API behavior**: Always verify against this reference before claiming how a command or flag behaves. Version-specific behavior must be cited with the version.
+2. **Don't confuse template tiers**: Each tier produces a different body structure. Choose the tier that matches the skill's purpose — technique for workflows, pattern for decisions, reference for lookups.
+3. **Don't skip the quick-reference table**: The table is the fastest path to an answer. If the item isn't in the table, check the detailed reference section before concluding it doesn't exist.
+
+## Platform Notes
+
+### Claude Code
+
+Use `$ARGUMENTS` for parameter references. Use `Skill()` for skill delegation.
+
+### Codex / OpenClaw / OpenCode / Antigravity
+
+Run commands via Bash tool. Arguments provided in chat.
+
+---
+
+**Template type**: reference
+**Purpose**: Lookup tables and documentation for quick factual reference

package/templates/skill/technique.md

@@ -0,0 +1,107 @@
+---
+name: <!-- NAME -->
+description: <!-- DESCRIPTION -->
+license: Apache-2.0
+metadata:
+  author: "[author]"
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+---
+
+# <!-- NAME -->
+
+<!-- DESCRIPTION -->
+
+## When to use
+
+Use this skill when you need to:
+
+- Execute a multi-step workflow that must produce a verified, reproducible output
+- Apply a project-specific procedure that should never be re-derived from scratch
+- Validate work against acceptance criteria before reporting completion
+- Cross-check intermediate results against authoritative documentation
+- Ensure deterministic steps across sessions, agents, and CI runs
+
+## Workflow
+
+Follow these steps to complete the workflow. Each step must be verified before proceeding to the next.
+
+### Step 1: Gather context
+
+Read the relevant files, configuration, and reference material. Never assume structure — verify paths exist before acting.
+
+```bash
+# Example: inspect the target before modifying
+ls -la <target>
+```
+
+### Step 2: Plan the change
+
+Identify the files to read and modify, dependencies, and edge cases. State assumptions explicitly.
+
+### Step 3: Execute the change
+
+Apply the change with surgical precision. Touch only what the task requires — no drive-by refactors.
+
+### Step 4: Verify the result
+
+Validate the output against the acceptance criteria. Cite the evidence (test output, command result, or document reference) before reporting done.
+
+## Behavior
+
+This skill acts as a **technique**: a step-by-step workflow with concrete instructions. When invoked, it executes the workflow end-to-end, verifying each step before proceeding.
+
+**Key invariants:**
+
+- Always verify before claiming completion — never report done without evidence
+- Cite sources for any external claim or API behavior
+- Validate inputs at system boundaries; trust internal code
+
+## Code Examples
+
+### Basic Usage
+
+```bash
+# Example command showing basic usage
+superskill <!-- NAME --> <target>
+```
+
+### Advanced Usage
+
+```bash
+# Example command with options
+superskill <!-- NAME --> <target> --strict --json
+```
+
+## Gotchas
+
+1. **Don't skip verification**: Reporting done without running the verification step is the most common failure mode. Always cite the test or command output.
+2. **Don't assume file structure**: Verify paths exist before reading or writing. A missing file is a blocking error, not a silent skip.
+3. **Don't drift from conventions**: Match existing project patterns. If a convention seems wrong, surface it — do not silently fork the style.
+
+## Resources (optional)
+
+Create only the resource directories this skill actually needs.
+
+### scripts/
+
+Executable code (TypeScript/Bash) for tasks that require deterministic reliability.
+
+### references/
+
+Documentation intended to be loaded into context as needed.
+
+## Platform Notes
+
+### Claude Code
+
+Use `$ARGUMENTS` for parameter references. Use `Skill()` for skill delegation.
+
+### Codex / OpenClaw / OpenCode / Antigravity
+
+Run commands via Bash tool. Arguments provided in chat.
+
+---
+
+**Template type**: technique
+**Purpose**: Step-by-step workflows with concrete instructions and verification gates

package/templates/hook/default.md

@@ -1,8 +0,0 @@
----
-name: <!-- NAME -->
-description: <!-- DESCRIPTION -->
-event: PreToolUse
-enabled: true
----
-
-<!-- TODO: hook script or matcher -->