feat(skill): add Claude Code skill and stack skill install command (#67)

Add a Claude plugin marketplace structure so the repo can distribute a
Claude Code skill that teaches Claude how to use the stack CLI. The new
`stack skill install` command shells out to the claude CLI to add the
marketplace and install the plugin.

Also skip git-repo validation for `skill install` and `version` so they
work outside git repositories.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: javoire

.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "stackinator",
+  "owner": {
+    "name": "javoire"
+  },
+  "plugins": [
+    {
+      "name": "stack",
+      "source": "./plugins/stack",
+      "description": "Stacked branch management skill for the stack CLI"
+    }
+  ]
+}

README.md

@@ -105,6 +105,25 @@ Or use the interactive helper:
 stack config set
 ```
 
+## Claude Code Skill
+
+Stackinator includes a [Claude Code](https://claude.ai/code) skill that teaches Claude how to manage stacked branches.
+
+### Quick install
+
+```bash
+stack skill install
+```
+
+### Manual install
+
+In Claude Code, run:
+
+```
+/plugin marketplace add javoire/stackinator
+/plugin install stack@stackinator
+```
+
 ## Documentation
 
 - [How It Works](docs/how-it-works.md) - Stack tracking and sync algorithm

cmd/root.go

@@ -54,6 +54,11 @@ The tool helps you create, navigate, and sync stacked branches with minimal over
 		// Set color output flag
 		ui.SetNoColor(noColor)
 
+		// Skip git validation for commands that don't need it
+		if cmd.Annotations["skipGitValidation"] == "true" {
+			return
+		}
+
 		// Validate we're in a git repository
 		gitClient := git.NewGitClient()
 		if _, err := gitClient.GetRepoRoot(); err != nil {

cmd/skill.go

@@ -0,0 +1,64 @@
+package cmd
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+
+	"github.com/javoire/stackinator/internal/ui"
+	"github.com/spf13/cobra"
+)
+
+var skillCmd = &cobra.Command{
+	Use:   "skill",
+	Short: "Manage Claude Code skills",
+	Long:  `Manage Claude Code skills for the stack CLI.`,
+	Annotations: map[string]string{
+		"skipGitValidation": "true",
+	},
+}
+
+var skillInstallCmd = &cobra.Command{
+	Use:   "install",
+	Short: "Install the stack skill for Claude Code",
+	Long: `Install the stack skill so Claude Code knows how to use the stack CLI.
+
+This requires the Claude Code CLI (claude) to be installed.
+See https://claude.ai/code for installation instructions.`,
+	Annotations: map[string]string{
+		"skipGitValidation": "true",
+	},
+	RunE: func(cmd *cobra.Command, args []string) error {
+		return runSkillInstall()
+	},
+}
+
+func init() {
+	skillCmd.AddCommand(skillInstallCmd)
+	rootCmd.AddCommand(skillCmd)
+}
+
+func runSkillInstall() error {
+	if _, err := exec.LookPath("claude"); err != nil {
+		return fmt.Errorf("claude CLI not found in PATH. Install it from https://claude.ai/code")
+	}
+
+	fmt.Println("Adding stackinator marketplace...")
+	addCmd := exec.Command("claude", "plugin", "marketplace", "add", "javoire/stackinator")
+	addCmd.Stdout = os.Stdout
+	addCmd.Stderr = os.Stderr
+	if err := addCmd.Run(); err != nil {
+		return fmt.Errorf("failed to add marketplace: %w", err)
+	}
+
+	fmt.Println("Installing stack skill...")
+	installCmd := exec.Command("claude", "plugin", "install", "stack@stackinator")
+	installCmd.Stdout = os.Stdout
+	installCmd.Stderr = os.Stderr
+	if err := installCmd.Run(); err != nil {
+		return fmt.Errorf("failed to install skill: %w", err)
+	}
+
+	fmt.Println(ui.Success("Stack skill installed! Claude Code now knows how to use the stack CLI."))
+	return nil
+}

