go-go-golems/ttmp/_guidelines

Guidelines: Skill Documents

Purpose

Skills are disciplined workflows written as documents (DocType: skill) that teach LLMs (and humans) how to work, not just what exists. A good skill turns “best practice” into a repeatable, enforceable process.

Skills are meant to be discoverable via:

• docmgr skill list (filter by topics, file/dir, ticket)
• docmgr skill show <query> (load and apply a skill)

Required Elements

• Frontmatter contract
  • DocType: skill
  • Title: Use the convention Skill: <Name> (recommended)
  • Topics: Choose topics that match how developers will search (e.g. tdd, debugging, docs)
  • WhatFor: 2–5 sentences describing the outcome this workflow ensures
  • WhenToUse: Clear trigger conditions (“Use when …”)
• Body
  • Overview: 2–5 sentences (why it matters; what it enforces)
  • When to Use: Concrete triggers + examples
  • Process: Step-by-step actions (copy/paste friendly commands where possible)
  • Verification: Checklist to prevent “I think I’m done” drift

Best Practices

• Be explicit: Use strong modal language (“MUST”, “NEVER”, “STOP”) where appropriate.
• Optimize for discovery: Ensure Topics, WhatFor, and WhenToUse contain the words people will actually search for.
• Prefer commands over prose: If there’s a canonical command sequence, include it as a bash block.
• Make validation unskippable: Add a checklist and expected success criteria (tests/linters/scenario suites).

References

• pkg/doc/how-to-write-skills.md — Full guidance on writing and enforcing skills
• pkg/doc/using-skills.md — How to discover and load skills via CLI