spandrel-author

Category: Testing & Security | Uploader: trevorfox | Downloads: 0 | Version: v1.0（Latest）

Authoring discipline for Spandrel knowledge graphs — surfaces /patterns/authorship, /hypothesis, and the audit heuristics when editing graph content (nodes, descriptions, link descriptions). References canonical knowledge in the graph rather than hardcoding it. Auto-load when editing markdown with Spandrel frontmatter, or when authoring/auditing any Spandrel knowledge graph content.

Changelog: Source: GitHub https://github.com/trevorfox/spandrel

Directory Structure

Current level: tree/main/.claude/skills/spandrel-author/

📄 SKILL.md 4.2 KB

SKILL.md

---
name: spandrel-author
description: Authoring discipline for Spandrel knowledge graphs — surfaces /patterns/authorship, /hypothesis, and the audit heuristics when editing graph content (nodes, descriptions, link descriptions). References canonical knowledge in the graph rather than hardcoding it. Auto-load when editing markdown with Spandrel frontmatter, or when authoring/auditing any Spandrel knowledge graph content.
user-invocable: true
compatibility: Designed for Claude Code
metadata:
  version: "1.0"
---

# Spandrel Author

Authoring discipline for Spandrel knowledge graphs. This skill activates when you're writing or editing graph content — nodes, descriptions, link descriptions, companion files. It does not duplicate the principles; it points at the canonical home and lets you consult them on demand.

## When to activate

Use this skill when:

- Editing a markdown file with Spandrel frontmatter (`name:` and `description:` required, `links:` array optional)
- Creating a new node in a Spandrel graph (`foo.md` or `foo/index.md`)
- Authoring or revising a `description:` field, a `name:` field, or a per-edge `description:` in `links:`
- Auditing an existing graph for low-signal labels

If you're working *on* the Spandrel framework code itself (TypeScript in `src/`, compiler internals, wire surfaces), use `spandrel-builder` instead. This skill is for working *with* a Spandrel graph as an author.

## What to do

**Load the canonical knowledge before suggesting edits.** Ensure these are in context via MCP (`context()` or `get_content()`) when this skill activates:

- `/patterns/authorship` — the canonical home for the authoring discipline (names, descriptions, link descriptions; shared principles; good/bad examples)
- `/hypothesis` — the design target (conversational coherence; what to design for; what to design against)
- `/patterns/progressive-disclosure` — node-scale and path-scale gating
- `/patterns/linking` — edge-description discipline
- `/specs/2026-05-10-authoring-audit-heuristics.md` — concrete detection signals and improvement templates (in the repo at `specs/`, or query the graph if the spec has been promoted into the docs subgraph)

These live in the graph or repo. Load them; do not paraphrase or restate them in this skill body.

**Apply the discipline at write time.** When the user is authoring or editing:

- **Names**: identify, don't categorize. Specific over generic. Plural for collections, specific for entities.
- **Descriptions**: substance over topic. Decision-helpful, not labelish. The reader uses it to decide whether to drill in.
- **Link descriptions**: the local story between two specific Things. Roles and intent, not implementation specifics. Survives refactor.

**Apply the audit heuristics on demand.** When the user asks for a sweep, review, or audit:

- Walk the heuristics from the audit-heuristics spec (TOC enumeration, topic-style framing, vague qualifiers; sibling-distinctiveness; body-vs-description coherence)
- Surface findings inline with severity and suggested improvements
- Use the improvement templates: verb-phrases per child, distinctive-claim lead, body-mining
- **Never auto-apply.** The user decides which fixes to take.

## What this skill is not

- **Not a knowledge dump.** The principles, examples, and heuristics live in the graph and the audit spec. This skill is the activation/scaffolding that says *"consult those now."* If the principles change, the docs change — this skill body does not need to.
- **Not a static checker.** Compile-time advisory warnings (when implemented per the spec) are the static layer. This skill is the write-time layer.
- **Not framework-builder guidance.** For working *on* the framework code, use `spandrel-builder`.

## How this skill embodies Spandrel's principles

The skill body is small instruction. The knowledge it references — patterns, hypothesis, audit spec — lives in the graph or repo, where it can evolve freely without skill-body edits. This is **instruction/knowledge separation applied to skills themselves**: the skill is the byproduct of designing for write-time application of the discipline. The recursive Spandrel reference applies — skills don't duplicate the principles, they point at where the principles live.

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

spandrel-author

Directory Structure

SKILL.md

Report

Notice