fix(init): address PR review comments

- Add opencode to --tool flag help text
- Fix extractSkillDescription comment (returns 'MDL skill', not the skill name)
- Add yamlSingleQuote() helper; use it in wrapSkillContent to safely escape
  skill names and descriptions in YAML frontmatter
- Update init_test.go assertions to match new single-quoted frontmatter format
- Fix opencode.json doc example to match generateOpenCodeConfig actual output
- Remove false panic claim from runInit test helper comment
- Wire full OpenCode sidecar into cmd_add_tool.go (commands, lint-rules, skills)
- Guard OpenCode lint-rule write with slices.Contains(tools, "claude") to
  prevent duplicate writes when both tools are selected or --all-tools is used
- Capture and handle fs.WalkDir errors in cmd_add_tool.go OpenCode sidecar
- Move success message in cmd_add_tool.go to after the OpenCode sidecar block
- Add .opencode/skills/**/SKILL.md to generateOpenCodeConfig instructions
- Update opencode.md doc example and prose to match generated config
- Rename other-ai-tools.md heading to '# Other AI tools'
- Fix stale link text in opencode.md to match renamed heading
- Nil out vsixData in runInit test helper to prevent external CLI side effects
- Fix lint-rule guard to use resolved 'tools' slice instead of 'initTools'

Author: retran

cmd/mxcli/cmd_add_tool.go

@@ -5,8 +5,10 @@ package main
 
 import (
 	"fmt"
+	"io/fs"
 	"os"
 	"path/filepath"
+	"strings"
 
 	"github.com/spf13/cobra"
 )
@@ -132,6 +134,101 @@ Supported Tools:
 			fmt.Println("  Run 'mxcli init' first to create universal documentation.")
 		}
 
+		// OpenCode sidecar: commands, skills, lint-rules (same as mxcli init)
+		if toolName == "opencode" {
+			opencodeDir := filepath.Join(absDir, ".opencode")
+			opencodeCommandsDir := filepath.Join(opencodeDir, "commands")
+			opencodeSkillsDir := filepath.Join(opencodeDir, "skills")
+			lintRulesDir := filepath.Join(absDir, ".claude", "lint-rules")
+
+			for _, dir := range []string{opencodeCommandsDir, opencodeSkillsDir, lintRulesDir} {
+				if err := os.MkdirAll(dir, 0755); err != nil {
+					fmt.Fprintf(os.Stderr, "  Error creating directory %s: %v\n", dir, err)
+				}
+			}
+
+			cmdCount := 0
+			if err := fs.WalkDir(commandsFS, "commands", func(path string, d fs.DirEntry, err error) error {
+				if err != nil || d.IsDir() {
+					return err
+				}
+				content, err := commandsFS.ReadFile(path)
+				if err != nil {
+					return err
+				}
+				targetPath := filepath.Join(opencodeCommandsDir, d.Name())
+				if _, statErr := os.Stat(targetPath); statErr == nil {
+					return nil // skip existing
+				}
+				if err := os.WriteFile(targetPath, content, 0644); err != nil {
+					return err
+				}
+				cmdCount++
+				return nil
+			}); err != nil {
+				fmt.Fprintf(os.Stderr, "  Error writing OpenCode commands: %v\n", err)
+			} else if cmdCount > 0 {
+				fmt.Printf("  Created %d command files in .opencode/commands/\n", cmdCount)
+			}
+
+			lintCount := 0
+			if err := fs.WalkDir(lintRulesFS, "lint-rules", func(path string, d fs.DirEntry, err error) error {
+				if err != nil || d.IsDir() {
+					return err
+				}
+				content, err := lintRulesFS.ReadFile(path)
+				if err != nil {
+					return err
+				}
+				targetPath := filepath.Join(lintRulesDir, d.Name())
+				if _, statErr := os.Stat(targetPath); statErr == nil {
+					return nil // skip existing
+				}
+				if err := os.WriteFile(targetPath, content, 0644); err != nil {
+					return err
+				}
+				lintCount++
+				return nil
+			}); err != nil {
+				fmt.Fprintf(os.Stderr, "  Error writing lint rules: %v\n", err)
+			} else if lintCount > 0 {
+				fmt.Printf("  Created %d lint rule files in .claude/lint-rules/\n", lintCount)
+			}
+
+			skillCount := 0
+			if err := fs.WalkDir(skillsFS, "skills", func(path string, d fs.DirEntry, err error) error {
+				if err != nil || d.IsDir() {
+					return err
+				}
+				if d.Name() == "README.md" {
+					return nil
+				}
+				content, err := skillsFS.ReadFile(path)
+				if err != nil {
+					return err
+				}
+				skillName := strings.TrimSuffix(d.Name(), ".md")
+				skillDir := filepath.Join(opencodeSkillsDir, skillName)
+				if err := os.MkdirAll(skillDir, 0755); err != nil {
+					return err
+				}
+				targetPath := filepath.Join(skillDir, "SKILL.md")
+				if _, statErr := os.Stat(targetPath); statErr == nil {
+					return nil // skip existing
+				}
+				wrapped := wrapSkillContent(skillName, content)
+				if err := os.WriteFile(targetPath, wrapped, 0644); err != nil {
+					return err
+				}
+				skillCount++
+				return nil
+			}); err != nil {
+				fmt.Fprintf(os.Stderr, "  Error writing OpenCode skills: %v\n", err)
+			} else if skillCount > 0 {
+				fmt.Printf("  Created %d skill directories in .opencode/skills/\n", skillCount)
+			}
+		}
+
 		fmt.Println("\n✓ Tool support added!")
 		fmt.Printf("\nNext steps:\n")
 		fmt.Printf("  1. Open project in %s\n", toolConfig.Name)

