Skill Building

A skill written after successful delivery is worth 10x one written from theory.

Phase 2: Define Scope

Answer these questions first:

1. What problem does this skill solve? (1 sentence)
2. What are the key gotchas? (list 3-5)
3. What would I tell a colleague? (elevator pitch)
4. Does this already exist? (check skill catalog)

Scope Check:

Phase 3: Create the Skill

Folder Structure:

.github/skills/{skill-name}/
├── SKILL.md          # Required: Main content
├── synapses.json     # Optional: Brain connections
└── {assets}          # Optional: Templates, CSS, scripts

Naming Convention:

SKILL.md Template

---
applyTo: "{glob-patterns}"
---

# {Skill Name}

> {One-line description — what + who}

{2-3 sentence intro with context}

---

## When to Use

- {Primary use case}
- {Secondary use case}
- {Edge case that surprised you}

---

## Quick Reference

{Most important info — tables, cheat sheets, one-liners}

---

## {Module 1: Core Concept}

{Main content organized by topic}

### {Sub-section}

{Details, patterns, examples}

---

## {Module N: Advanced}

{Progressive disclosure — basics first, advanced later}

---

## Troubleshooting

### {Problem Title}

**Problem**: {What goes wrong}

**Solution**: {How to fix it}

**Why**: {Root cause for learning}

---

## Activation Patterns

| Trigger | Response |
|---------|----------|
| "{keyword}" | Full skill activation |
| "{partial keyword}" | {Specific module} |

---

*Skill created: {date} | Category: {category} | Status: Active*

---
## applyTo Patterns

Choose patterns that match when this skill should activate:

| Pattern | When to Use | Example Skills |
|---------|-------------|----------------|
| `**/*.{ext}` | File-type specific | `typescript-patterns` |
| `**/*{keyword}*` | Name-based activation | `markdown-mermaid` |
| `**/test*` | Context-based | `testing-strategies` |
| `src/**` | Location-based | `frontend-patterns` |

**Common Combinations:**

```yaml
# Documentation skills
applyTo: "**/*.md,**/readme*,**/docs/**"

# TypeScript skills  
applyTo: "**/*.ts,**/*.tsx,**/tsconfig*"

# Azure skills
applyTo: "**/azure*,**/bicep*,**/arm*,**/*.bicep"

# Broad activation (use sparingly)
applyTo: "**/*"

Synapse Guidelines

When to Add Synapses

Strength Values

Direction Types

Format:

- [.github/skills/{skill}/SKILL.md] (High, Enables, Bidirectional) - "When X happens"

Quality Checklist

Before promoting to Master, verify:

Content Quality

• Validated: Based on real-world experience, not theory
• Gotchas included: Hard-won lessons documented
• Actionable: Reader can immediately apply
• Examples: Code/patterns are concrete, not abstract

Structure Quality

• Quick Reference: Most useful info first
• Progressive disclosure: Basics → Advanced
• Troubleshooting: Common problems solved
• Activation patterns: Clear triggers defined

Integration Quality

• applyTo set: Appropriate glob patterns
• Synapses defined: 2-5 meaningful connections
• No duplication: Doesn't overlap with existing skills
• Keywords identified: For memory-activation index

Promotion Readiness Score

Calculate before requesting Master promotion:

Promotion thresholds:

• ≥12: Ready for Master
• 8-11: Needs refinement
• <8: Keep developing

Recognizing Shallow vs Deep Content

The biggest failure mode in skill creation is the capabilities-list anti-pattern — a skill that reads like a product brochure instead of encoding real knowledge.

The Capabilities-List Anti-Pattern

# ❌ SHALLOW — adds zero value
Expert in domain-agnostic knowledge acquisition.

## Capabilities
- Guide conversational knowledge acquisition
- Create skill files
- Build expertise through progressive questioning

## When to Use
- User wants to learn something new
- Teaching Alex about a domain

Why this fails: An LLM already knows how to "guide conversational learning" generically. The skill adds nothing the model didn't already have. It's a capability label, not capability knowledge.

What Deep Looks Like

# ✅ DEEP — encodes specific, actionable knowledge

## Phase 2: Foundation — Nail the core concepts

- Ask for the simplest possible explanation of each concept
- Demand concrete examples, not abstractions
- Test understanding by explaining it back
- **Red flag**: If the explanation uses jargon from the same domain, you haven't bottomed out

**Exit criteria**: Can explain core concepts without jargon.

Depth Assessment Rubric

The Litmus Test

For each section, ask: "Would an LLM produce something equally useful without this skill?"

• If yes → the section is shallow, rewrite or remove it
• If no → the section earns its place

Trifecta Decision Framework

A trifecta = SKILL.md (declarative) + .instructions.md (procedural) + .prompt.md (interactive). Not every skill needs one.

When to Build a Trifecta

Trifecta Components — What Goes Where

Rule: If the skill's value is in its reference data (tables, thresholds, patterns), a SKILL.md alone is correct. Only add procedures/prompts when there's a genuine process to guide.

Building the Trifecta

1. Start with SKILL.md — always create the declarative knowledge first
2. Observe usage — is there a repeatable process emerging?
3. Add .instructions.md — when you can write numbered steps with decision points
4. Add .prompt.md — when users need an interactive guided experience
5. Register in catalogs — update TRIFECTA-CATALOG.md

Muscle Assessment

A muscle is an execution script in .github/muscles/ — the motor cortex of the architecture. Scripts, not memory.

When to Create a Muscle

Muscle Naming Convention

Muscle + Trifecta Integration

A muscle is referenced by a trifecta but is never a memory component itself:

SKILL.md          → "What to check" (knowledge)
.instructions.md  → "Step 5: Run brain-qa.ps1" (procedure)
.prompt.md        → "Shall I run the health check?" (interaction)
brain-qa.ps1      → Actually runs the check (execution)

Memory File Inheritance

Every memory file declares how it syncs from Master Alex to heir projects. Default is inheritable (syncs automatically). Each file type uses its native format:

Declaration Mechanisms

Inheritance Types

Trifecta Consistency Rule

When a skill is non-inheritable, its trifecta siblings must have matching frontmatter:

# In the .instructions.md and .prompt.md files:
---