cmd/skill_test.go

@@ -0,0 +1,32 @@
+package cmd
+
+import (
+	"os"
+	"os/exec"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestRunSkillInstall_ClaudeNotFound(t *testing.T) {
+	// Set PATH to empty so claude can't be found
+	originalPath := os.Getenv("PATH")
+	t.Setenv("PATH", "")
+	defer func() { os.Setenv("PATH", originalPath) }()
+
+	// Clear the exec.LookPath cache by ensuring fresh lookup
+	err := runSkillInstall()
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "claude CLI not found")
+}
+
+func TestRunSkillInstall_ClaudeFound(t *testing.T) {
+	// Skip if claude is not installed
+	if _, err := exec.LookPath("claude"); err != nil {
+		t.Skip("claude CLI not installed, skipping integration test")
+	}
+
+	// This would actually run the commands, so we just verify claude is found
+	// A full integration test would require mocking exec.Command
+	t.Log("claude CLI found in PATH")
+}

cmd/version.go

@@ -17,6 +17,9 @@ var versionCmd = &cobra.Command{
 	Use:   "version",
 	Short: "Print version information",
 	Long:  `Print the version, commit hash, and build date of this stack binary.`,
+	Annotations: map[string]string{
+		"skipGitValidation": "true",
+	},
 	Run: func(cmd *cobra.Command, args []string) {
 		fmt.Printf("stack version %s\n", version)
 		fmt.Printf("  commit: %s\n", commit)

docs/commands.md

@@ -154,6 +154,16 @@ Flags:
 
 - `--prune` - Remove worktrees for branches with merged PRs
 
+## `stack skill install`
+
+Install the Claude Code skill so Claude knows how to use the stack CLI.
+
+Requires the [Claude Code CLI](https://claude.ai/code) to be installed.
+
+```bash
+stack skill install
+```
+
 ## `stack version`
 
 Print version information.

plugins/stack/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "stack",
+  "description": "Stacked branch management skill for the stack CLI",
+  "version": "1.0.0"
+}

plugins/stack/skills/stack/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: stack
+description: Manage stacked branches with the stack CLI. Covers branch creation, navigation, syncing, and PR management.
+---
+
+The `stack` CLI manages stacked branches and syncs them to GitHub PRs. Use this for working with dependent branches.
+
+## Choosing Between `stack worktree` vs `stack new`
+
+- **`stack worktree <branch>`** - Creates a separate git worktree directory at `~/.stack/worktrees/<repo>/<branch>`. Use when:
+  - Starting a new feature from master
+  - Want to work on multiple things in parallel without stashing
+  - The current worktree has uncommitted changes you want to keep
+
+- **`stack new <branch>`** - Creates a branch in the current worktree. Use when:
+  - Building on top of the current feature branch (stacked PRs)
+  - Already in a worktree and want to add dependent branches
+
+## Common Commands
+
+- `stack new <branch>` - Create new branch in the stack (use instead of `git checkout -b`)
+- `stack status` - Show stack structure with PR status (fetches from GitHub)
+- `stack show` - Show local stack structure (fast, no network)
+- `stack sync` - Sync branches and update PRs on GitHub
+- `stack up` / `stack down` - Navigate up/down the stack
+- `stack prune` - Clean up merged branches
+- `stack reparent <parent>` - Change the parent branch
+- `stack rename <name>` - Rename the current branch
+- `stack worktree` - Create a git worktree for parallel work
+
+## Workflow
+
+1. Start a new feature from master: `stack worktree feature-name`
+   - Or use `stack new feature-name` if building stacked PRs on a feature branch
+2. Make changes and commit
+3. Sync to GitHub: `stack sync` (creates/updates PR)
+4. Check status: `stack status`
+5. After merge: `stack prune` to clean up
+
+Run `stack --help` for full documentation.