feat: add SKILLS.md loading system (#193)

* feat: add SKILLS.md loading system using similar path to KB system, skill.md parsing, L1 register, auto matching with TF-IDF scoring option, char-based context budget, tests and race-clean

* fix: fixes for greptile code review for skills system

* fix: update config.example.yaml with new skills system options

* fix: honor skills config limits

* chore: format skill registry

* fix: improve skill validation reporting

---------

Co-authored-by: Alvin Unreal <alvin@cmngoal.com>

Author: swein

README.md

@@ -53,6 +53,12 @@
   - [Creating Knowledge Bases](#creating-knowledge-bases)
   - [Using Knowledge Bases](#using-knowledge-bases)
   - [Auto-Loading Knowledge Bases](#auto-loading-knowledge-bases)
+- [Skills](#skills)
+  - [Enabling Skills](#enabling-skills)
+  - [Creating Skills](#creating-skills)
+  - [Using Skills](#using-skills)
+  - [Auto-Match](#auto-match)
+  - [Budget Controls](#budget-controls)
 - [Model Configuration](#model-configuration)
   - [Setting Up Multiple Models](#setting-up-multiple-models)
   - [Switching Between Models](#switching-between-models)
@@ -428,6 +434,143 @@ knowledge_base:
 - Knowledge bases are injected after the system prompt but before conversation history
 - Unloading a KB removes it from future messages immediately
 
+## Skills
+
+The Skills feature extends the Knowledge Base system with structured, metadata-rich instructions that teach TmuxAI new capabilities. Unlike KBs (which provide passive reference material), skills can be auto-discovered, lazily loaded, and optionally auto-matched to incoming messages.
+
+Each skill lives in a directory with a `SKILL.md` file containing frontmatter metadata and body content. Ancillary files (scripts, templates, reference docs) can coexist in the same directory.
+
+### Enabling Skills
+
+Skills are **disabled by default**. Enable them in `~/.config/tmuxai/config.yaml`:
+```yaml
+knowledge_base:
+  skills:
+    enabled: true
+```
+
+### Creating Skills
+
+Skills are stored in `~/.config/tmuxai/skills/<skill-name>/`:
+
+```bash
+mkdir -p ~/.config/tmuxai/skills/git-hooks
+```
+
+Create `SKILL.md` with frontmatter:
+```bash
+cat > ~/.config/tmuxai/skills/git-hooks/SKILL.md << 'EOF'
+---
+name: git-hooks
+description: Git pre-commit and linting setup. Auto-stage hooks, conventional commits, branch protection.
+disable-model-invocation: false
+---
+
+# Git Hooks Guide
+
+## Pre-commit Setup
+
+```bash
+git config core.hooksPath .husky
+npm install husky --save-dev
+```
+
+...rest of the skill body...
+EOF
+```
+
+**Frontmatter fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique skill name (must match directory name, alphanumeric + hyphens only) |
+| `description` | Yes | Brief description shown in L1 discovery block and `/skill list` |
+| `disable-model-invocation` | No | If `true`, disables auto-match — skill must be loaded manually |
+
+Optional ancillary files (`.sh`, `.txt`, `.py`, `.json`) can be placed alongside `SKILL.md`. When a skill is loaded, TmuxAI includes a manifest listing those helper file paths so the model can request them if needed.
+
+### Using Skills
+
+```bash
+# List available skills
+TmuxAI » /skill
+Available skills:
+  [ ] docker-workflows
+  [ ] git-hooks                [manual]
+  [ ] terraform-best-practices
+
+# Load a skill (lazy-load body + ancillary file manifest)
+TmuxAI » /skill load git-hooks
+✓ Loaded skill: git-hooks (1,240 chars)
+
+# List again to see loaded status
+TmuxAI » /skill
+Available skills:
+  [✓] docker-workflows               (850 chars)
+  [✓] git-hooks                      (1,240 chars)
+  [ ] terraform-best-practices
+
+Loaded: 2/3 skill(s), 2,090/32,000 chars
+
+# View skill details without loading body
+TmuxAI » /skill info git-hooks
+Name:        git-hooks
+Description: Git pre-commit and linting setup.
+Disabled:    false
+Loaded:      true
+Body Size:   1,240 chars
+Directory:   ~/.config/tmuxai/skills/git-hooks
+File:        ~/.config/tmuxai/skills/git-hooks/SKILL.md
+
+# Validate all skills
+TmuxAI » /skill validate
+Validated 3 skill(s):
+  ✓ OK  docker-workflows
+  ✓ OK  git-hooks
+  ✓ OK  terraform-best-practices
+
+# Unload a skill
+TmuxAI » /skill unload git-hooks
+✓ Unloaded skill: git-hooks
+
+# Unload all skills
+TmuxAI » /skill unload --all
+✓ Unloaded all skills (2 skill(s))
+```
+
+### Auto-Match
+
+You can enable automatic skill matching against incoming messages:
+
+```yaml
+knowledge_base:
+  skills:
+    enabled: true
+    auto_match: true
+    auto_match_threshold: 0.1  # Match sensitivity (0.0–1.0, lower = more aggressive)
+```
+
+With auto-match enabled, TmuxAI analyzes incoming messages and loads relevant skills based on term frequency and description relevance. Skills marked `[manual]` (via `disable-model-invocation: true`) require explicit loading.
+
+### Budget Controls
+
+Skills share context budget with your conversation. Defaults:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `max_l1_chars` | 8,000 | Maximum chars for the L1 discovery block |
+| `max_loaded_chars` | 32,000 | Maximum chars across all loaded skill bodies |
+| `max_skill_chars` | 20,000 | Maximum chars per individual skill body; set to `0` to disable the per-skill cap |
+
+Use `/info` to monitor context usage with skills loaded.
+
+**Important Notes:**
+- Skills are injected after the system prompt and KBs, before conversation history
+- The L1 discovery block tells the model which skills exist and their load status
+- Body content is only loaded on demand (lazy loading)
+- A 1MB cap per SKILL.md prevents runaway memory usage
+- SKILL.md frontmatter fences (`---`) are matched line-by-line; standalone `---` lines in multi-line YAML values will be misinterpreted as the closing fence
+
 ## Model Configuration
 
 TmuxAI supports configuring multiple AI model configurations and easily switching between them. This allows you to define different AI providers, models, and settings for various use cases.

config.example.yaml

@@ -115,6 +115,18 @@ blacklist_patterns:
   - 'mv\s+'
   - 'dd\s+'
 
+# Knowledge Base: Skills system (opt-in)
+knowledge_base:
+  skills:
+    enabled: false  # Disabled by default; set true to enable
+    auto_scan: true
+    auto_match: false
+    auto_match_threshold: 0.1  # Match sensitivity (0.0–1.0, lower = more aggressive)
+    max_l1_chars: 8000        # L1 discovery block char budget
+    max_loaded_chars: 32000   # Total loaded skill bodies char budget
+    max_skill_chars: 20000    # Per-skill char cap (set 0 for unlimited; 1MB hard limit)
+    truncate_desc_at: 200     # Truncate descriptions in L1 block
+
 # Prompts customization, see prompts.go for more details
 prompts:
   base_system: |

config/config.go

@@ -90,10 +90,23 @@ type PromptsConfig struct {
 	Watch                 string `mapstructure:"watch"`
 }
 
+// SkillsConfig holds skill system configuration
+type SkillsConfig struct {
+	Enabled            bool    `mapstructure:"enabled"`
+	AutoScan           bool    `mapstructure:"auto_scan"`
+	AutoMatch          bool    `mapstructure:"auto_match"`
+	AutoMatchThreshold float64 `mapstructure:"auto_match_threshold"`
+	MaxL1Chars         int     `mapstructure:"max_l1_chars"`
+	MaxLoadedChars     int     `mapstructure:"max_loaded_chars"`
+	MaxSkillChars      int     `mapstructure:"max_skill_chars"`
+	TruncateDescAt     int     `mapstructure:"truncate_desc_at"`
+}
+
 // KnowledgeBaseConfig holds knowledge base configuration
 type KnowledgeBaseConfig struct {
-	AutoLoad []string `mapstructure:"auto_load"`
-	Path     string   `mapstructure:"path"`
+	AutoLoad []string     `mapstructure:"auto_load"`
+	Path     string       `mapstructure:"path"`
+	Skills   SkillsConfig `mapstructure:"skills"`
 }
 
 // TmuxConfig holds tmux-specific behavior settings.
@@ -135,6 +148,16 @@ func DefaultConfig() *Config {
 		KnowledgeBase: KnowledgeBaseConfig{
 			AutoLoad: []string{},
 			Path:     "",
+			Skills: SkillsConfig{
+				Enabled:            false,
+				AutoScan:           true,
+				AutoMatch:          false,
+				AutoMatchThreshold: 0.1,
+				MaxL1Chars:         8000,
+				MaxLoadedChars:     32000,
+				MaxSkillChars:      20000,
+				TruncateDescAt:     200,
+			},
 		},
 	}
 }

internal/chat.go

@@ -288,6 +288,44 @@ func (c *CLIInterface) newCompleter() *completion.CmdCompletionOrList2 {
 					return availableModels, availableModels
 				}
 			}
+
+			// Handle /skill subcommands
+			if len(field) > 0 && field[0] == "/skill" {
+				if len(field) == 1 || (len(field) == 2 && !strings.HasSuffix(field[1], " ")) {
+					return []string{"list ", "load ", "unload ", "info ", "validate "}, []string{"list ", "load ", "unload ", "info ", "validate "}
+				} else if len(field) >= 2 && field[1] == "load" {
+					// Complete with skill names
+					if c.manager.Skills != nil {
+						var skillNames []string
+						for name := range c.manager.Skills.Skills {
+							skillNames = append(skillNames, name)
+						}
+						return skillNames, skillNames
+					}
+				} else if len(field) >= 2 && field[1] == "info" {
+					// Complete with skill names
+					if c.manager.Skills != nil {
+						var skillNames []string
+						for name := range c.manager.Skills.Skills {
+							skillNames = append(skillNames, name)
+						}
+						return skillNames, skillNames
+					}
+				} else if len(field) >= 2 && field[1] == "unload" {
+					// Complete with loaded skill names and --all
+					var unloadTargets []string
+					unloadTargets = append(unloadTargets, "--all ")
+					if c.manager.Skills != nil {
+						for name, skill := range c.manager.Skills.Skills {
+							if skill.Loaded {
+								unloadTargets = append(unloadTargets, name+" ")
+							}
+						}
+					}
+					return unloadTargets, unloadTargets
+				}
+			}
+
 			return nil, nil
 		},
 	}