Agent-Skills.md

Agent Skills: SoT Builder

>

UncategorizedID: mattgierhart/PRD-driven-context-engineering/ghm-sot-builder

Repository

mattgierhart/PRD-driven-context-engineering
mattgierhartLicense: MIT
213

Install this agent skill to your local

pnpm dlx add-skill https://github.com/mattgierhart/PRD-driven-context-engineering/tree/HEAD/.claude/skills/ghm-sot-builder

Skill Files

Browse the full folder contents for ghm-sot-builder.

Download Skill

Loading file tree…

.claude/skills/ghm-sot-builder/SKILL.md

Skill Metadata

Name
ghm-sot-builder
Description
>

SoT Builder

Create new Source of Truth files that fit your product's unique needs while maintaining template purity.

When to Use This Skill

This skill is for rare occasions (3-4 times per product lifecycle) when:

  • You fork this repo and the existing SoT files don't cover your artifact types
  • Your product needs to track a concept that doesn't fit existing ID prefixes
  • You need to consolidate scattered documentation into a canonical SoT

Do NOT use when:

  • An existing SoT file covers your need (just add entries there)
  • You want to track temporary/session-specific data (use temp/ instead)
  • The artifact type is already covered by ghm-id-register

Workflow Overview

  1. Identify Need → Confirm no existing SoT fits
  2. Design Schema → Define ID prefix, categories, required fields
  3. Draft Template → Create pure structure (no methodology teaching)
  4. Validate Purity → Apply the litmus test
  5. Register & Integrate → Update SoT.README.md and ID system

Core Output Template

See assets/sot-template.md for the copy-paste starter template.

| Element | Definition | Required | |---------|------------|----------| | YAML Frontmatter | version, purpose, id_prefix, authority | Yes | | Purpose Block | Single paragraph explaining what this tracks | Yes | | Navigation Section | Category links for quick access | Yes | | Entry Template | Repeatable structure for each ID | Yes | | Cross-Reference Index | Bidirectional links to other SoT files | Yes | | Update Protocol | When/how to add new entries | Yes |

Step 1: Identify the Need

Before creating a new SoT, verify:

Checklist

  • [ ] Searched existing SoT files for similar artifact types
  • [ ] Confirmed the concept is durable (survives multiple sessions)
  • [ ] Confirmed the concept needs unique IDs for cross-referencing
  • [ ] Confirmed this isn't better served by a subsection in an existing SoT

Questions to Answer

  1. What artifact type does this track?

    • Bad: "Notes" (too generic)
    • Good: "Partner Integration Contracts" (specific, durable)

  2. Why can't existing SoT files handle this?

    • Valid: "We need different fields than API contracts for partner integrations"
    • Invalid: "I just want a separate file" (preference, not need)

  3. What ID prefix will you use?

    • Must be unique across the system
    • 2-4 uppercase letters
    • Check SoT/SoT.UNIQUE_ID_SYSTEM.md for existing prefixes

Step 2: Design the Schema

Define the structure before writing:

ID Prefix Selection

Format: [PREFIX]-[XXX]
Examples: PIC-001, INT-042, MIG-003

Rules:

  • 2-4 uppercase letters
  • Descriptive but short
  • Unique across all SoT files
  • Check existing prefixes in SoT/SoT.UNIQUE_ID_SYSTEM.md

Category Ranges

Reserve ID ranges for logical groupings:

**Category A** (XXX-001 to XXX-099):
**Category B** (XXX-101 to XXX-199):
**Category C** (XXX-201 to XXX-299):

Required Fields per Entry

Define the minimum fields every entry needs:

| Field | Purpose | Example | |-------|---------|---------| | ID | Unique identifier | PIC-001 | | Title | Human-readable name | "Stripe Payment Integration" | | Status | Current state | Active / Deprecated / Planned | | Created | Origin date | 2025-01-10 | | Last Updated | Last modification | 2025-01-15 | | Related IDs | Cross-references | BR-101, API-045 |

Optional Fields

Add domain-specific fields as needed, but keep them structural (not methodology):

  • Good: "Partner Contact" (data field)
  • Bad: "Best Practices for Partner Selection" (methodology teaching)

