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

Add support for the Claude Code `!\`command\`` pattern in SKILL.md files.
When a local skill is read, any `!\`command\`` patterns are expanded by
executing the shell command and replacing the pattern with its stdout.
This enables skills to dynamically inject context (e.g. git branch,
PR diff, script output) into the prompt at read time.

Commands run in the agent's configured working directory (from
RuntimeConfig.WorkingDir), not in the skill's own directory, so that
project-relative commands like `git status` work correctly.

Security: command expansion is restricted to local (filesystem) skills.
Remote skills fetched over HTTP are never expanded, preventing
arbitrary code execution from untrusted sources. Command stdout is
capped at 1 MB via io.LimitReader with remaining output drained to
avoid pipe deadlocks.

Assisted-By: docker-agent

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
 	}