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
└── {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: "**/*"

Connection Guidelines

When to Connect Skills

Skills connect through:

1. Frontmatter applyTo patterns — File patterns that trigger activation
2. Body text references — Links to related skills: [skill-name](..\skill-name/SKILL.md)
3. Semantic relationships — VS Code's semantic search finds related skills by content

How to Link Skills

1. Related Skills section — Add at end of SKILL.md:

   ## Related Skills
   - [debugging-patterns](../debugging-patterns/SKILL.md) - Systematic problem-solving
   - [root-cause-analysis](../root-cause-analysis/SKILL.md) - Deep investigation
   

2. In-line references — Mention related skills in context:

   For visual diagrams, see the [markdown-mermaid](../markdown-mermaid/SKILL.md) skill.
   

3. applyTo overlap — Skills with overlapping applyTo patterns naturally co-activate.

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
• Connections defined: 2-5 related skill links
• 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) + muscle (automation). Prompts are optional interfaces for explicit invocation. Not every skill needs a trifecta.

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. Verify registration — run brain-qa to confirm trifecta completeness

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:
---
description: "..."
inheritance: master-only   # ← Must match the skill's exclusion type
---

Without this, the instruction/prompt syncs as an orphan to heirs where the paired skill doesn't exist.

Scaffold with Inheritance

# Creates skill + auto-registers in SKILL_EXCLUSIONS:
.github/muscles/new-skill.ps1 -SkillName "my-skill" -Inheritance master-only

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 links: Redirect references 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 Memory-Activation

Add your skill to the action-keyword index:

Location: .github/skills/memory-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"