feat(skills): add Kiro skills adapter and markdown skill parsing

Add Kiro steering file adapter for skills and extend core adapter
to support markdown format with YAML frontmatter. Skills can now
be read from both JSON and markdown canonical formats.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: grokify

skills/core/adapter.go

@@ -7,6 +7,7 @@ import (
 	"os"
 	"path/filepath"
 	"sort"
+	"strings"
 	"sync"
 )
 
@@ -126,13 +127,29 @@ func Convert(data []byte, from, to string) ([]byte, error) {
 	return DefaultRegistry.Convert(data, from, to)
 }
 
-// ReadCanonicalFile reads a canonical skill.json file.
+// ReadCanonicalFile reads a canonical skill file (JSON or Markdown with YAML frontmatter).
 func ReadCanonicalFile(path string) (*Skill, error) {
 	data, err := os.ReadFile(path)
 	if err != nil {
 		return nil, &ReadError{Path: path, Err: err}
 	}
 
+	// Detect format: if it starts with "---" or has .md extension, parse as markdown
+	ext := filepath.Ext(path)
+	if ext == ".md" || (len(data) >= 3 && string(data[:3]) == "---") {
+		skill, err := ParseSkillMarkdown(data)
+		if err != nil {
+			return nil, &ParseError{Format: "markdown", Path: path, Err: err}
+		}
+		// Infer name from filename if not set
+		if skill.Name == "" {
+			base := filepath.Base(path)
+			skill.Name = strings.TrimSuffix(base, filepath.Ext(base))
+		}
+		return skill, nil
+	}
+
+	// Fall back to JSON
 	var skill Skill
 	if err := json.Unmarshal(data, &skill); err != nil {
 		return nil, &ParseError{Format: "canonical", Path: path, Err: err}
@@ -160,7 +177,10 @@ func WriteCanonicalFile(skill *Skill, path string) error {
 	return nil
 }
 
-// ReadCanonicalDir reads all skill.json files from subdirectories.
+// ReadCanonicalDir reads all skill files from a directory.
+// Supports both:
+// - Subdirectories with skill.json files
+// - Direct .md files with YAML frontmatter
 func ReadCanonicalDir(dir string) ([]*Skill, error) {
 	entries, err := os.ReadDir(dir)
 	if err != nil {
@@ -169,10 +189,21 @@ func ReadCanonicalDir(dir string) ([]*Skill, error) {
 
 	var skills []*Skill
 	for _, entry := range entries {
+		// Handle direct .md files (flat structure)
 		if !entry.IsDir() {
+			ext := filepath.Ext(entry.Name())
+			if ext == ".md" {
+				skillPath := filepath.Join(dir, entry.Name())
+				skill, err := ReadCanonicalFile(skillPath)
+				if err != nil {
+					return nil, err
+				}
+				skills = append(skills, skill)
+			}
 			continue
 		}
 
+		// Handle subdirectories with skill.json
 		skillPath := filepath.Join(dir, entry.Name(), "skill.json")
 		if _, err := os.Stat(skillPath); os.IsNotExist(err) {
 			continue
@@ -207,3 +238,74 @@ func WriteSkillsToDir(skills []*Skill, dir string, adapterName string) error {
 
 	return nil
 }
+
+// ParseSkillMarkdown parses a Markdown file with YAML frontmatter into a Skill.
+func ParseSkillMarkdown(data []byte) (*Skill, error) {
+	content := string(data)
+
+	if !strings.HasPrefix(content, "---") {
+		// No frontmatter, treat entire content as instructions
+		return &Skill{Instructions: strings.TrimSpace(content)}, nil
+	}
+
+	parts := strings.SplitN(content, "---", 3)
+	if len(parts) < 3 {
+		return &Skill{Instructions: strings.TrimSpace(content)}, nil
+	}
+
+	skill := &Skill{}
+
+	// Parse simple YAML key: value pairs from frontmatter
+	lines := strings.Split(strings.TrimSpace(parts[1]), "\n")
+	for _, line := range lines {
+		line = strings.TrimSpace(line)
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		idx := strings.Index(line, ":")
+		if idx <= 0 {
+			continue
+		}
+		key := strings.TrimSpace(line[:idx])
+		value := strings.TrimSpace(line[idx+1:])
+		// Remove quotes if present
+		value = strings.Trim(value, "\"'")
+
+		switch key {
+		case "name":
+			skill.Name = value
+		case "description":
+			skill.Description = value
+		case "triggers":
+			skill.Triggers = parseList(value)
+		case "dependencies":
+			skill.Dependencies = parseList(value)
+		case "scripts":
+			skill.Scripts = parseList(value)
+		case "references":
+			skill.References = parseList(value)
+		case "assets":
+			skill.Assets = parseList(value)
+		}
+	}
+
+	// Body becomes instructions
+	skill.Instructions = strings.TrimSpace(parts[2])
+
+	return skill, nil
+}
+
+// parseList parses a comma-separated or bracket-enclosed list.
+func parseList(s string) []string {
+	s = strings.Trim(s, "[]")
+	parts := strings.Split(s, ",")
+	var result []string
+	for _, p := range parts {
+		p = strings.TrimSpace(p)
+		p = strings.Trim(p, "\"'")
+		if p != "" {
+			result = append(result, p)
+		}
+	}
+	return result
+}

skills/kiro/adapter.go

@@ -0,0 +1,163 @@
+// Package kiro provides the Kiro CLI skill adapter for steering files.
+package kiro
+
+import (
+	"bytes"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/agentplexus/assistantkit/skills/core"
+)
+
+const (
+	// AdapterName is the identifier for this adapter.
+	AdapterName = "kiro"
+
+	// SteeringDir is the default steering directory name.
+	SteeringDir = "steering"
+)
+
+func init() {
+	core.Register(&Adapter{})
+}
+
+// Adapter converts between canonical Skill and Kiro CLI steering file format.
+type Adapter struct{}
+
+// Name returns the adapter identifier.
+func (a *Adapter) Name() string {
+	return AdapterName
+}
+
+// SkillFileName returns the skill definition filename.
+// For Kiro, steering files are named <skill-name>.md directly.
+func (a *Adapter) SkillFileName() string {
+	return ".md" // Used as suffix
+}
+
+// DefaultDir returns the default directory name for Kiro steering files.
+func (a *Adapter) DefaultDir() string {
+	return SteeringDir
+}
+
+// Parse converts Kiro steering file bytes to canonical Skill.
+func (a *Adapter) Parse(data []byte) (*core.Skill, error) {
+	content := string(data)
+	lines := strings.SplitN(content, "\n", 2)
+
+	skill := &core.Skill{}
+
+	// Extract name from first line (# Title)
+	if len(lines) > 0 && strings.HasPrefix(lines[0], "# ") {
+		title := strings.TrimPrefix(lines[0], "# ")
+		skill.Name = toKebabCase(title)
+		skill.Description = title
+	}
+
+	// Rest is instructions
+	if len(lines) > 1 {
+		skill.Instructions = strings.TrimSpace(lines[1])
+	}
+
+	return skill, nil
+}
+
+// Marshal converts canonical Skill to Kiro steering file bytes.
+func (a *Adapter) Marshal(skill *core.Skill) ([]byte, error) {
+	var buf bytes.Buffer
+
+	// Write title from name (convert kebab-case to Title Case)
+	title := toTitleCase(skill.Name)
+	buf.WriteString(fmt.Sprintf("# %s\n\n", title))
+
+	// Write description if different from title
+	if skill.Description != "" && skill.Description != title {
+		buf.WriteString(fmt.Sprintf("%s\n\n", skill.Description))
+	}
+
+	// Write instructions directly (they contain the markdown content)
+	if skill.Instructions != "" {
+		buf.WriteString(skill.Instructions)
+		if !strings.HasSuffix(skill.Instructions, "\n") {
+			buf.WriteString("\n")
+		}
+	}
+
+	return buf.Bytes(), nil
+}
+
+// ReadFile reads a Kiro steering file and returns canonical Skill.
+func (a *Adapter) ReadFile(path string) (*core.Skill, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, &core.ReadError{Path: path, Err: err}
+	}
+
+	skill, err := a.Parse(data)
+	if err != nil {
+		if pe, ok := err.(*core.ParseError); ok {
+			pe.Path = path
+		}
+		return nil, err
+	}
+
+	// Infer name from filename if not set
+	if skill.Name == "" {
+		base := filepath.Base(path)
+		skill.Name = strings.TrimSuffix(base, filepath.Ext(base))
+	}
+
+	return skill, nil
+}
+
+// WriteFile writes canonical Skill to a Kiro steering file.
+func (a *Adapter) WriteFile(skill *core.Skill, path string) error {
+	data, err := a.Marshal(skill)
+	if err != nil {
+		return err
+	}
+
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, core.DefaultDirMode); err != nil {
+		return &core.WriteError{Path: path, Err: err}
+	}
+
+	if err := os.WriteFile(path, data, core.DefaultFileMode); err != nil {
+		return &core.WriteError{Path: path, Err: err}
+	}
+
+	return nil
+}
+
+// WriteSkillDir writes the skill as a steering file.
+// For Kiro, skills are flat files in the steering directory, not subdirectories.
+func (a *Adapter) WriteSkillDir(skill *core.Skill, baseDir string) error {
+	// Ensure directory exists
+	if err := os.MkdirAll(baseDir, core.DefaultDirMode); err != nil {
+		return &core.WriteError{Path: baseDir, Err: err}
+	}
+
+	// Write steering file: steering/<skill-name>.md
+	steeringPath := filepath.Join(baseDir, skill.Name+".md")
+	return a.WriteFile(skill, steeringPath)
+}
+
+// toKebabCase converts "Title Case" or "Title-Case" to "title-case".
+func toKebabCase(s string) string {
+	s = strings.ToLower(s)
+	s = strings.ReplaceAll(s, " ", "-")
+	return s
+}
+
+// toTitleCase converts "kebab-case" to "Title Case".
+func toTitleCase(s string) string {
+	words := strings.Split(s, "-")
+	for i, word := range words {
+		if len(word) > 0 {
+			words[i] = strings.ToUpper(word[:1]) + word[1:]
+		}
+	}
+	return strings.Join(words, " ")
+}

skills/skills.go

@@ -36,6 +36,7 @@ import (
 	// Import adapters for side-effect registration
 	_ "github.com/agentplexus/assistantkit/skills/claude"
 	_ "github.com/agentplexus/assistantkit/skills/codex"
+	_ "github.com/agentplexus/assistantkit/skills/kiro"
 )
 
 // Re-export core types for convenience