Add usage tracking for Cursor skills

Author: mrdon

internal/clients/claude_code/client.go

@@ -216,16 +216,17 @@ func (c *Client) ListSkills(ctx context.Context, scope *clients.InstallScope) ([
 func (c *Client) ReadSkill(ctx context.Context, name string, scope *clients.InstallScope) (*clients.SkillContent, error) {
 	targetBase := c.determineTargetBase(scope)
 
-	content, baseDir, description, err := skillOps.ReadPromptContent(targetBase, name, "SKILL.md", func(m *metadata.Metadata) string { return m.Skill.PromptFile })
+	result, err := skillOps.ReadPromptContent(targetBase, name, "SKILL.md", func(m *metadata.Metadata) string { return m.Skill.PromptFile })
 	if err != nil {
 		return nil, err
 	}
 
 	return &clients.SkillContent{
 		Name:        name,
-		Description: description,
-		Content:     content,
-		BaseDir:     baseDir,
+		Description: result.Description,
+		Version:     result.Version,
+		Content:     result.Content,
+		BaseDir:     result.BaseDir,
 	}, nil
 }
 

internal/clients/client.go

@@ -69,6 +69,7 @@ type InstalledSkill struct {
 type SkillContent struct {
 	Name        string // Skill name
 	Description string // Skill description from metadata
+	Version     string // Skill version from metadata
 	Content     string // Contents of SKILL.md (or configured prompt file)
 	BaseDir     string // Directory where skill is installed (for resolving @ file references)
 }

internal/clients/cursor/client.go

@@ -419,16 +419,17 @@ func (c *Client) ListSkills(ctx context.Context, scope *clients.InstallScope) ([
 func (c *Client) ReadSkill(ctx context.Context, name string, scope *clients.InstallScope) (*clients.SkillContent, error) {
 	targetBase := c.determineTargetBase(scope)
 
-	content, baseDir, description, err := skillOps.ReadPromptContent(targetBase, name, "SKILL.md", func(m *metadata.Metadata) string { return m.Skill.PromptFile })
+	result, err := skillOps.ReadPromptContent(targetBase, name, "SKILL.md", func(m *metadata.Metadata) string { return m.Skill.PromptFile })
 	if err != nil {
 		return nil, err
 	}
 
 	return &clients.SkillContent{
 		Name:        name,
-		Description: description,
-		Content:     content,
-		BaseDir:     baseDir,
+		Description: result.Description,
+		Version:     result.Version,
+		Content:     result.Content,
+		BaseDir:     result.BaseDir,
 	}, nil
 }
 

internal/handlers/dirartifact/operations.go

@@ -120,21 +120,29 @@ func (o *Operations) GetArtifactDir(targetBase string, artifactName string) stri
 // Returns empty string if not specified, in which case the default will be used.
 type PromptFileGetter func(meta *metadata.Metadata) string
 
+// PromptContent contains the result of reading an artifact's prompt file
+type PromptContent struct {
+	Content     string // The prompt file contents
+	BaseDir     string // Directory where the artifact is installed
+	Description string // Artifact description from metadata
+	Version     string // Artifact version from metadata
+}
+
 // ReadPromptContent reads the prompt/content file for an artifact.
 // promptFileGetter extracts the prompt file from metadata; if nil or returns empty, defaultPromptFile is used.
-func (o *Operations) ReadPromptContent(targetBase string, artifactName string, defaultPromptFile string, promptFileGetter PromptFileGetter) (content string, baseDir string, description string, err error) {
+func (o *Operations) ReadPromptContent(targetBase string, artifactName string, defaultPromptFile string, promptFileGetter PromptFileGetter) (*PromptContent, error) {
 	artifactDir := o.GetArtifactDir(targetBase, artifactName)
 
 	// Check if artifact directory exists
 	if _, err := os.Stat(artifactDir); os.IsNotExist(err) {
-		return "", "", "", fmt.Errorf("artifact not found: %s", artifactName)
+		return nil, fmt.Errorf("artifact not found: %s", artifactName)
 	}
 
 	// Read metadata
 	metaPath := filepath.Join(artifactDir, "metadata.toml")
 	meta, err := metadata.ParseFile(metaPath)
 	if err != nil {
-		return "", "", "", fmt.Errorf("failed to read artifact metadata: %w", err)
+		return nil, fmt.Errorf("failed to read artifact metadata: %w", err)
 	}
 
 	// Determine prompt file
@@ -149,8 +157,13 @@ func (o *Operations) ReadPromptContent(targetBase string, artifactName string, d
 	promptPath := filepath.Join(artifactDir, promptFile)
 	contentBytes, err := os.ReadFile(promptPath)
 	if err != nil {
-		return "", "", "", fmt.Errorf("failed to read prompt content: %w", err)
+		return nil, fmt.Errorf("failed to read prompt content: %w", err)
 	}
 
-	return string(contentBytes), artifactDir, meta.Artifact.Description, nil
+	return &PromptContent{
+		Content:     string(contentBytes),
+		BaseDir:     artifactDir,
+		Description: meta.Artifact.Description,
+		Version:     meta.Artifact.Version,
+	}, nil
 }

internal/mcp/server.go

@@ -6,22 +6,40 @@ import (
 	"os"
 	"path/filepath"
 	"regexp"
+	"time"
 
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 	"github.com/sleuth-io/skills/internal/clients"
+	"github.com/sleuth-io/skills/internal/config"
 	"github.com/sleuth-io/skills/internal/gitutil"
+	"github.com/sleuth-io/skills/internal/logger"
+	"github.com/sleuth-io/skills/internal/repository"
+	"github.com/sleuth-io/skills/internal/stats"
 )
 
+// UsageReporter handles reporting skill usage
+type UsageReporter interface {
+	ReportSkillUsage(skillName, skillVersion string)
+}
+
 // Server provides an MCP server that exposes skill operations
 type Server struct {
-	registry *clients.Registry
+	registry      *clients.Registry
+	usageReporter UsageReporter
 }
 
 // NewServer creates a new MCP server
 func NewServer(registry *clients.Registry) *Server {
-	return &Server{
+	s := &Server{
 		registry: registry,
 	}
+	s.usageReporter = s // Server implements UsageReporter by default
+	return s
+}
+
+// SetUsageReporter sets a custom usage reporter (for testing)
+func (s *Server) SetUsageReporter(reporter UsageReporter) {
+	s.usageReporter = reporter
 }
 
 // ReadSkillInput is the input type for read_skill tool
@@ -69,6 +87,9 @@ func (s *Server) handleReadSkill(ctx context.Context, req *mcp.CallToolRequest,
 	for _, client := range installedClients {
 		content, err := client.ReadSkill(ctx, input.Name, scope)
 		if err == nil {
+			// Report usage (best-effort, won't fail the MCP call)
+			go s.usageReporter.ReportSkillUsage(content.Name, content.Version)
+
 			// Resolve @file references to absolute paths
 			resolvedContent := resolveFileReferences(content.Content, content.BaseDir)
 
@@ -130,3 +151,44 @@ func (s *Server) detectScope(ctx context.Context) (*clients.InstallScope, error)
 		Path:     gitContext.RelativePath,
 	}, nil
 }
+
+// ReportSkillUsage reports usage of a skill to the repository.
+// This function runs in a goroutine and is best-effort - it will not block the MCP call.
+func (s *Server) ReportSkillUsage(skillName, skillVersion string) {
+	log := logger.Get()
+
+	// Create usage event
+	usageEvent := stats.UsageEvent{
+		ArtifactName:    skillName,
+		ArtifactVersion: skillVersion,
+		ArtifactType:    "skill",
+		Timestamp:       time.Now().UTC().Format(time.RFC3339),
+	}
+
+	// Enqueue event (fast, local file write)
+	if err := stats.EnqueueEvent(usageEvent); err != nil {
+		log.Warn("failed to enqueue usage event", "skill", skillName, "error", err)
+		return
+	}
+
+	log.Debug("skill usage enqueued", "name", skillName, "version", skillVersion)
+
+	// Try to flush queue with timeout (network call, but we're already in a goroutine)
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	// Load config to get repository
+	cfg, err := config.Load()
+	if err != nil {
+		return
+	}
+
+	// Create repository instance
+	repo, err := repository.NewFromConfig(cfg)
+	if err != nil {
+		return
+	}
+
+	// Try to flush queue
+	_ = stats.FlushQueue(ctx, repo)
+}

internal/mcp/server_test.go

@@ -5,6 +5,7 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+	"sync"
 	"testing"
 
 	"github.com/modelcontextprotocol/go-sdk/mcp"
@@ -69,10 +70,11 @@ func (m *mockClient) ShouldInstall(ctx context.Context) (bool, error) {
 	return true, nil
 }
 
-func (m *mockClient) addSkill(name, description, content, baseDir string) {
+func (m *mockClient) addSkill(name, description, version, content, baseDir string) {
 	m.skills[name] = &clients.SkillContent{
 		Name:        name,
 		Description: description,
+		Version:     version,
 		Content:     content,
 		BaseDir:     baseDir,
 	}
@@ -81,7 +83,7 @@ func (m *mockClient) addSkill(name, description, content, baseDir string) {
 func TestServer_ReadSkill(t *testing.T) {
 	// Create a mock client with test skills
 	mock := newMockClient()
-	mock.addSkill("test-skill", "A test skill", "# Test Skill\n\nThis is the skill content.", "/tmp/skills/test-skill")
+	mock.addSkill("test-skill", "A test skill", "1.0.0", "# Test Skill\n\nThis is the skill content.", "/tmp/skills/test-skill")
 
 	// Create a registry with just our mock client
 	registry := clients.NewRegistry()
@@ -222,7 +224,7 @@ This skill helps with @example.txt integration testing.
 
 	// Use a mock client that reads from our temp directory
 	mock := newMockClient()
-	mock.addSkill("integration-skill", "An integration test skill", skillContent, skillDir)
+	mock.addSkill("integration-skill", "An integration test skill", "1.0.0", skillContent, skillDir)
 
 	registry := clients.NewRegistry()
 	registry.Register(mock)
@@ -338,3 +340,103 @@ func TestResolveFileReferences(t *testing.T) {
 		})
 	}
 }
+
+// mockUsageReporter captures usage reports for testing
+type mockUsageReporter struct {
+	mu      sync.Mutex
+	reports []usageReport
+	called  chan struct{}
+}
+
+type usageReport struct {
+	skillName    string
+	skillVersion string
+}
+
+func newMockUsageReporter() *mockUsageReporter {
+	return &mockUsageReporter{
+		called: make(chan struct{}, 1),
+	}
+}
+
+func (m *mockUsageReporter) ReportSkillUsage(skillName, skillVersion string) {
+	m.mu.Lock()
+	m.reports = append(m.reports, usageReport{skillName, skillVersion})
+	m.mu.Unlock()
+	select {
+	case m.called <- struct{}{}:
+	default:
+	}
+}
+
+func (m *mockUsageReporter) getReports() []usageReport {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return append([]usageReport{}, m.reports...)
+}
+
+func TestServer_ReadSkill_ReportsUsage(t *testing.T) {
+	// Create a mock client with a test skill
+	mock := newMockClient()
+	mock.addSkill("usage-test-skill", "A skill for testing usage", "2.0.0", "# Usage Test\n\nContent here.", "/tmp/skills/usage-test")
+
+	registry := clients.NewRegistry()
+	registry.Register(mock)
+
+	server := NewServer(registry)
+
+	// Inject mock usage reporter
+	mockReporter := newMockUsageReporter()
+	server.SetUsageReporter(mockReporter)
+
+	// Create and connect MCP server
+	impl := &mcp.Implementation{Name: "skills", Version: "1.0.0"}
+	mcpServer := mcp.NewServer(impl, nil)
+	mcp.AddTool(mcpServer, &mcp.Tool{
+		Name:        "read_skill",
+		Description: "Read a skill's full instructions and content.",
+	}, server.handleReadSkill)
+
+	ctx := context.Background()
+	t1, t2 := mcp.NewInMemoryTransports()
+
+	_, err := mcpServer.Connect(ctx, t1, nil)
+	if err != nil {
+		t.Fatalf("Failed to connect server: %v", err)
+	}
+
+	client := mcp.NewClient(&mcp.Implementation{Name: "test-client", Version: "v1.0.0"}, nil)
+	session, err := client.Connect(ctx, t2, nil)
+	if err != nil {
+		t.Fatalf("Failed to connect client: %v", err)
+	}
+	defer session.Close()
+
+	// Read the skill
+	result, err := session.CallTool(ctx, &mcp.CallToolParams{
+		Name:      "read_skill",
+		Arguments: map[string]any{"name": "usage-test-skill"},
+	})
+	if err != nil {
+		t.Fatalf("CallTool failed: %v", err)
+	}
+	if result.IsError {
+		t.Fatalf("Tool returned error: %v", result.Content)
+	}
+
+	// Wait for the goroutine to call the reporter
+	<-mockReporter.called
+
+	// Verify the usage was reported
+	reports := mockReporter.getReports()
+	if len(reports) != 1 {
+		t.Fatalf("Expected 1 usage report, got %d", len(reports))
+	}
+
+	if reports[0].skillName != "usage-test-skill" {
+		t.Errorf("Expected skill name 'usage-test-skill', got %q", reports[0].skillName)
+	}
+	if reports[0].skillVersion != "2.0.0" {
+		t.Errorf("Expected skill version '2.0.0', got %q", reports[0].skillVersion)
+	}
+}