cmd/mxcli/init.go

@@ -313,28 +313,33 @@ All tools receive universal documentation in AGENTS.md and .ai-context/
 				}
 
 				lintRuleCount := 0
-				err = fs.WalkDir(lintRulesFS, "lint-rules", func(path string, d fs.DirEntry, err error) error {
-					if err != nil {
-						return err
-					}
-					if d.IsDir() {
+				// Only write lint rules from the OpenCode path when Claude is not also
+				// being initialised — the Claude path already writes the same files to
+				// .claude/lint-rules/ and we don't want duplicate log output or writes.
+				if !slices.Contains(tools, "claude") {
+					err = fs.WalkDir(lintRulesFS, "lint-rules", func(path string, d fs.DirEntry, err error) error {
+						if err != nil {
+							return err
+						}
+						if d.IsDir() {
+							return nil
+						}
+						content, err := lintRulesFS.ReadFile(path)
+						if err != nil {
+							return err
+						}
+						targetPath := filepath.Join(lintRulesDir, d.Name())
+						if err := os.WriteFile(targetPath, content, 0644); err != nil {
+							return err
+						}
+						lintRuleCount++
 						return nil
-					}
-					content, err := lintRulesFS.ReadFile(path)
+					})
 					if err != nil {
-						return err
+						fmt.Fprintf(os.Stderr, "  Error writing lint rules: %v\n", err)
+					} else {
+						fmt.Printf("  Created %d lint rule files in .claude/lint-rules/\n", lintRuleCount)
 					}
-					targetPath := filepath.Join(lintRulesDir, d.Name())
-					if err := os.WriteFile(targetPath, content, 0644); err != nil {
-						return err
-					}
-					lintRuleCount++
-					return nil
-				})
-				if err != nil {
-					fmt.Fprintf(os.Stderr, "  Error writing lint rules: %v\n", err)
-				} else {
-					fmt.Printf("  Created %d lint rule files in .claude/lint-rules/\n", lintRuleCount)
 				}
 
 				skillCount2 := 0
@@ -461,19 +466,28 @@ All tools receive universal documentation in AGENTS.md and .ai-context/
 	},
 }
 
+// yamlSingleQuote wraps s in YAML single quotes and escapes any internal
+// single quotes by doubling them, so the result is safe to embed in a YAML
+// value without further quoting.
+func yamlSingleQuote(s string) string {
+	s = strings.ReplaceAll(s, "\n", " ")
+	s = strings.ReplaceAll(s, "'", "''")
+	return "'" + s + "'"
+}
+
 // wrapSkillContent prepends OpenCode-compatible YAML frontmatter to a skill file.
 // OpenCode requires each skill to live in its own subdirectory as SKILL.md and
 // the file must start with YAML frontmatter containing name, description, and
 // compatibility fields.
 func wrapSkillContent(skillName string, content []byte) []byte {
 	description := extractSkillDescription(content)
-	frontmatter := fmt.Sprintf("---\nname: %s\ndescription: %s\ncompatibility: opencode\n---\n\n", skillName, description)
+	frontmatter := fmt.Sprintf("---\nname: %s\ndescription: %s\ncompatibility: opencode\n---\n\n", yamlSingleQuote(skillName), yamlSingleQuote(description))
 	return append([]byte(frontmatter), content...)
 }
 
 // extractSkillDescription returns a one-line description for the skill by
 // finding the first top-level markdown heading (# ...) and stripping a leading
