Skip to content

docs: teach only the KEEP surface in agent skills - #120

Draft
pewpewpotato wants to merge 1 commit into
mainfrom
cursor/skill-keep-surface-fa97
Draft

pewpewpotato wants to merge 1 commit into
mainfrom
cursor/skill-keep-surface-fa97

Conversation

@pewpewpotato

@pewpewpotato pewpewpotato commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Refs #115

Agent skills and operator how-tos in this repo now teach the post-cut KEEP surface only. Marketplace (autonomous-bits/spool-marketplace) is out of scope for this PR, so this does not close #115.

Inventory

Rewritten

Skills (current how-to no longer names Rack, .spl as source of truth, or deleted CLI/MCP verbs):

  • .agents/skills/spool/SKILL.md
  • .agents/skills/spool/references/working-changes.md (export was “one-shot or repeatable”; it is now lossy, once, then stop)
  • .agents/skills/spool/references/workspaces.md
  • .agents/skills/spool/references/cli-help.md
  • .agents/skills/spool/references/branches-and-history.md
  • .agents/skills/spool/references/maintenance.md
  • .agents/skills/spool/references/merges.md
  • .agents/skills/spool/references/schemas.md
  • .agents/skills/spool/references/batch-authoring.md
  • .agents/skills/spool-technical-implementation/SKILL.md

Operator guidance that still listed deleted verbs as something to know:

  • README.md
  • docs/context-bind.md
  • docs/architecture.md (deleted names point at internal/surface instead of a verb catalog)
  • docs/README.md
  • CONTRIBUTING.md
  • cmd/spl/AGENTS.md
  • internal/AGENTS.md
  • CHANGELOG.md (Unreleased note that skills teach KEEP only)

Deleted

None. No skill existed whose only purpose was Rack or .spl-as-SoT. Bind, query, mutate, merge, and prune skills still map to KEEP work, so they were rewritten in place.

Reviewed, already KEEP (no edit)

  • .agents/skills/spool/references/reading-graphs.md
  • .agents/skills/select-new-goal/SKILL.md
  • .agents/skills/spool-product/SKILL.md
  • .agents/skills/spool-architecture/SKILL.md
  • .agents/skills/spool-engineering-standards/SKILL.md
  • .agents/skills/spool-release/SKILL.md

Left in place on purpose

  • CHANGELOG.md historical sections, including the Unreleased stop-list. That list is the release record, and TestSunsetCopyClosesSoftDoor requires it.
  • docs/context-git-migration.md — the export escape-hatch doc. Its drop list matches tool output (packs, remote config skipped as Rack remotes, reflogs, merge leases, projections). It is not the day-to-day operating skill.
  • docs/graphcontract.md — library pack-contract disclaimer, not a CLI how-to.

What guidance teaches now

  • Bind: spl context init --remote
  • MCP: spl mcp and KEEP spl_* tools, including spl_mutate
  • Writes: one mutation batch → short-lived branch + pull request
  • Reads: query-context, search, search-expand, filter, resolve, graph
  • schema / validate, asset *, file-graph merge *, prune
  • Export: if a leftover .spl store remains, run context export / migrate-once once into the bound context git remote, then stop. Export is lossy; re-run is overwrite-at-own-risk.
  • History, diff, and pull-request review: stock git and GitHub on the context remote

cmd/spl/sunset_test.go walks .agents/skills and fails if a removed verb or Rack reappears as skill text. The required .spl escape-hatch sentence is allowed. spl_context_export is allowed; the removed tool id spl_context is not.

Verification

make check passed tidy, format, vet, staticcheck, golangci-lint, go test, and go test -race.

govulncheck (v1.1.4, vuln DB 2026-10-08) reports pre-existing standard-library findings in Go 1.26.6 (fixed in 1.26.9), including GO-2026-6617. Those calls are unchanged by this PR. Quality on main last passed on 2026-09-19, before that database update. This PR does not bump the toolchain.

Open in Web Open in Cursor 

Agent how-tos no longer list deleted CLI/MCP verbs or Rack as the way to
operate Spool. Leftover .spl export is a lossy one-shot into the bound
context remote, then stop. History and review stay on stock git and GitHub.

Refs #115

Co-authored-by: Werner Swart <werner@swart.io>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Cleanup: audit marketplace/skills so agents don’t learn deleted surface

2 participants