Merge pull request #2116 from dgageot/board/we-must-support-skills-that-work-on-clau-418d8ffc

Support dynamic command expansion in skills (\!`command` syntax)

Author: dgageot

pkg/app/app.go

@@ -194,7 +194,7 @@ func (a *App) CurrentAgentSkills() []skills.Skill {
 
 // ResolveSkillCommand checks if the input matches a skill slash command (e.g. /skill-name args).
 // If matched, it reads the skill content and returns the resolved prompt. Otherwise returns "".
-func (a *App) ResolveSkillCommand(input string) (string, error) {
+func (a *App) ResolveSkillCommand(ctx context.Context, input string) (string, error) {
 	if !strings.HasPrefix(input, "/") {
 		return "", nil
 	}
@@ -212,7 +212,7 @@ func (a *App) ResolveSkillCommand(input string) (string, error) {
 			continue
 		}
 
-		content, err := st.ReadSkillContent(skill.Name)
+		content, err := st.ReadSkillContent(ctx, skill.Name)
 		if err != nil {
 			return "", fmt.Errorf("reading skill %q: %w", skill.Name, err)
 		}
@@ -229,7 +229,7 @@ func (a *App) ResolveSkillCommand(input string) (string, error) {
 // ResolveInput resolves the user input by trying skill commands first,
 // then agent commands. Returns the resolved content ready to send to the agent.
 func (a *App) ResolveInput(ctx context.Context, input string) string {
-	if resolved, err := a.ResolveSkillCommand(input); err != nil {
+	if resolved, err := a.ResolveSkillCommand(ctx, input); err != nil {
 		return fmt.Sprintf("Error loading skill: %v", err)
 	} else if resolved != "" {
 		return resolved

pkg/app/app_test.go

@@ -245,7 +245,7 @@ func TestApp_ResolveSkillCommand_NoLocalRuntime(t *testing.T) {
 	app := New(ctx, rt, sess)
 
 	// mockRuntime is not a LocalRuntime, so no skills should be returned
-	resolved, err := app.ResolveSkillCommand("/some-skill")
+	resolved, err := app.ResolveSkillCommand(ctx, "/some-skill")
 	require.NoError(t, err)
 	assert.Empty(t, resolved)
 }
@@ -258,7 +258,7 @@ func TestApp_ResolveSkillCommand_NotSlashCommand(t *testing.T) {
 	sess := session.New()
 	app := New(ctx, rt, sess)
 
-	resolved, err := app.ResolveSkillCommand("not a slash command")
+	resolved, err := app.ResolveSkillCommand(ctx, "not a slash command")
 	require.NoError(t, err)
 	assert.Empty(t, resolved)
 }

pkg/skills/expand.go

@@ -0,0 +1,85 @@
+package skills
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"log/slog"
+	"os/exec"
+	"regexp"
+	"strings"
+	"time"
+)
+
+// commandTimeout is the maximum time allowed for a single command expansion.
+const commandTimeout = 30 * time.Second
+
+// maxOutputSize is the maximum number of bytes read from a command's stdout.
+const maxOutputSize = 1 << 20 // 1 MB
+
+// commandPattern matches the !`command` syntax used by Claude Code skills
+// to embed dynamic command output into skill content.
+var commandPattern = regexp.MustCompile("!`([^`]+)`")
+
+// ExpandCommands replaces all !`command` patterns in the given content
+// with the stdout of executing each command via the system shell.
+// Commands are executed with the specified working directory.
+// If a command fails, the pattern is replaced with an error message
+// rather than failing the entire expansion.
+func ExpandCommands(ctx context.Context, content, workDir string) string {
+	return commandPattern.ReplaceAllStringFunc(content, func(match string) string {
+		command := match[2 : len(match)-1] // strip leading !` and trailing `
+
+		output, err := runCommand(ctx, command, workDir)
+		if err != nil {
+			slog.Warn("Skill command expansion failed", "command", command, "error", err)
+			return fmt.Sprintf("[error executing `%s`: %s]", command, err)
+		}
+
+		return strings.TrimRight(output, "\n")
+	})
+}
+
+// runCommand executes a shell command and returns its stdout (up to maxOutputSize bytes).
+// The command runs in the specified working directory.
+func runCommand(ctx context.Context, command, workDir string) (string, error) {
+	ctx, cancel := context.WithTimeout(ctx, commandTimeout)
+	defer cancel()
+
+	cmd := exec.CommandContext(ctx, "sh", "-c", command)
+	cmd.Dir = workDir
+
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+
+	stdout, err := cmd.StdoutPipe()
+	if err != nil {
+		return "", err
+	}
+
+	if err := cmd.Start(); err != nil {
+		return "", err
+	}
+
+	out, err := io.ReadAll(io.LimitReader(stdout, maxOutputSize))
+	if err != nil {
+		return "", err
+	}
+
+	// Drain any remaining stdout so the process doesn't block on a full pipe
+	// and hang until the context timeout kills it.
+	_, _ = io.Copy(io.Discard, stdout)
+
+	if err := cmd.Wait(); err != nil {
+		if ctx.Err() == context.DeadlineExceeded {
+			return "", fmt.Errorf("command timed out after %s", commandTimeout)
+		}
+		if stderrMsg := strings.TrimSpace(stderr.String()); stderrMsg != "" {
+			return "", fmt.Errorf("%w: %s", err, stderrMsg)
+		}
+		return "", err
+	}
+
+	return string(out), nil
+}

pkg/skills/expand_test.go

@@ -0,0 +1,111 @@
+package skills
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func skipOnWindows(t *testing.T) {
+	t.Helper()
+	if runtime.GOOS == "windows" {
+		t.Skip("skipping on windows")
+	}
+}
+
+func TestExpandCommands(t *testing.T) {
+	skipOnWindows(t)
+
+	tests := []struct {
+		name    string
+		content string
+		want    string
+	}{
+		{
+			name:    "no patterns",
+			content: "# My Skill\n\nJust regular markdown content.",
+			want:    "# My Skill\n\nJust regular markdown content.",
+		},
+		{
+			name:    "simple echo",
+			content: "Hello !`echo world`!",
+			want:    "Hello world!",
+		},
+		{
+			name:    "multiple commands",
+			content: "Name: !`echo alice`, Age: !`echo 30`",
+			want:    "Name: alice, Age: 30",
+		},
+		{
+			name:    "multiline output",
+			content: "Files:\n!`printf 'a.go\nb.go\nc.go\n'`\nEnd.",
+			want:    "Files:\na.go\nb.go\nc.go\nEnd.",
+		},
+		{
+			name:    "empty output",
+			content: "Before !`true` after",
+			want:    "Before  after",
+		},
+		{
+			name:    "pipes",
+			content: "Count: !`printf 'a\nb\nc\n' | wc -l | tr -d ' '`",
+			want:    "Count: 3",
+		},
+		{
+			name:    "preserves regular backticks",
+			content: "Use `echo hello` to print.\n\nCode: ```go\nfmt.Println()\n```",
+			want:    "Use `echo hello` to print.\n\nCode: ```go\nfmt.Println()\n```",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := ExpandCommands(t.Context(), tt.content, t.TempDir())
+			assert.Equal(t, tt.want, result)
+		})
+	}
+}
+
+func TestExpandCommands_WorkingDirectory(t *testing.T) {
+	skipOnWindows(t)
+
+	tmpDir := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(tmpDir, "test.txt"), []byte("hello"), 0o644))
+
+	result := ExpandCommands(t.Context(), "Content: !`cat test.txt`", tmpDir)
+	assert.Equal(t, "Content: hello", result)
+}
+
+func TestExpandCommands_ScriptExecution(t *testing.T) {
+	skipOnWindows(t)
+
+	tmpDir := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(tmpDir, "info.sh"), []byte("#!/bin/sh\necho from-script"), 0o755))
+
+	result := ExpandCommands(t.Context(), "Output: !`./info.sh`", tmpDir)
+	assert.Equal(t, "Output: from-script", result)
+}
+
+func TestExpandCommands_FailedCommand(t *testing.T) {
+	skipOnWindows(t)
+
+	result := ExpandCommands(t.Context(), "Before !`nonexistent_command_12345` after", t.TempDir())
+	assert.Contains(t, result, "Before ")
+	assert.Contains(t, result, "[error executing `nonexistent_command_12345`:")
+	assert.Contains(t, result, " after")
+}
+
+func TestExpandCommands_CancelledContext(t *testing.T) {
+	skipOnWindows(t)
+
+	ctx, cancel := context.WithCancel(t.Context())
+	cancel()
+
+	result := ExpandCommands(ctx, "Result: !`echo hello`", t.TempDir())
+	assert.Contains(t, result, "[error executing `echo hello`:")
+}

pkg/skills/skills.go

@@ -22,6 +22,7 @@ type Skill struct {
 	FilePath      string            `yaml:"-"`
 	BaseDir       string            `yaml:"-"`
 	Files         []string          `yaml:"-"`
+	Local         bool              `yaml:"-"` // true for filesystem-loaded skills, false for remote
 	License       string            `yaml:"license"`
 	Compatibility string            `yaml:"compatibility"`
 	Metadata      map[string]string `yaml:"metadata"`
@@ -308,6 +309,7 @@ func loadSkillFile(path, dirName string) (Skill, bool) {
 	skill.Name = cmp.Or(skill.Name, dirName)
 	skill.FilePath = path
 	skill.BaseDir = filepath.Dir(path)
+	skill.Local = true
 
 	return skill, true
 }

pkg/teamloader/teamloader.go

@@ -218,7 +218,7 @@ func LoadWithConfig(ctx context.Context, agentSource config.Source, runConfig *c
 		if agentConfig.Skills.Enabled() {
 			loadedSkills := skills.Load(agentConfig.Skills.Sources)
 			if len(loadedSkills) > 0 {
-				agentTools = append(agentTools, builtin.NewSkillsToolset(loadedSkills))
+				agentTools = append(agentTools, builtin.NewSkillsToolset(loadedSkills, runConfig.WorkingDir))
 			}
 		}
 

pkg/tools/builtin/skills.go

@@ -25,12 +25,14 @@ var (
 // agent load skill content and supporting resources by name. It hides whether
 // a skill is local or remote — the agent just sees a name and description.
 type SkillsToolset struct {
-	skills []skills.Skill
+	skills     []skills.Skill
+	workingDir string
 }
 
-func NewSkillsToolset(loadedSkills []skills.Skill) *SkillsToolset {
+func NewSkillsToolset(loadedSkills []skills.Skill, workingDir string) *SkillsToolset {
 	return &SkillsToolset{
-		skills: loadedSkills,
+		skills:     loadedSkills,
+		workingDir: workingDir,
 	}
 }
 
@@ -49,7 +51,10 @@ func (s *SkillsToolset) findSkill(name string) *skills.Skill {
 }
 
 // ReadSkillContent returns the content of a skill's SKILL.md by name.
-func (s *SkillsToolset) ReadSkillContent(name string) (string, error) {
+// For local skills, it expands any !`command` patterns in the content by
+// executing the commands and replacing the patterns with their stdout output.
+// Command expansion is disabled for remote skills to prevent arbitrary code execution.
+func (s *SkillsToolset) ReadSkillContent(ctx context.Context, name string) (string, error) {
 	skill := s.findSkill(name)
 	if skill == nil {
 		return "", fmt.Errorf("skill %q not found", name)
@@ -60,6 +65,10 @@ func (s *SkillsToolset) ReadSkillContent(name string) (string, error) {
 		return "", err
 	}
 
+	if skill.Local {
+		content = skills.ExpandCommands(ctx, content, s.workingDir)
+	}
+
 	return content, nil
 }
 
@@ -119,8 +128,8 @@ type readSkillFileArgs struct {
 	Path      string `json:"path" jsonschema:"The relative path to the file within the skill (e.g. references/FORMS.md)"`
 }
 
-func (s *SkillsToolset) handleReadSkill(_ context.Context, args readSkillArgs) (*tools.ToolCallResult, error) {
-	content, err := s.ReadSkillContent(args.Name)
+func (s *SkillsToolset) handleReadSkill(ctx context.Context, args readSkillArgs) (*tools.ToolCallResult, error) {
+	content, err := s.ReadSkillContent(ctx, args.Name)
 	if err != nil {
 		return tools.ResultError(err.Error()), nil
 	}