-// "Skill: " prefix if present.  Falls back to the skill name if no heading is
+// "Skill: " prefix if present.  Falls back to "MDL skill" if no heading is
 // found.
 func extractSkillDescription(content []byte) string {
 	for _, line := range strings.Split(string(content), "\n") {
@@ -1147,7 +1161,7 @@ func init() {
 	rootCmd.AddCommand(initCmd)
 
 	// Add flags for tool selection
-	initCmd.Flags().StringSliceVar(&initTools, "tool", []string{}, "AI tool(s) to configure (claude, cursor, continue, windsurf, aider)")
+	initCmd.Flags().StringSliceVar(&initTools, "tool", []string{}, "AI tool(s) to configure (claude, opencode, cursor, continue, windsurf, aider)")
 	initCmd.Flags().BoolVar(&initAllTools, "all-tools", false, "Initialize for all supported AI tools")
 	initCmd.Flags().BoolVar(&initListTools, "list-tools", false, "List supported AI tools and exit")
 }

cmd/mxcli/init_test.go

@@ -10,14 +10,19 @@ import (
 )
 
 // runInit is a test helper that sets initTools to the given list, invokes the
-// cobra Run closure against dir, then restores the original value.  The
-// function panics if initListTools or initAllTools are left non-default from a
-// previous test.
+// cobra Run closure against dir, then restores the original values.
+// vsixData is set to nil during the call to prevent installVSCodeExtension from
+// invoking the external 'code' CLI or writing .vsix files on CI / dev machines.
 func runInit(t *testing.T, tools []string, dir string) {
 	t.Helper()
-	prev := initTools
-	t.Cleanup(func() { initTools = prev })
+	prevTools := initTools
+	prevVsix := vsixData
+	t.Cleanup(func() {
+		initTools = prevTools
+		vsixData = prevVsix
+	})
 	initTools = tools
+	vsixData = nil // disable VS Code extension installation during tests
 	initCmd.Run(initCmd, []string{dir})
 }
 
@@ -72,11 +77,11 @@ func TestWrapSkillContent_FrontmatterPresent(t *testing.T) {
 	if !strings.HasPrefix(text, "---\n") {
 		t.Errorf("wrapped content should start with '---\\n', got: %q", text[:min(40, len(text))])
 	}
-	if !strings.Contains(text, "name: my-skill\n") {
-		t.Error("frontmatter should contain 'name: my-skill'")
+	if !strings.Contains(text, "name: 'my-skill'\n") {
+		t.Error("frontmatter should contain 'name: 'my-skill''")
 	}
-	if !strings.Contains(text, "description: My Skill\n") {
-		t.Error("frontmatter should contain 'description: My Skill'")
+	if !strings.Contains(text, "description: 'My Skill'\n") {
+		t.Error("frontmatter should contain 'description: 'My Skill''")
 	}
 	if !strings.Contains(text, "compatibility: opencode\n") {
 		t.Error("frontmatter should contain 'compatibility: opencode'")
@@ -217,8 +222,8 @@ func TestInitOpenCode_EachSkillHasValidFrontmatter(t *testing.T) {
 		if !strings.HasPrefix(text, "---\n") {
 			t.Errorf("skill %q: SKILL.md should start with YAML frontmatter '---'", e.Name())
 		}
-		if !strings.Contains(text, "name: "+e.Name()) {
-			t.Errorf("skill %q: SKILL.md frontmatter should contain 'name: %s'", e.Name(), e.Name())
+		if !strings.Contains(text, "name: '"+e.Name()+"'") {
+			t.Errorf("skill %q: SKILL.md frontmatter should contain 'name: '%s''", e.Name(), e.Name())
 		}
 		if !strings.Contains(text, "compatibility: opencode") {
 			t.Errorf("skill %q: SKILL.md should contain 'compatibility: opencode'", e.Name())

cmd/mxcli/tool_templates.go

@@ -347,6 +347,7 @@ func generateOpenCodeConfig(projectName, mprPath string) string {
   "$schema": "https://opencode.ai/config.json",
   "instructions": [
     "AGENTS.md",
+    ".opencode/skills/**/SKILL.md",
     ".ai-context/skills/*.md"
   ]
 }

docs-site/src/tutorial/opencode.md

@@ -46,12 +46,16 @@ my-mendix-project/
 
 ### opencode.json
 
-The `opencode.json` file is OpenCode's primary configuration. It points to `AGENTS.md` for instructions and to the skill files in `.opencode/skills/`:
+The `opencode.json` file is OpenCode's primary configuration. It points to `AGENTS.md` for instructions and to both the OpenCode-format skills in `.opencode/skills/` and the universal skill files in `.ai-context/skills/`:
 
 ```json
 {
-  "instructions": ["AGENTS.md", ".ai-context/skills/*.md"],
-  "model": "anthropic/claude-sonnet-4-5"
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [
+    "AGENTS.md",
+    ".opencode/skills/**/SKILL.md",
+    ".ai-context/skills/*.md"
+  ]
 }
 ```
 
@@ -188,4 +192,4 @@ This creates `.opencode/`, `opencode.json`, and the lint rules without touching
 
 ## Next steps
 
-To understand what the skill files contain and how they guide AI behavior, see [Skills and CLAUDE.md](skills.md). For other supported tools, see [Cursor / Continue.dev / Windsurf](other-ai-tools.md).
+To understand what the skill files contain and how they guide AI behavior, see [Skills and CLAUDE.md](skills.md). For other supported tools, see [Other AI tools (Cursor, Continue.dev, Windsurf, OpenCode)](other-ai-tools.md).

docs-site/src/tutorial/other-ai-tools.md

@@ -1,4 +1,4 @@
-# Cursor / Continue.dev / Windsurf
+# Other AI tools
 
 Claude Code is the default integration, but mxcli also supports OpenCode, Cursor, Continue.dev, Windsurf, and Aider. Each tool gets its own configuration file that teaches the AI about MDL syntax and mxcli commands.