Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
Scaffold and harden Surface — a deterministic
"documentation governed like code" gate. Surface anchors prose claims to code symbols, stores an
AST-normalized logic fingerprint per symbol, and blocks CI/commits when the fingerprint drifts
until a human re-runs surf verify. It ignores cosmetic edits and catches flipped operators,
relaxed comparisons, and dropped await.
⚠️ Experimental — adopt defensively. As of 2026-06 Surface is a young, single-maintainer
project (no crates.io publish, bus-factor 1). The engine and release hygiene vetted well, but
treat it as a pinned, optional gate — never an unpinned dependency. This skill defaults to
SHA-pinned installs and fail-closed checksum verification.
When to Use This Skill
Use this skill when...
Use another approach when...
Adding a deterministic doc↔code drift gate to CI/pre-commit
Enforcing same-commit doc discipline by convention (blueprint:blueprint-docs-currency)
You want specific prose claims pinned to specific functions
Detecting stale generated content (blueprint:blueprint-sync)
You want an offline, no-LLM gate that fails the build on logic drift
You want semantic "is the doc still true?" judgment (code-quality:code-review)
Hardening an existing Surface setup (pin by SHA, verify checksums)
Generating docs from code (documentation:docs-generate)
Context
surf.toml: !find . -maxdepth 2 -name 'surf.toml'
Hubs dir: !find . -maxdepth 2 -type d -name 'hubs'
--check-only: Report Surface adoption status and pin hygiene; make no changes (CI mode).
: Apply scaffolding and hardening without prompting.
--fix
--pin <tag>: Release tag to install/pin (default: latest stable; resolve its commit SHA before writing any uses: ref).
Execution
Execute this Surface configuration workflow:
Step 1: Detect current state
From Context, classify the repo:
Signal
Meaning
surf.toml present
Surface already initialised — go to hardening (Step 5)
Hubs dir present, no surf.toml
Partial setup — repair
Neither
Greenfield — full scaffold
Language marker
Surface supports Rust, TypeScript/JS (TSX grammar), Python, Go. Warn if none match — anchors only resolve in supported languages.
If --check-only, report the table and the pin audit from Step 5, then stop.
Step 2: Confirm the maturity trade-off
Before writing files, surface the experimental posture (the blockquote above) and confirm with
AskUserQuestion unless --fix is set: adopt as a pinned optional gate (recommended) or skip.
Record the chosen pin tag.
Step 3: Resolve the pinned ref
Resolve the chosen tag to the commit SHA it points at so every uses: and rev: is
reproducible — a release tag can be re-pointed to a different commit after the fact, so the SHA the
tag resolved to (with the tag kept in a trailing comment) is the real immutable anchor:
Land the Action ref as Connorrmcd6/surface@<sha> # <tag> and the pre-commit rev: as <tag>
(github-tags datasource — Renovate manages both; see .claude/rules/version-pinning.md). Do not
hand-transcribe a SHA from memory.
Carry the same tag into the Action step's version: input (Step 5) — the ref pins the action,
not the binary it installs.
Step 4: Scaffold (greenfield)
Create surf.toml:
hubs = ["hubs/*.md"]
Create hubs/ with one starter hub anchoring a real, stable symbol the team relies on. Hub shape:
---
summary: One-line description of what this hub governs.
anchors:
- claim: >
The prose claim about behaviour that must stay true.
at: src/path/file.ts > symbolName
hash: "" # surf verify seals this after you confirm the prose
refs: []
---
# Title
Longer explanation a reviewer reads when the gate flags drift.
Run surf lint (every anchor resolves to exactly one symbol), then surf verify to seal hashes.
Step 5: Wire + harden the gates
Pre-commit — add to .pre-commit-config.yaml (requires surf on PATH; pair with
/configure:web-session to install it in Claude Code web sessions):
-repo:https://github.com/Connorrmcd6/surfacerev:v0.8.0# --pin tag; Renovate-managed (github-tags)hooks:-id:surf-lint# anchors resolve-id:surf-check# the gate — blocks on drift
GitHub Action — scaffold .github/workflows/ with a SHA-pinned ref and an explicit
version::
name:"Docs: Surface drift gate"on: [pull_request]
jobs:surface:runs-on:ubuntu-lateststeps:-uses:actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8# v5.0.0-uses:Connorrmcd6/surface@091b937ae34ac81a02386604fed977dd24f1f0cf# v0.8.0with:version:v0.8.0# pins the BINARY; the input defaults to floating `latest`args:check
Two pins, not one. The @<sha> # vX.Y.Z ref pins the composite action and its bundled
install.sh; version: pins the binary that installer downloads. Omit it and action.yml's
own default (latest) resolves releases/latest over the API on every run — a new upstream
release then changes gate behaviour with no local change, landing as a red merge gate nobody can
attribute to an edit. Checksum verification does not close this: it proves the download matches
its own published hash, not that it is the version you pinned. Keep the two values equal;
Renovate bumps the ref, so update version: to match in the same PR.
The historical installer-pin gap (action.yml piping install.sh from mutable main) is fixed
and shipped — v0.8.0 runs sh "${{ github.action_path }}/install.sh". Pinning v0.6.2 or
earlier still carries that gap; vendor install.sh at that ref if you must stay there.
Step 6: Document the JSON → reviewer handoff
Surface keeps semantic judgment out of its deterministic core and emits JSON for reviewer plugins
(surf check --format json). Note in the repo (e.g. CONTRIBUTING or the workflow) that a drift
verdict can be handed to code-quality:code-review / verify to judge whether the claim is still
true before a human runs surf verify. That is the division of labour Surface is designed for and
where our skills add the most value.
Step 7: Report
Print: scaffold actions taken, the resolved pin (<sha> # <tag>), the version: input value, the
pre-commit + Action wiring status, and the hardening checklist below with each item ✓/✗.
Hardening checklist
Control
Target state
Action ref
SHA-pinned with # <tag> comment, not a floating major
Binary version
Pinned via version: <tag> in with:, not left at the floating latest default
Installer
Checksum-verified (default) or vendored at the pinned ref
Pin freshness
rev: / uses: Renovate-visible (github-tags shape)
Gate scope
surf check --base <ref> to diff-scope to changed files in CI
Report adoption + pin hygiene without modifying files
--fix
Apply scaffolding and hardening without prompting
--pin <tag>
Release tag to install/pin (resolved to a SHA before writing refs)
Upstream contributions
Installer pin — reported, merged, shipped: action.yml now runs the bundled
${{ github.action_path }}/install.sh, so a SHA-pinned uses: also pins the installer. Released;
the caveat in Step 5 applies only to v0.6.2 and earlier.
Floating version: default — reported, open (Connorrmcd6/surface#169):
proposes the default itself stop being latest, so the SHA pin becomes transitive. Independent of
the fix here — set version: explicitly regardless, since anyone pinning an older release needs it.
See Also
/configure:web-session — install surf in Claude Code web sessions
/configure:pre-commit — pre-commit framework setup this plugs into
blueprint:blueprint-docs-currency — same-commit doc discipline (the convention-level complement)
blueprint:blueprint-sync — drift detection for generated content
code-quality:code-review — the semantic reviewer for Surface's JSON verdicts
