跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
搜索与研究

ghm-sot-builder

Creates new Source of Truth (SoT) files when existing templates don't fit your needs. Triggers on requests to create a new SoT file, add a new artifact type, or when user says "I need to track [X] but there's no SoT for it", "create SoT", "new source of truth". Outputs a properly structured SoT.*.md file with ID prefix, frontmatter, and update protocol.

mattgierhart · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add mattgierhart/PRD-driven-context-engineering --skill ghm-sot-builder

技能说明


name: ghm-sot-builder description: > Creates new Source of Truth (SoT) files when existing templates don't fit your needs. Triggers on requests to create a new SoT file, add a new artifact type, or when user says "I need to track [X] but there's no SoT for it", "create SoT", "new source of truth". Outputs a properly structured SoT.*.md file with ID prefix, frontmatter, and update protocol. context: fork allowed-tools:

  • Read
  • Write
  • Edit
  • Glob
  • Grep

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.

ElementDefinitionRequired
YAML Frontmatterversion, purpose, id_prefix, authorityYes
Purpose BlockSingle paragraph explaining what this tracksYes
Navigation SectionCategory links for quick accessYes
Entry TemplateRepeatable structure for each IDYes
Cross-Reference IndexBidirectional links to other SoT filesYes
Update ProtocolWhen/how to add new entriesYes

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:

FieldPurposeExample
IDUnique identifierPIC-001
TitleHuman-readable name"Stripe Payment Integration"
StatusCurrent stateActive / Deprecated / Planned
CreatedOrigin date2025-01-10
Last UpdatedLast modification2025-01-15
Related IDsCross-referencesBR-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
阅读完整来源 ↗