From 90a58f0b9ec158dce8e0b07a5a510327ed3d0b72 Mon Sep 17 00:00:00 2001 From: Mathias Date: Sat, 29 Aug 2026 10:09:52 +0200 Subject: [PATCH] feat(skills): declare which surfaces each skill ships to MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The repo distributes three ways — the Claude Code plugin, the symlinked library for Crush/Pi/OpenCode, and claude.ai, which has no fetch path at all — and treated every skill as belonging to all of them. claude.ai is not a fourth host to mirror: gitea-ci, playwright and web-shot have no shell and no cluster there, so a flat mirror installs skills that can never fire and degrades selection for the ones that can. Every SKILL.md now carries `surfaces:`, defaulting to [claude-code, library]; dream, own-the-task and grill-me add `chat`, matching what is actually installed on claude.ai today. Claude Code accepts the extra key — `claude plugin validate` passes and the skills still load. bin/check-surfaces validates values, not just presence, because the failure mode here is silent: a wrong surface removes a skill from a harness rather than erroring. install.sh links only skills whose surfaces include `library`, and a source that declares nothing at all is treated as foreign and linked as-is — Anthropic's official set has no reason to know this convention. doctor's missing-link check skips non-library skills for the same reason. Refs #29 Bump-Type: minor --- Taskfile.yml | 7 +- bin/check-surfaces | 49 ++++++++++++++ bin/doctor | 7 ++ install.sh | 11 ++++ skills/atdd/SKILL.md | 1 + skills/cad-babysit/SKILL.md | 1 + skills/clean-code/SKILL.md | 1 + skills/code-review/SKILL.md | 1 + skills/cognitive-load/SKILL.md | 1 + skills/debug/SKILL.md | 1 + skills/discovery-framing/SKILL.md | 1 + skills/dream/SKILL.md | 1 + skills/experiment-spec/SKILL.md | 1 + skills/feature-spec/SKILL.md | 1 + skills/gitea-ci/SKILL.md | 1 + skills/grill-me/SKILL.md | 1 + skills/own-the-task/SKILL.md | 1 + skills/planning/SKILL.md | 1 + skills/playwright/SKILL.md | 1 + skills/problem-analysis/SKILL.md | 1 + skills/refactoring/SKILL.md | 1 + skills/regulatory-risk-assessment/SKILL.md | 1 + skills/secret-hygiene/SKILL.md | 1 + skills/session-retrospective/SKILL.md | 1 + skills/solid/SKILL.md | 1 + skills/spec-driven-dev/SKILL.md | 1 + skills/stage-gate-review/SKILL.md | 1 + skills/superpowers-brainstorming/SKILL.md | 1 + .../SKILL.md | 1 + skills/superpowers-executing-plans/SKILL.md | 1 + .../SKILL.md | 1 + .../SKILL.md | 1 + .../SKILL.md | 1 + .../SKILL.md | 1 + .../superpowers-systematic-debugging/SKILL.md | 1 + .../superpowers-using-git-worktrees/SKILL.md | 1 + skills/superpowers-using-superpowers/SKILL.md | 1 + .../SKILL.md | 1 + skills/superpowers-writing-plans/SKILL.md | 1 + skills/superpowers-writing-skills/SKILL.md | 1 + skills/tdd/SKILL.md | 1 + skills/telos-load/SKILL.md | 1 + skills/test-design/SKILL.md | 1 + skills/trainer/SKILL.md | 1 + skills/user-stories/SKILL.md | 1 + skills/web-shot/SKILL.md | 1 + tests/check_surfaces_test.sh | 65 +++++++++++++++++++ tests/doctor_test.sh | 7 ++ tests/install_test.sh | 27 ++++++++ 49 files changed, 214 insertions(+), 1 deletion(-) create mode 100755 bin/check-surfaces create mode 100644 tests/check_surfaces_test.sh diff --git a/Taskfile.yml b/Taskfile.yml index 3d4a879..a8676e4 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -99,7 +99,12 @@ tasks: # tests/check_index_test.sh rather than living untested here. sh '{{.TASKFILE_DIR}}/bin/check-index' '{{.TASKFILE_DIR}}' || fail=1 - # 4. Plugin manifest version must match the latest tag, or installers + # 4. Every skill says which surfaces it ships to, and names only + # surfaces that exist — a wrong value silently drops a skill from a + # harness instead of erroring. + sh '{{.TASKFILE_DIR}}/bin/check-surfaces' '{{.TASKFILE_DIR}}' || fail=1 + + # 5. Plugin manifest version must match the latest tag, or installers # never see the update (Claude Code gates updates on this field). if [ -f '{{.PLUGIN_MANIFEST}}' ]; then manifest_v=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' '{{.PLUGIN_MANIFEST}}' | head -1) diff --git a/bin/check-surfaces b/bin/check-surfaces new file mode 100755 index 0000000..6d4df89 --- /dev/null +++ b/bin/check-surfaces @@ -0,0 +1,49 @@ +#!/bin/sh +# check-surfaces — every skill declares which surfaces it ships to, and only +# names surfaces that exist. +# +# The repo distributes three ways: the Claude Code plugin, the symlinked +# library (Crush/Pi/OpenCode), and claude.ai, which has no fetch path at all. +# Treating every skill as belonging to all three installs skills that can never +# fire — gitea-ci, playwright and web-shot have no shell or cluster in a chat +# surface — and degrades selection for the ones that can (#29). +# +# Values are validated, not merely counted: a wrong surface silently removes a +# skill from a harness rather than erroring, which is the failure mode this +# whole file exists to prevent. +# +# Usage: check-surfaces [checkout-root] + +set -u + +ROOT=${1:-$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)} +ALLOWED='claude-code library chat' +fail=0 + +for dir in "$ROOT"/skills/*/; do + [ -f "$dir/SKILL.md" ] || continue + name=$(basename "$dir") + + line=$(sed -n 's/^surfaces:[[:space:]]*//p' "$dir/SKILL.md" | head -1) + if [ -z "$line" ]; then + echo "ERROR: skills/$name declares no 'surfaces:' — say where it ships (${ALLOWED% *}, ${ALLOWED##* })" >&2 + fail=1 + continue + fi + + values=$(printf '%s' "$line" | tr -d '[]' | tr ',' ' ') + count=0 + for v in $values; do + count=$((count + 1)) + case " $ALLOWED " in + *" $v "*) ;; + *) echo "ERROR: skills/$name names surface '$v', which does not exist — allowed: $ALLOWED" >&2; fail=1 ;; + esac + done + [ "$count" -gt 0 ] || { + echo "ERROR: skills/$name has an empty 'surfaces:' list — a skill that ships nowhere should be deleted, not declared" >&2 + fail=1 + } +done + +exit $fail diff --git a/bin/doctor b/bin/doctor index 55b7221..7adbe2e 100755 --- a/bin/doctor +++ b/bin/doctor @@ -153,6 +153,13 @@ elif [ -d "$AGENTS_DIR" ]; then for dir in "$SKILLS_DIR"/*/; do [ -f "$dir/SKILL.md" ] || continue name=$(basename "$dir") + # Only skills that ship to the library belong here. A chat-only skill + # missing from a Crush directory is correct, not drift (#29). + surfaces=$(sed -n 's/^surfaces:[[:space:]]*//p' "$dir/SKILL.md" | head -1) + if [ -n "$surfaces" ] \ + && ! printf '%s' "$surfaces" | tr -d '[]' | tr ',' ' ' | grep -qw library; then + continue + fi [ -L "$AGENTS_DIR/$name" ] \ || add FAIL missing "$name is in the checkout but has no link in $AGENTS_DIR — re-run install.sh" done diff --git a/install.sh b/install.sh index bfbd1cd..d49e304 100755 --- a/install.sh +++ b/install.sh @@ -131,6 +131,17 @@ wire_skills() { name="$(basename "$dir")" target="${dir%/}" + # A skill declares its surfaces; this installer serves exactly one of + # them. A chat-only skill linked into Crush can never fire and competes + # for selection with ones that can (#29). A source with no declaration + # is foreign — Anthropic's official set has no reason to know this + # convention — so silence means "link it". + surfaces="$(sed -n 's/^surfaces:[[:space:]]*//p' "$dir/SKILL.md" | head -1)" + if [ -n "$surfaces" ] && ! printf '%s' "$surfaces" | tr -d '[]' | tr ',' ' ' | grep -qw library; then + log "skipping $name — surfaces: $surfaces does not include the library" + continue + fi + if printf '%s' "$desired" | grep -qx -- "$name"; then log "COLLISION: $name is offered by $target too; keeping $AGENTS_DIR/$name -> $(readlink "$AGENTS_DIR/$name" 2>/dev/null || echo '?')" continue diff --git a/skills/atdd/SKILL.md b/skills/atdd/SKILL.md index 20dcb7c..82f6b3a 100644 --- a/skills/atdd/SKILL.md +++ b/skills/atdd/SKILL.md @@ -1,5 +1,6 @@ --- name: atdd +surfaces: [claude-code, library] description: Implement user stories using the ATDD workflow — Red (failing acceptance test) → Green (minimal implementation) → Refactor. One story at a time. --- diff --git a/skills/cad-babysit/SKILL.md b/skills/cad-babysit/SKILL.md index 82d365e..2e92d87 100644 --- a/skills/cad-babysit/SKILL.md +++ b/skills/cad-babysit/SKILL.md @@ -1,5 +1,6 @@ --- name: cad-babysit +surfaces: [claude-code, library] description: Focused human-in-the-loop session working CAD's stuck queue (cad-stuck output). Read-only — diagnoses, never dispatches, arms a label, or closes an issue. Use when picking up whatever CAD has run into trouble on, with a human present. --- diff --git a/skills/clean-code/SKILL.md b/skills/clean-code/SKILL.md index f6acbd1..f43c472 100644 --- a/skills/clean-code/SKILL.md +++ b/skills/clean-code/SKILL.md @@ -1,5 +1,6 @@ --- name: clean-code +surfaces: [claude-code, library] description: Write code that humans can read, understand, and safely change. Apply SOLID, GRASP, and Clean Code principles during the REFACTOR phase of TDD. --- diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 9dfe1e3..2b2893d 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -1,5 +1,6 @@ --- name: code-review +surfaces: [claude-code, library] description: Systematic code smell detection and Go-specific review checklist. Load before any pre-merge review. --- diff --git a/skills/cognitive-load/SKILL.md b/skills/cognitive-load/SKILL.md index cfedbe1..b7776d3 100644 --- a/skills/cognitive-load/SKILL.md +++ b/skills/cognitive-load/SKILL.md @@ -1,5 +1,6 @@ --- name: cognitive-load +surfaces: [claude-code, library] description: Measure how much mental effort a codebase demands from developers. Use when identifying hotspots, before architectural decisions, or when code feels hard to understand. --- diff --git a/skills/debug/SKILL.md b/skills/debug/SKILL.md index 45a8a31..fb295fd 100644 --- a/skills/debug/SKILL.md +++ b/skills/debug/SKILL.md @@ -1,5 +1,6 @@ --- name: debug +surfaces: [claude-code, library] description: Systematic hypothesis-first debugging. Generate 3-5 ranked hypotheses with verification steps before suggesting any fix. Use when encountering a bug, test failure, or unexpected behavior. --- diff --git a/skills/discovery-framing/SKILL.md b/skills/discovery-framing/SKILL.md index 8c9d171..194cbbb 100644 --- a/skills/discovery-framing/SKILL.md +++ b/skills/discovery-framing/SKILL.md @@ -1,5 +1,6 @@ --- name: discovery-framing +surfaces: [claude-code, library] description: Run the discovery / framing phase of product innovation — define and quantify a focused customer problem BEFORE any solution exists. Four movements: understand the problem space, learn about customers, identify and size problems, decide pursue/table/kill. Produces a problem brief per prioritized opportunity. Use when an idea is still vague, when someone is jumping to solutions before the problem is validated, when scoping early research, or when deciding which problems are worth pursuing. Trigger phrases include "frame the problem", "discovery", "problem statement", "is this worth building", "early research", "opportunity sizing", "we have an idea for", "how might we", "what problem are we solving". --- diff --git a/skills/dream/SKILL.md b/skills/dream/SKILL.md index b1f0545..1c3c253 100644 --- a/skills/dream/SKILL.md +++ b/skills/dream/SKILL.md @@ -1,5 +1,6 @@ --- name: dream +surfaces: [claude-code, library, chat] description: > Run a "dream" — a reflective memory consolidation pass over an agent's memory directory. Use this skill whenever the user says "dream", "run a dream", "consolidate diff --git a/skills/experiment-spec/SKILL.md b/skills/experiment-spec/SKILL.md index 96da443..07ab63f 100644 --- a/skills/experiment-spec/SKILL.md +++ b/skills/experiment-spec/SKILL.md @@ -1,5 +1,6 @@ --- name: experiment-spec +surfaces: [claude-code, library] description: Write a rigorous experiment spec for a research phase before any code or training runs. Use instead of feature-spec for scientific/ML research projects. Enforces falsifiable hypothesis, quantitative acceptance criteria, baseline comparison, and null-result protocol. --- diff --git a/skills/feature-spec/SKILL.md b/skills/feature-spec/SKILL.md index d775e84..71d93f7 100644 --- a/skills/feature-spec/SKILL.md +++ b/skills/feature-spec/SKILL.md @@ -1,5 +1,6 @@ --- name: feature-spec +surfaces: [claude-code, library] description: Write a tight implementation-level spec for a single feature or component before coding it. Use after a project-level spec exists (see spec-driven-dev) and you need to nail down one feature inside it. --- diff --git a/skills/gitea-ci/SKILL.md b/skills/gitea-ci/SKILL.md index ae5f0ac..32957b5 100644 --- a/skills/gitea-ci/SKILL.md +++ b/skills/gitea-ci/SKILL.md @@ -1,5 +1,6 @@ --- name: gitea-ci +surfaces: [claude-code, library] description: End-to-end Gitea CI/CD setup with self-hosted act_runner, quality gate pipeline, shared buildctl image-build script, k3s deploy, and GitHub mirror. Covers act_runner-specific gotchas that are not documented anywhere. --- diff --git a/skills/grill-me/SKILL.md b/skills/grill-me/SKILL.md index bd94fff..5c5aa16 100644 --- a/skills/grill-me/SKILL.md +++ b/skills/grill-me/SKILL.md @@ -1,5 +1,6 @@ --- name: grill-me +surfaces: [claude-code, library, chat] description: Critically interrogates plans, ideas, and proposals to make them sharper, more robust, and better grounded — with the explicit goal of producing a meaningfully better plan by the end. Use this skill whenever the user wants to stress-test a plan, prepare for hard questions, check if an idea is ready to act on, validate a hypothesis, or explicitly asks to be challenged, questioned, or grilled. Also trigger when a conversation has been exploring an idea for a while and it's time to converge — use this skill to check if the idea is actually ready. Trigger phrases include "grill me", "challenge this", "poke holes", "am I missing something", "is this ready", "stress-test this", "devil's advocate", "what am I not seeing". --- diff --git a/skills/own-the-task/SKILL.md b/skills/own-the-task/SKILL.md index fd398fb..3c0899b 100644 --- a/skills/own-the-task/SKILL.md +++ b/skills/own-the-task/SKILL.md @@ -1,5 +1,6 @@ --- name: own-the-task +surfaces: [claude-code, library, chat] description: Take ownership of a delegated task like a hired employee — interview first, write a handover brief, propose a plan, then execute. Use whenever the user says "take this off my plate", "own this", "act as my AI employee", "interview me first", "ask me questions before you start", or delegates anything open-ended where the real goal, the why, and the definition of done are not yet on the table. Trigger even when "interview" is never said — any delegation where getting the intent wrong would waste the whole effort belongs here. --- diff --git a/skills/planning/SKILL.md b/skills/planning/SKILL.md index 0bf2434..6198808 100644 --- a/skills/planning/SKILL.md +++ b/skills/planning/SKILL.md @@ -1,5 +1,6 @@ --- name: planning +surfaces: [claude-code, library] description: Decompose work into small, verifiable, ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable units. --- diff --git a/skills/playwright/SKILL.md b/skills/playwright/SKILL.md index 2f3cec4..ba65802 100644 --- a/skills/playwright/SKILL.md +++ b/skills/playwright/SKILL.md @@ -1,5 +1,6 @@ --- name: playwright +surfaces: [claude-code, library] description: Add and run Playwright E2E tests for any project with a web UI — covers setup, HTMX-specific patterns, SSE/streaming, Taskfile integration, and CI wiring. --- diff --git a/skills/problem-analysis/SKILL.md b/skills/problem-analysis/SKILL.md index 528ab93..781f61f 100644 --- a/skills/problem-analysis/SKILL.md +++ b/skills/problem-analysis/SKILL.md @@ -1,5 +1,6 @@ --- name: problem-analysis +surfaces: [claude-code, library] description: Deeply understand a problem before coding begins. Identify the real problem, stakeholders, constraints, and success criteria. Use before starting any non-trivial feature. --- diff --git a/skills/refactoring/SKILL.md b/skills/refactoring/SKILL.md index d618ec6..65a7736 100644 --- a/skills/refactoring/SKILL.md +++ b/skills/refactoring/SKILL.md @@ -1,5 +1,6 @@ --- name: refactoring +surfaces: [claude-code, library] description: Systematic refactoring methodology based on Martin Fowler's catalog. Apply during the REFACTOR phase of TDD, never while making code changes that modify behavior. --- diff --git a/skills/regulatory-risk-assessment/SKILL.md b/skills/regulatory-risk-assessment/SKILL.md index cf4f9d4..25fe6fe 100644 --- a/skills/regulatory-risk-assessment/SKILL.md +++ b/skills/regulatory-risk-assessment/SKILL.md @@ -1,5 +1,6 @@ --- name: regulatory-risk-assessment +surfaces: [claude-code, library] description: Produce a structured regulatory risk assessment / risk-register entry for regulated-industry features (banking, payments, PSD2/PSR, DORA, AML). Use when filing a CAD issue that needs a Risk:LOW/MEDIUM/HIGH level, or designing features touching payments, auth, data storage, or external APIs ("what are the risks?", "compliance gate", "risk register"). --- diff --git a/skills/secret-hygiene/SKILL.md b/skills/secret-hygiene/SKILL.md index d5849b8..c515782 100644 --- a/skills/secret-hygiene/SKILL.md +++ b/skills/secret-hygiene/SKILL.md @@ -1,5 +1,6 @@ --- name: secret-hygiene +surfaces: [claude-code, library] description: Prevent agent sessions from rendering credentials into the transcript, and recover safely when one leaks. Load BEFORE any command that touches credentials - kubectl exec/env/describe, kubectl get secret, whole-file SOPS decryption, token generation or rotation, envFrom inspection, or edits to encrypted config. Also load when a credential has already been exposed and a rotation chain is needed. Triggers - "rotate this token", "decrypt the config", "check the env var", "leaked credential", "did that print a secret", "why is this secret wrong". --- diff --git a/skills/session-retrospective/SKILL.md b/skills/session-retrospective/SKILL.md index e266ce2..dd20793 100644 --- a/skills/session-retrospective/SKILL.md +++ b/skills/session-retrospective/SKILL.md @@ -1,5 +1,6 @@ --- name: session-retrospective +surfaces: [claude-code, library] description: Review a completed coding session (from brain/sessions/*.jsonl) and surface non-obvious learnings worth preserving. Use after a session ends, before context is lost. --- diff --git a/skills/solid/SKILL.md b/skills/solid/SKILL.md index 331e7ec..93b9713 100644 --- a/skills/solid/SKILL.md +++ b/skills/solid/SKILL.md @@ -1,5 +1,6 @@ --- name: solid +surfaces: [claude-code, library] description: Apply SOLID design principles in Go. Use during architecture decisions, design reviews, and when adding new abstractions. --- diff --git a/skills/spec-driven-dev/SKILL.md b/skills/spec-driven-dev/SKILL.md index adc7c00..b9d1726 100644 --- a/skills/spec-driven-dev/SKILL.md +++ b/skills/spec-driven-dev/SKILL.md @@ -1,5 +1,6 @@ --- name: spec-driven-dev +surfaces: [claude-code, library] description: Write a structured specification before writing any code. Use when starting a new project, feature, or significant change. Adapted for a PM-first workflow where why comes before how. --- diff --git a/skills/stage-gate-review/SKILL.md b/skills/stage-gate-review/SKILL.md index d2f9514..21523e4 100644 --- a/skills/stage-gate-review/SKILL.md +++ b/skills/stage-gate-review/SKILL.md @@ -1,5 +1,6 @@ --- name: stage-gate-review +surfaces: [claude-code, library] description: Run or prepare a stage-gate product governance review — the go/no-go checkpoint where a council approves an initiative to advance through fixed innovation stages (Frame → Concept → Prototype → Validate → Scale), each gate guarded by a per-discipline readiness checklist. Use when preparing a Product Council / steering-group ask, building a go/no-go checklist, designing an innovation governance process, or auditing whether an initiative is genuinely ready to advance vs faking the gate. Trigger phrases include "stage gate", "product council", "go/no-go", "advance to the next stage", "is this ready to progress", "gate review", "phase gate", "innovation governance". --- diff --git a/skills/superpowers-brainstorming/SKILL.md b/skills/superpowers-brainstorming/SKILL.md index 06cd0a2..c989b1a 100644 --- a/skills/superpowers-brainstorming/SKILL.md +++ b/skills/superpowers-brainstorming/SKILL.md @@ -1,5 +1,6 @@ --- name: brainstorming +surfaces: [claude-code, library] description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation." --- diff --git a/skills/superpowers-dispatching-parallel-agents/SKILL.md b/skills/superpowers-dispatching-parallel-agents/SKILL.md index a6a3f5a..7fa5d00 100644 --- a/skills/superpowers-dispatching-parallel-agents/SKILL.md +++ b/skills/superpowers-dispatching-parallel-agents/SKILL.md @@ -1,5 +1,6 @@ --- name: dispatching-parallel-agents +surfaces: [claude-code, library] description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies --- diff --git a/skills/superpowers-executing-plans/SKILL.md b/skills/superpowers-executing-plans/SKILL.md index a591862..b996a1a 100644 --- a/skills/superpowers-executing-plans/SKILL.md +++ b/skills/superpowers-executing-plans/SKILL.md @@ -1,5 +1,6 @@ --- name: executing-plans +surfaces: [claude-code, library] description: Use when you have a written implementation plan to execute in a separate session with review checkpoints --- diff --git a/skills/superpowers-finishing-a-development-branch/SKILL.md b/skills/superpowers-finishing-a-development-branch/SKILL.md index 43da0ae..f1b7418 100644 --- a/skills/superpowers-finishing-a-development-branch/SKILL.md +++ b/skills/superpowers-finishing-a-development-branch/SKILL.md @@ -1,5 +1,6 @@ --- name: finishing-a-development-branch +surfaces: [claude-code, library] description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup --- diff --git a/skills/superpowers-receiving-code-review/SKILL.md b/skills/superpowers-receiving-code-review/SKILL.md index 4ea72cd..b663e3d 100644 --- a/skills/superpowers-receiving-code-review/SKILL.md +++ b/skills/superpowers-receiving-code-review/SKILL.md @@ -1,5 +1,6 @@ --- name: receiving-code-review +surfaces: [claude-code, library] description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation --- diff --git a/skills/superpowers-requesting-code-review/SKILL.md b/skills/superpowers-requesting-code-review/SKILL.md index 34b8340..a252241 100644 --- a/skills/superpowers-requesting-code-review/SKILL.md +++ b/skills/superpowers-requesting-code-review/SKILL.md @@ -1,5 +1,6 @@ --- name: requesting-code-review +surfaces: [claude-code, library] description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements --- diff --git a/skills/superpowers-subagent-driven-development/SKILL.md b/skills/superpowers-subagent-driven-development/SKILL.md index ea7ac8f..0fd6421 100644 --- a/skills/superpowers-subagent-driven-development/SKILL.md +++ b/skills/superpowers-subagent-driven-development/SKILL.md @@ -1,5 +1,6 @@ --- name: subagent-driven-development +surfaces: [claude-code, library] description: Use when executing implementation plans with independent tasks in the current session --- diff --git a/skills/superpowers-systematic-debugging/SKILL.md b/skills/superpowers-systematic-debugging/SKILL.md index 111d2a9..8a9f524 100644 --- a/skills/superpowers-systematic-debugging/SKILL.md +++ b/skills/superpowers-systematic-debugging/SKILL.md @@ -1,5 +1,6 @@ --- name: systematic-debugging +surfaces: [claude-code, library] description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes --- diff --git a/skills/superpowers-using-git-worktrees/SKILL.md b/skills/superpowers-using-git-worktrees/SKILL.md index 134d371..81fe81d 100644 --- a/skills/superpowers-using-git-worktrees/SKILL.md +++ b/skills/superpowers-using-git-worktrees/SKILL.md @@ -1,5 +1,6 @@ --- name: using-git-worktrees +surfaces: [claude-code, library] description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback --- diff --git a/skills/superpowers-using-superpowers/SKILL.md b/skills/superpowers-using-superpowers/SKILL.md index c8a8570..1eaf070 100644 --- a/skills/superpowers-using-superpowers/SKILL.md +++ b/skills/superpowers-using-superpowers/SKILL.md @@ -1,5 +1,6 @@ --- name: using-superpowers +surfaces: [claude-code, library] description: Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions --- diff --git a/skills/superpowers-verification-before-completion/SKILL.md b/skills/superpowers-verification-before-completion/SKILL.md index 2f14076..c94424b 100644 --- a/skills/superpowers-verification-before-completion/SKILL.md +++ b/skills/superpowers-verification-before-completion/SKILL.md @@ -1,5 +1,6 @@ --- name: verification-before-completion +surfaces: [claude-code, library] description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always --- diff --git a/skills/superpowers-writing-plans/SKILL.md b/skills/superpowers-writing-plans/SKILL.md index 847412e..520201a 100644 --- a/skills/superpowers-writing-plans/SKILL.md +++ b/skills/superpowers-writing-plans/SKILL.md @@ -1,5 +1,6 @@ --- name: writing-plans +surfaces: [claude-code, library] description: Use when you have a spec or requirements for a multi-step task, before touching code --- diff --git a/skills/superpowers-writing-skills/SKILL.md b/skills/superpowers-writing-skills/SKILL.md index c3b73d8..e4e8782 100644 --- a/skills/superpowers-writing-skills/SKILL.md +++ b/skills/superpowers-writing-skills/SKILL.md @@ -1,5 +1,6 @@ --- name: writing-skills +surfaces: [claude-code, library] description: Use when creating new skills, editing existing skills, or verifying skills work before deployment --- diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md index 7e0f5a9..b6f9224 100644 --- a/skills/tdd/SKILL.md +++ b/skills/tdd/SKILL.md @@ -1,5 +1,6 @@ --- name: tdd +surfaces: [claude-code, library] description: Write failing tests first, then minimal code to pass. Non-negotiable for all new features and bug fixes. --- diff --git a/skills/telos-load/SKILL.md b/skills/telos-load/SKILL.md index 00787ec..ad91384 100644 --- a/skills/telos-load/SKILL.md +++ b/skills/telos-load/SKILL.md @@ -1,5 +1,6 @@ --- name: telos-load +surfaces: [claude-code, library] description: Load TELOS — the intention substrate (problems, goals, strategies, status) — into a session at start so every decision traces to a goal. Use when starting any koala session, before architectural decisions, or as the CAD pipeline entry point ("load TELOS", "what are we optimizing toward?"). --- diff --git a/skills/test-design/SKILL.md b/skills/test-design/SKILL.md index 7691f9d..d9190c5 100644 --- a/skills/test-design/SKILL.md +++ b/skills/test-design/SKILL.md @@ -1,5 +1,6 @@ --- name: test-design +surfaces: [claude-code, library] description: Evaluate test quality using Dave Farley's 8 Properties of Good Tests. Use when reviewing or writing tests to ensure they provide genuine verification. --- diff --git a/skills/trainer/SKILL.md b/skills/trainer/SKILL.md index f5a96f0..dc43e66 100644 --- a/skills/trainer/SKILL.md +++ b/skills/trainer/SKILL.md @@ -1,5 +1,6 @@ --- name: trainer +surfaces: [claude-code, library] description: Two-phase brain curation — scan session logs to score candidate learnings (READ), then write the ones that pass the quality gate as generalized knowledge entries (WRITE). Use periodically to keep the brain useful, not noisy. --- diff --git a/skills/user-stories/SKILL.md b/skills/user-stories/SKILL.md index a373f74..fe1854b 100644 --- a/skills/user-stories/SKILL.md +++ b/skills/user-stories/SKILL.md @@ -1,5 +1,6 @@ --- name: user-stories +surfaces: [claude-code, library] description: Decompose problems into thin, deliverable user stories using Elephant Carpaccio and INVEST criteria. Use after problem analysis, before planning and implementation. --- diff --git a/skills/web-shot/SKILL.md b/skills/web-shot/SKILL.md index cb4e68f..8487dbe 100644 --- a/skills/web-shot/SKILL.md +++ b/skills/web-shot/SKILL.md @@ -1,5 +1,6 @@ --- name: web-shot +surfaces: [claude-code, library] description: Screenshot any running web UI by spawning a one-shot Playwright Job on the koala k3s cluster. Auto-detects the calling host's Tailscale name so a dev server on flamingo:8099, iguana:3000 or koala:8181 just works. Use when the user asks for a screenshot, visual verification, "what does the UI look like", or any time chromium / firefox / a browser is requested but none is installed on the host. --- diff --git a/tests/check_surfaces_test.sh b/tests/check_surfaces_test.sh new file mode 100644 index 0000000..58e13f3 --- /dev/null +++ b/tests/check_surfaces_test.sh @@ -0,0 +1,65 @@ +#!/bin/sh +# Tests for bin/check-surfaces. +# +# The repo ships to three surfaces — the Claude Code plugin, the symlinked +# library (Crush/Pi/OpenCode) and claude.ai, which has no fetch path at all — +# and used to treat every skill as belonging to all of them. gitea-ci, +# playwright and web-shot cannot fire in a chat surface; a flat mirror installs +# skills that can never trigger and degrades selection for the ones that can +# (#29). +# +# The risk this gate exists for: a wrong `surfaces:` value silently removes a +# skill from a harness rather than erroring. So presence is not enough — values +# are validated against the allowed set. + +set -u + +ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd) +SUT="$ROOT/bin/check-surfaces" + +pass=0 +fail=0 +WORK=${TMPDIR:-/tmp}/check_surfaces_test.$$ + +if [ ! -f "$SUT" ]; then + printf 'FAIL: %s does not exist\n' "$SUT" + exit 1 +fi + +cleanup() { rm -rf "$WORK"; } +trap cleanup EXIT INT TERM + +# fixture — a checkout holding one skill. +fixture() { + _f="$WORK/$1" + mkdir -p "$_f/skills/alpha" + if [ -n "$2" ]; then + printf -- '---\nname: alpha\n%s\ndescription: a\n---\n' "$2" > "$_f/skills/alpha/SKILL.md" + else + printf -- '---\nname: alpha\ndescription: a\n---\n' > "$_f/skills/alpha/SKILL.md" + fi + printf '%s' "$_f" +} + +# expect