Skill Building

Skill Building

Create effective, reusable skills from real-world experience

Meta-skill for heirs to build high-quality skills that can be promoted to Master Alex.

When to Use

• After completing a project with reusable learnings
• When you've discovered gotchas worth documenting
• When patterns are ready to be promoted to Master
• When creating new domain expertise from scratch

The Skill Creation Workflow

Phase 1: Wait for Validation

Never create skills from theory. Wait for:

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*

---

## Synapses

- [{related-skill}/SKILL.md] ({Strength}, {Type}, {Direction}) - "{When}"
- [{related-instructions}.md] ({Strength}, {Type}, {Direction}) - "{When}"

applyTo Patterns

Choose patterns that match when this skill should activate:

Common Combinations:

# 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 skill-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)

Anti-Patterns

Examples: Good vs Bad

❌ Bad Skill Start

# My Azure Function

> How I built my Azure Function

## Setup
1. Created function app
2. Added my config...

Problems: Project-specific, no reusability, no patterns

✅ Good Skill Start

# Azure Functions Patterns

> Production patterns for serverless Azure development

## When to Use
- HTTP-triggered APIs
- Event-driven processing
- Scheduled jobs

## Quick Reference

| Trigger | Use When | Gotcha |
|---------|----------|--------|
| HTTP | API endpoints | Cold start 5-10s |
| Timer | Scheduled jobs | UTC timezone only |
...

Why better: General patterns, table for quick reference, gotchas included

Skill Consolidation (KISS Merge)

When related skills exist, merge rather than proliferate:

When to Merge

• 2+ skills serve same domain
• Skills would always be used together
• Content overlap > 30%

Merge Process

1. Choose anchor: Most comprehensive skill
2. Absorb content: Move unique sections from others
3. Update synapses: Redirect connections to anchor
4. Archive sources: Keep in heir for history
5. Document merge: Note absorbed skills at bottom

Example:

*Skill created: 2026-02-10 | Category: Communication | Status: Active*
*Merged: stakeholder-management, meeting-efficiency*

After Creation: Register with Skill-Activation

Add your skill to the action-keyword index:

Location: .github/skills/skill-activation/SKILL.md

Format:

| {skill-name} | {keyword1}, {keyword2}, {keyword3} |

Choose keywords that users would actually say:

• Action verbs: "create", "debug", "design"
• Domain terms: "azure", "mermaid", "citation"
• Problem phrases: "not working", "how to"

Synapses

• [.github/instructions/skill-building.instructions.md] (Critical, Implements, Forward) - "Step-by-step procedure for creating and completing skills"
• [.github/instructions/bootstrap-learning.instructions.md] (High, Enables, Bidirectional) - "Learning becomes skill"
• [.github/instructions/heir-skill-promotion.instructions.md] (Critical, Implements, Forward) - "Skill ready for promotion"
• [.github/skills/skill-activation/SKILL.md] (High, Integrates, Forward) - "Register for discovery"
• [.github/skills/skill-catalog-generator/SKILL.md] (Medium, Triggers, Forward) - "Regenerate catalog after creation"
• SYNAPSE-SCHEMA.md (High, References, Backward) - "Canonical synapse architecture reference"

Skill created: 2026-02-10 | Category: Meta-Skills | Status: Active