Step 3: Draft the Template

Use assets/sot-template.md as your starting point.

Structure Sections

  1. YAML Frontmatter - Metadata for the file
  2. Title & Purpose Block - What this SoT tracks
  3. Navigation by Category - Quick links to entries
  4. Entry Template - Repeatable structure (copy for each new entry)
  5. Deprecated Section - Where old entries go
  6. Cross-Reference Index - Bidirectional links
  7. Update Protocol - When/how to maintain

Template Purity Rules

KEEP in the template (self-documentation):

  • When to add new entries
  • Required fields checklist
  • Cross-reference integrity checks
  • File-specific maintenance procedures

MOVE to skill references (methodology teaching):

  • "Best practices" for this domain
  • "What makes a good entry"
  • Example workflows beyond format
  • Evaluation criteria

Litmus Test

For each section, ask:

"Is this teaching me how to maintain the FILE STRUCTURE, or teaching me DOMAIN KNOWLEDGE about what makes good content?"

  • File structure maintenance → Keep in template
  • Domain knowledge → Move to skill references

Step 4: Validate Purity

Before finalizing, run this checklist:

Purity Checklist

  • [ ] No "how to analyze" or "how to evaluate" content
  • [ ] No "best practices" or "key learnings" sections
  • [ ] No cross-file workflows (multi-file coordination)
  • [ ] No "what makes a good entry" evaluation criteria
  • [ ] Examples show FORMAT only, not instructional CONTENT
  • [ ] Self-documentation is under 20% of total file size

Self-Documentation Checklist

  • [ ] Has "Update Protocol" section
  • [ ] Documents when to add new IDs
  • [ ] Includes cross-reference integrity checks
  • [ ] Specifies required fields for new entries
  • [ ] Self-documentation is file-specific (not generic)

Context Efficiency Checklist

  • [ ] Template can be read without loading other files
  • [ ] Methodology examples are in skill references, not template
  • [ ] General governance references SoT.README.md

Step 5: Register and Integrate

After creating the SoT file:

Update SoT.README.md

Add entry to the structure table:

| `SoT.{YOUR_FILE}.md` | {PREFIX}-### | {Purpose description} |

Update SoT.UNIQUE_ID_SYSTEM.md

Add new prefix to Section 1.2 Standard Prefixes:

| **{PREFIX}** | {Meaning} | `SoT.{YOUR_FILE}.md` |

Create Index Tables

Add empty index table in Part 2 of SoT.UNIQUE_ID_SYSTEM.md:

#### {Your Type} ({PREFIX}-XXX)

| ID | Title | Status | Used By |
|----|-------|--------|---------|
| {PREFIX}-001 | {Title} | Active | {IDs} |

Quality Gates

Pass Checklist

  • [ ] ID prefix is unique across all SoT files
  • [ ] Template follows purity standard
  • [ ] Update protocol included
  • [ ] Cross-reference index structure defined
  • [ ] SoT.README.md updated
  • [ ] SoT.UNIQUE_ID_SYSTEM.md updated

Testability Check

  • [ ] Can create a new entry using only the template instructions
  • [ ] Cross-references can be validated programmatically
  • [ ] Entries can be found by ID search

Anti-Patterns

| Pattern | Example | Fix | |---------|---------|-----| | Methodology in template | "Best practices for partner selection" | Move to skill references | | Duplicate prefix | Using BR- for a new file | Choose unique prefix | | Too generic | "Notes.md" | Be specific: "Partner_Integrations.md" | | No update protocol | Template with no maintenance section | Add "Update Protocol" section | | Orphan SoT | Not registered in SoT.README.md | Always register new files |

Bundled Resources

  • references/sot-patterns.md — Common patterns across existing SoT files
  • references/examples.md — Before/after examples of SoT creation
  • assets/sot-template.md — Copy-paste starter template

Handoff

After creating a new SoT:

  1. SoT file exists at SoT/SoT.{NAME}.md
  2. SoT.README.md lists the new file
  3. SoT.UNIQUE_ID_SYSTEM.md has the new prefix
  4. Ready to use ghm-id-register for adding entries