Skills: deterministic invocation — /<skill-name>, searchable /skills picker, discovery-budget fix

.gitignore

@@ -37,6 +37,7 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 
 /zero
 /zero.exe
+/zero-skills
 /snake-game.html
 
 # Superpowers skill artifacts (brainstorm mockups, specs, plans) — local only

internal/agent/skills_context_test.go

@@ -7,14 +7,18 @@ import (
 )
 
 func TestSkillsContextCapsLongList(t *testing.T) {
-	skills := make([]SkillInfo, 0, 40)
-	for i := 0; i < 40; i++ {
+	// 60 skills with realistic trigger-rich descriptions (~180 chars each, under
+	// the 200-rune truncation) total well past the 4096-byte list budget, so the
+	// overflow summary must kick in while the block stays bounded.
+	longDesc := strings.Repeat("use when the request touches deployments, release notes, or verification; ", 2) + "number "
+	skills := make([]SkillInfo, 0, 60)
+	for i := 0; i < 60; i++ {
 		n := strconv.Itoa(i)
-		skills = append(skills, SkillInfo{Name: "skill-" + n, Description: "does something useful, number " + n})
+		skills = append(skills, SkillInfo{Name: "skill-" + n, Description: longDesc + n})
 	}
 	got := skillsContext(Options{Skills: skills})
-	if len(got) > 1200 {
-		t.Fatalf("skills block should stay bounded, got %d bytes:\n%s", len(got), got)
+	if len(got) > skillsContextListBudget+1000 {
+		t.Fatalf("skills block should stay bounded near the %d-byte budget, got %d bytes:\n%s", skillsContextListBudget, len(got), got)
 	}
 	if !strings.Contains(got, "more (call skill") {
 		t.Fatalf("expected an overflow summary line, got:\n%s", got)
@@ -25,6 +29,27 @@ func TestSkillsContextCapsLongList(t *testing.T) {
 	}
 }
 
+// A realistic mid-size skill set (20 skills, trigger-rich descriptions) must be
+// listed in FULL — no overflow summary. This pins the fix for the old 640-byte
+// budget, under which skills past ~#6 were invisible to the model and therefore
+// never triggered.
+func TestSkillsContextListsRealisticSetInFull(t *testing.T) {
+	desc := "Use when the user asks about deployments, release notes, or pre-merge verification runs."
+	skills := make([]SkillInfo, 0, 20)
+	for i := 0; i < 20; i++ {
+		skills = append(skills, SkillInfo{Name: "skill-" + strconv.Itoa(i), Description: desc})
+	}
+	got := skillsContext(Options{Skills: skills})
+	if strings.Contains(got, "more (call skill") {
+		t.Fatalf("20 described skills must all be listed without overflow, got:\n%s", got)
+	}
+	for i := 0; i < 20; i++ {
+		if !strings.Contains(got, "- skill-"+strconv.Itoa(i)+":") {
+			t.Fatalf("skill-%d missing from the list:\n%s", i, got)
+		}
+	}
+}
+
 func TestSkillsContext(t *testing.T) {
 	if got := skillsContext(Options{}); got != "" {
 		t.Fatalf("no skills should yield an empty section, got %q", got)

internal/agent/system_prompt.go

@@ -191,18 +191,27 @@ func specialistDelegationContext(options Options) string {
 // when no skills are installed, so a skill-less run reproduces the previous prompt
 // byte-for-byte.
 // skillsContextListBudget bounds the bytes spent listing individual skills so a
-// workspace with dozens of them can't bloat every turn's prompt. Skills past the
-// budget are summarized as a count rather than dropped — the model can still load
-// any of them by name (an unknown name returns the full list from the skill tool).
-const skillsContextListBudget = 640
+// workspace with an extreme number of them can't bloat every turn's prompt.
+// Skills past the budget are summarized as a count rather than dropped — the
+// model can still load any of them by name (an unknown name returns the full
+// list from the skill tool).
+//
+// The budget is deliberately generous — roughly 18 skills with maximally long
+// (200-rune, ASCII) descriptions, or 40+ with typical terser ones; non-ASCII
+// descriptions consume it faster since the budget counts bytes. This list is
+// the model's ONLY discovery surface, so a skill squeezed out of it effectively
+// never triggers. The previous 640-byte cap silently broke invocation for
+// anyone with more than ~6 skills — the model cannot match a request against a
+// skill it cannot see.
+const skillsContextListBudget = 4096
 
 func skillsContext(options Options) string {
 	if len(options.Skills) == 0 {
 		return ""
 	}
 	var b strings.Builder
 	b.WriteString("<available_skills>\n")
-	b.WriteString("Reusable, on-demand instruction sets you can load with the skill tool. When a request matches one, call skill with its exact name to pull in its guidance before acting — do not guess names or skip a relevant skill.\n")
+	b.WriteString("Reusable, on-demand instruction sets you can load with the skill tool. Before acting on a request, scan this list; when the request matches a skill's name or description, call skill with its exact name FIRST and follow the loaded guidance — do not guess names, do not skip a matching skill, and do not substitute your own approach for its instructions.\n")
 	listed, spent, omitted := 0, 0, 0
 	for _, info := range options.Skills {
 		name := strings.TrimSpace(info.Name)
@@ -232,9 +241,11 @@ func skillsContext(options Options) string {
 }
 
 // truncateForSkillLine keeps a skill's one-line description short so a single
-// verbose description can't dominate the skills-list budget.
+// verbose description can't dominate the skills-list budget. The cap is roomy on
+// purpose: the description carries the skill's trigger conditions ("use when…"),
+// and truncating those is what stops the model from ever invoking the skill.
 func truncateForSkillLine(desc string) string {
-	const maxDescRunes = 100
+	const maxDescRunes = 200
 	runes := []rune(desc)
 	if len(runes) <= maxDescRunes {
 		return desc

internal/cli/app.go

@@ -12,6 +12,7 @@ import (
 	"os/exec"
 	"path/filepath"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/Gitlawb/zero/internal/agent"
@@ -782,6 +783,14 @@ func runInteractiveTUIWithSetup(stderr io.Writer, deps appDeps, permissionMode a
 			Specialists:    specialistRuntime.specialists,
 			Skills:         pluginActivation.skillInfos(deps.skillsDir()),
 		},
+		// LoadSkills backs /skills and direct /<skill-name> invocation in the TUI.
+		// It resolves against the same merged set (default dir + plugin skill
+		// roots) as the skill tool and the system-prompt list, re-read per use so
+		// newly installed skills work without a restart.
+		LoadSkills: cachedSkillsLoader(func() []skills.Skill {
+			merged, _ := plugins.MergedSkillsLoaded(deps.skillsDir(), pluginActivation.skillRoots)
+			return merged
+		}),
 		PermissionMode: permissionMode,
 		Notify:         resolved.Notify,
 		KeyBindings:    resolved.KeyBindings,
@@ -1277,3 +1286,26 @@ Flags:
 `)
 	return err
 }
+
+// cachedSkillsLoader memoizes a skills loader for a short interval. The TUI
+// calls the loader from autocomplete on every "/x" keystroke; without a cache
+// each keystroke would re-read every SKILL.md body. Two seconds is fresh enough
+// that a newly installed skill still shows up "immediately" while typing.
+func cachedSkillsLoader(load func() []skills.Skill) func() []skills.Skill {
+	var (
+		mu     sync.Mutex
+		at     time.Time
+		cached []skills.Skill
+	)
+	const ttl = 2 * time.Second
+	return func() []skills.Skill {
+		mu.Lock()
+		defer mu.Unlock()
+		if cached != nil && time.Since(at) < ttl {
+			return cached
+		}
+		cached = load()
+		at = time.Now()
+		return cached
+	}
+}

internal/tui/autocomplete.go

@@ -188,7 +188,54 @@ func (m model) matchCommandSuggestions(token string) []commandSuggestion {
 	out := matchCommandSuggestionsWithFilter(token, func(command commandDefinition) bool {
 		return command.kind != commandSandboxSetup || m.sandboxSetupCommand != nil
 	})
-	return append(out, m.matchUserCommandSuggestions(token)...)
+	out = append(out, m.matchUserCommandSuggestions(token)...)
+	out = append(out, m.matchSkillSuggestions(token)...)
+	// Each source caps itself, but the merged list must honor the shared cap too
+	// (three sources could otherwise stack up to ~3x the palette bound).
+	if len(out) > maxCommandSuggestions {
+		out = out[:maxCommandSuggestions]
+	}
+	return out
+}
+
+// matchSkillSuggestions returns installed skills whose slash name has the typed
+// prefix, so skills are discoverable and invocable from the palette like user
+// commands. Precedence (builtin > user command > skill) is enforced here by
+// skipping any skill whose name is claimed by a builtin (or alias) or a user
+// command — unlike the builtin/user pair, a shadowed skill row would be dead at
+// dispatch time, so it must not be advertised at all.
+func (m model) matchSkillSuggestions(token string) []commandSuggestion {
+	prefix := strings.ToLower(strings.TrimSpace(strings.TrimPrefix(token, "/")))
+	if prefix == "" || m.loadSkills == nil {
+		return nil
+	}
+	taken := m.takenSlashNames()
+	var out []commandSuggestion
+	// Read through the loader (not the startup snapshot in agentOptions) so the
+	// palette matches what dispatch will actually resolve — a skill installed or
+	// removed mid-session appears/disappears without a restart.
+	for _, skill := range m.installedSkills() {
+		name := skillSlashName(skill.Name)
+		if name == "" || taken[name] || !strings.HasPrefix(name, prefix) {
+			continue
+		}
+		// Two skills whose names collide after lowercasing (e.g. "Deploy" and
+		// "deploy") map to one slash name; only the first — the one dispatch will
+		// run — may be advertised, or the row's description and the executed
+		// instructions silently diverge.
+		taken[name] = true
+		desc := strings.TrimSpace(skill.Description)
+		if desc == "" {
+			desc = "Skill: /" + name
+		} else {
+			desc += " (skill)"
+		}
+		out = append(out, commandSuggestion{Name: "/" + name, Desc: desc})
+		if len(out) >= maxCommandSuggestions {
+			break
+		}
+	}
+	return out
 }
 
 // matchUserCommandSuggestions returns file-sourced /commands whose name has the

internal/tui/command_views.go

@@ -698,3 +698,19 @@ func (m model) debugText() string {
 		}},
 	})
 }
+
+// skillsText is the /skills fallback when NO skills are installed — an install
+// hint. With skills present /skills opens the searchable skill picker instead
+// (see newSkillPicker), matching how /model works.
+func (m model) skillsText() string {
+	return renderCommandOutput(commandOutput{
+		Title:  "Skills",
+		Status: commandStatusInfo,
+		Sections: []commandSection{{
+			Lines: []string{"No skills installed."},
+		}},
+		Hints: []string{
+			"install one: create <skills-dir>/<name>/SKILL.md (see `zero skills`)",
+		},
+	})
+}

internal/tui/commands.go

@@ -46,6 +46,7 @@ const (
 	commandCopy
 	commandExport
 	commandNew
+	commandSkills
 	commandUnknown
 )
 
@@ -131,6 +132,13 @@ var commandDefinitions = []commandDefinition{
 		description: "List registered tools.",
 		kind:        commandTools,
 	},
+	{
+		name:        "/skills",
+		usage:       "/skills",
+		group:       commandGroupTools,
+		description: "List installed skills; run one directly with /<skill-name> [args].",
+		kind:        commandSkills,
+	},
 	{
 		name:        "/context",
 		usage:       "/context",

internal/tui/model.go

@@ -29,6 +29,7 @@ import (
 	"github.com/Gitlawb/zero/internal/providers/providerio"
 	"github.com/Gitlawb/zero/internal/sandbox"
 	"github.com/Gitlawb/zero/internal/sessions"
+	"github.com/Gitlawb/zero/internal/skills"
 	"github.com/Gitlawb/zero/internal/streamjson"
 	"github.com/Gitlawb/zero/internal/tools"
 	"github.com/Gitlawb/zero/internal/usage"
@@ -62,6 +63,7 @@ type model struct {
 	ctx                         context.Context
 	cwd                         string
 	userCommands                []usercommands.Command // file-sourced /commands (.zero/commands)
+	loadSkills                  func() []skills.Skill  // lazy installed-skills loader for /skills + /<skill-name>
 	userConfigPath              string
 	doctorUserConfigPath        string
 	projectConfigPath           string
@@ -735,6 +737,7 @@ func newModel(ctx context.Context, options Options) model {
 		cwd:                         cwd,
 		swarmDoneAt:                 map[string]time.Time{},
 		userCommands:                loadedUserCommands,
+		loadSkills:                  options.LoadSkills,
 		composerCursorVisible:       true,
 		userConfigPath:              options.UserConfigPath,
 		doctorUserConfigPath:        doctorUserConfigPath,
@@ -3730,6 +3733,11 @@ func (m model) choosePicker() (tea.Model, tea.Cmd) {
 		if text != "" {
 			m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: text})
 		}
+	case pickerSkill:
+		// Fill the composer with "/name " so the user adds their request before
+		// submitting (a bare second Enter runs it without one); names the slash
+		// path cannot reach run immediately instead.
+		m, cmd = m.chooseSkillFromPicker(item)
 	case pickerTheme:
 		// The hovered palette is already live from the preview; handleThemeCommand
 		// records the choice (m.themeMode) and re-applies it, and reports the switch.
@@ -3845,6 +3853,15 @@ func (m model) handleSubmit() (tea.Model, tea.Cmd) {
 	case commandTools:
 		m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: m.toolsText()})
 		return m, nil
+	case commandSkills:
+		// With skills installed, /skills opens a searchable picker (like /model);
+		// the text card remains only as the no-skills install hint.
+		if picker := m.newSkillPicker(); picker != nil {
+			m.picker = picker
+			return m, nil
+		}
+		m.transcript = reduceTranscript(m.transcript, transcriptAction{kind: actionAppendSystem, text: m.skillsText()})
+		return m, nil
 	case commandMCP:
 		if strings.TrimSpace(command.text) == "" {
 			return m.openMCPManager(), nil
@@ -4040,6 +4057,11 @@ func (m model) handleSubmit() (tea.Model, tea.Cmd) {
 		if next, cmd, handled := m.handleUserCommand(command.text); handled {
 			return next, cmd
 		}
+		// Then an installed skill: "/<skill-name> [args]" runs the skill directly
+		// (deterministic invocation, vs waiting for the model to pull it in).
+		if next, cmd, handled := m.handleSkillCommand(command.text); handled {
+			return next, cmd
+		}
 		m.transcript = reduceTranscript(m.transcript, transcriptAction{
 			kind: actionAppendError,
 			text: "unknown command: " + command.text,

internal/tui/options.go

@@ -13,6 +13,7 @@ import (
 	"github.com/Gitlawb/zero/internal/providermodeldiscovery"
 	"github.com/Gitlawb/zero/internal/sandbox"
 	"github.com/Gitlawb/zero/internal/sessions"
+	"github.com/Gitlawb/zero/internal/skills"
 	"github.com/Gitlawb/zero/internal/tools"
 	"github.com/Gitlawb/zero/internal/usage"
 	"github.com/Gitlawb/zero/internal/zeroruntime"
@@ -48,7 +49,13 @@ type Options struct {
 	SessionCompactor            SessionCompactor
 	PrService                   *PrService
 
-	AgentOptions    agent.Options
+	AgentOptions agent.Options
+	// LoadSkills returns the installed skills (default skills dir merged with any
+	// plugin skill roots), bodies included, for /skills and direct /<skill-name>
+	// invocation. Called lazily per use so newly installed skills are picked up
+	// without a restart. Nil means the session has no skills wiring (skills stay
+	// model-pulled via the skill tool only).
+	LoadSkills      func() []skills.Skill
 	PermissionMode  agent.PermissionMode
 	ReasoningEffort modelregistry.ReasoningEffort
 	ResponseStyle   string

internal/tui/picker.go

@@ -24,6 +24,7 @@ const (
 	pickerEffort
 	pickerSession
 	pickerTheme
+	pickerSkill
 )
 
 // pickerItem is one selectable row: Label is shown, Value is passed to the
@@ -225,6 +226,35 @@ func (m model) newModelPicker() *commandPicker {
 	return &commandPicker{kind: pickerModel, title: "Choose a model", items: items, allItems: append([]pickerItem{}, items...), selected: 0}
 }
 
+// newSkillPicker lists the installed skills for browse-and-run: type to filter,
+// arrow keys to select, Enter runs the chosen skill immediately. Selection is by
+// the skill's EXACT name (item.Value), so even skills the slash path cannot
+// reach — names shadowed by a builtin or user command, or names that don't fit
+// a slash token — are runnable here: picking from the Skills picker is
+// unambiguous. Returns nil when no skills are installed (the caller falls back
+// to the install-hint card).
+func (m model) newSkillPicker() *commandPicker {
+	installed := m.installedSkills()
+	items := make([]pickerItem, 0, len(installed))
+	for _, skill := range installed {
+		name := strings.TrimSpace(skill.Name)
+		if name == "" {
+			continue
+		}
+		label := name
+		if slash := skillSlashName(name); slash != "" {
+			// Show the slash form where one exists — it doubles as documentation
+			// of the direct "/name [args]" invocation.
+			label = "/" + slash
+		}
+		items = append(items, pickerItem{Label: label, Value: name, Meta: strings.TrimSpace(skill.Description)})
+	}
+	if len(items) == 0 {
+		return nil
+	}
+	return &commandPicker{kind: pickerSkill, title: "pick a skill · ⏎ fills /name — add your request", items: items, allItems: append([]pickerItem{}, items...), selected: 0}
+}
+
 // modelPickerProviders returns the providers to list in /model: all saved
 // providers, falling back to the active profile when none were threaded in.
 func (m model) modelPickerProviders() []config.ProviderProfile {