菜单
Surface doc-drift gate: scaffold surf.toml + hubs, wire the SHA-pinned pre-commit/Action. Use when adding a docs-governed-like-code CI gate.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/laurigates/claude-plugins --skill configure-surface命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Install, configure and troubleshoot MCP servers. Use when adding/enabling servers, editing .mcp.json, fixing OAuth, or when a server runs stale code after an upstream fix.
FinOps snapshot — org billing, workflow stats, cache usage. Use when you want a high-level view of CI spending or workflow health before diving deeper.
GitHub Actions billing, workflow efficiency, and waste analysis at org or repo level. Use when investigating CI/CD costs, wasted runs, or optimizing triggers.
正在显示 SKILL.md
基于 SOC 职业分类
| created | "2026-06-14T00:00:00.000Z" |
| modified | "2026-07-28T00:00:00.000Z" |
| reviewed | "2026-07-28T00:00:00.000Z" |
| description | Surface doc-drift gate: scaffold surf.toml + hubs, wire the SHA-pinned pre-commit/Action. Use when adding a docs-governed-like-code CI gate. |
| allowed-tools | Glob, Grep, Read, Write, Edit, Bash, AskUserQuestion, TodoWrite, WebFetch |
| args | [--check-only] [--fix] [--pin <tag>] |
| argument-hint | [--check-only] [--fix] [--pin v0.8.0] |
| name | configure-surface |
| language | rust |
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.
| 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) |
find . -maxdepth 2 -name 'surf.toml'find . -maxdepth 2 -type d -name 'hubs'find . -maxdepth 1 -name '.pre-commit-config.yaml'find . -path '*/.github/workflows/*' -maxdepth 3 -name '*.yml'find . -maxdepth 1 \( -name 'Cargo.toml' -o -name 'package.json' -o -name 'pyproject.toml' -o -name 'go.mod' \)Parse from $ARGUMENTS:
--check-only: Report Surface adoption status and pin hygiene; make no changes (CI mode).--fix--pin <tag>: Release tag to install/pin (default: latest stable; resolve its commit SHA before writing any uses: ref).Execute this Surface configuration workflow:
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.
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.
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:
git ls-remote https://github.com/Connorrmcd6/surface refs/tags/<tag>
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.
surf.toml:
hubs = ["hubs/*.md"]
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.
surf lint (every anchor resolves to exactly one symbol), then surf verify to seal hashes.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/surface
rev: 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-latest
steps:
- uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
- uses: Connorrmcd6/surface@091b937ae34ac81a02386604fed977dd24f1f0cf # v0.8.0
with:
version: v0.8.0 # pins the BINARY; the input defaults to floating `latest`
args: check
Two pins, not one. The
@<sha> # vX.Y.Zref pins the composite action and its bundledinstall.sh;version:pins the binary that installer downloads. Omit it andaction.yml's own default (latest) resolvesreleases/latestover 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 updateversion:to match in the same PR.The historical installer-pin gap (
action.ymlpipinginstall.shfrom mutablemain) is fixed and shipped — v0.8.0 runssh "${{ github.action_path }}/install.sh". Pinning v0.6.2 or earlier still carries that gap; vendorinstall.shat that ref if you must stay there.
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.
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 ✓/✗.
| 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 |
| Fallback | macOS Intel / Windows unsupported — document cargo install --git source fallback |
| Context | Command |
|---|---|
| Status + pin audit | /configure:surface --check-only |
| Scaffold + harden | /configure:surface --fix --pin v0.8.0 |
| The gate (CI) | surf check |
| Scope to changed files | surf check --base origin/main |
| Machine-readable verdict | surf check --format json |
| Re-seal after human review | surf verify |
| Anchors resolve | surf lint |
| Flag | Description |
|---|---|
--check-only | 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) |
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.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./configure:web-session — install surf in Claude Code web sessions/configure:pre-commit — pre-commit framework setup this plugs intoblueprint:blueprint-docs-currency — same-commit doc discipline (the convention-level complement)blueprint:blueprint-sync — drift detection for generated contentcode-quality:code-review — the semantic reviewer for Surface's JSON verdicts