fix(skill): correct and slim the bundled skills; add plivo-first-agent

README.md

@@ -161,7 +161,7 @@ For the full command reference, see [`docs/COMMANDS.md`](docs/COMMANDS.md) (auto
 
 ## For LLM agents
 
-If you're an LLM (Claude, Codex, Cursor, Aider, custom agent) and the user has asked you to do anything Plivo-related — **read [`cli-skill/SKILL.md`](cli-skill/SKILL.md) first**. It's the single-file reference written for agent consumption: every command with its required args, flag table, and "when to use" — plus the universal invariants (`--dry-run`, `--yes` for spend verbs, the stable error-envelope codes, JSON-output rules).
+If you're an LLM (Claude, Codex, Cursor, Aider, custom agent) and the user has asked you to do anything Plivo-related — **read [`cli-skill/SKILL.md`](cli-skill/SKILL.md) first**. It's the single-file reference written for agent consumption: the rules (`--dry-run` before `--yes` for spend and destructive verbs, the stable error-envelope codes, JSON-output rules), a command map, and the behaviour `--help` does not show. For flags, `plivo <command> --help` is the source of truth.
 
 **TL;DR for an agent starting cold:**
 

cmd/skill.go

@@ -9,6 +9,7 @@ import (
 
 	audiostreamingskill "github.com/plivo/plivo-cli/audio-streaming-skill"
 	cliskill "github.com/plivo/plivo-cli/cli-skill"
+	firstagentskill "github.com/plivo/plivo-cli/first-agent-skill"
 	"github.com/plivo/plivo-cli/internal/clierr"
 	"github.com/plivo/plivo-cli/internal/output"
 	siptrunkingskill "github.com/plivo/plivo-cli/sip-trunking-skill"
@@ -35,6 +36,7 @@ var bundledSkills = []bundledSkill{
 		content:  cliskill.SkillMD,
 		summary:  "the CLI reference — use `plivo` instead of raw curl",
 	},
+	{selector: "first-agent", dirName: "plivo-first-agent", content: firstagentskill.SkillMD, summary: "take a new user to a first AI voice agent on a real call"},
 	{selector: "audio-streaming", dirName: "plivo-audio-streaming", content: audiostreamingskill.SkillMD, summary: "connect a WebSocket voice bot to calls with <Stream>"},
 	{selector: "sip-trunking", dirName: "plivo-sip-trunking", content: siptrunkingskill.SkillMD, summary: "connect an AI voice platform over SIP trunking"},
 	{selector: "voice-xml", dirName: "plivo-voice-xml", content: voicexmlskill.SkillMD, summary: "write and fix Plivo Voice XML"},
@@ -85,14 +87,15 @@ var skillCmd = &cobra.Command{
 // skillInstallCmd writes the embedded SKILL.md into the agent skills directory
 // (default ~/.claude/skills/plivo-cli; override with --dir, or --print to stdout).
 var skillInstallCmd = &cobra.Command{
-	Use:   "install [cli|audio-streaming|sip-trunking|voice-xml|all]",
+	Use:   "install [cli|first-agent|audio-streaming|sip-trunking|voice-xml|all]",
 	Short: "Install an agent skill so coding agents auto-load the reference",
 	Long: `Install a Plivo agent skill.
 
 A skill is a single-file reference (SKILL.md) written for LLM coding agents.
 They are bundled in the binary, so this writes them out without a network call.
 
   cli              the CLI reference — use ` + "`plivo`" + ` instead of raw curl
+  first-agent      take a new user to a first AI voice agent on a real call
   audio-streaming  connect a WebSocket voice bot to calls with <Stream>
   sip-trunking     connect an AI voice platform over SIP trunking
   voice-xml        write and fix Plivo Voice XML
@@ -103,11 +106,12 @@ Each skill lands at ~/.claude/skills/<skill>/SKILL.md by default. Use --dir to
 target another agent's skills directory, or --print to write the content to
 stdout so any other tool can capture it; both act on a single skill.`,
 	Example: `  plivo skill install                    # CLI skill -> ~/.claude/skills/plivo-cli/
+  plivo skill install first-agent        # -> ~/.claude/skills/plivo-first-agent/
   plivo skill install voice-xml          # -> ~/.claude/skills/plivo-voice-xml/
   plivo skill install all                # every listed skill
   plivo skill install all --dry-run      # show destinations, write nothing`,
 	Args:      cobra.MaximumNArgs(1),
-	ValidArgs: []string{"cli", "audio-streaming", "sip-trunking", "voice-xml", "all"},
+	ValidArgs: []string{"cli", "first-agent", "audio-streaming", "sip-trunking", "voice-xml", "all"},
 	RunE:      runSkillInstall,
 }
 

cmd/skill_frontmatter_test.go

@@ -0,0 +1,58 @@
+package cmd
+
+import (
+	"regexp"
+	"strings"
+	"testing"
+	"unicode/utf8"
+
+	"gopkg.in/yaml.v3"
+)
+
+var (
+	skillNameRe = regexp.MustCompile(`^[a-z0-9-]{1,64}$`)
+	xmlTagRe    = regexp.MustCompile(`<[A-Za-z/][^>]*>`)
+)
+
+// Loaders with a strict YAML parser, such as the `skills` npm CLI, skip a skill
+// whose frontmatter does not parse. An unquoted ": " inside the description is
+// enough to do that, and Claude Code's tolerant loader hides it.
+func TestBundledSkills_frontmatterFollowsAgentSkillsSpec(t *testing.T) {
+	for _, s := range bundledSkills {
+		t.Run(s.selector, func(t *testing.T) {
+			content := strings.ReplaceAll(s.content, "\r\n", "\n")
+			rest, ok := strings.CutPrefix(content, "---\n")
+			if !ok {
+				t.Fatal("SKILL.md does not open with a frontmatter block")
+			}
+			block, _, ok := strings.Cut(rest, "\n---\n")
+			if !ok {
+				t.Fatal("frontmatter block is not closed")
+			}
+
+			var fm struct {
+				Name        string `yaml:"name"`
+				Description string `yaml:"description"`
+			}
+			if err := yaml.Unmarshal([]byte(block), &fm); err != nil {
+				t.Fatalf("frontmatter is not valid YAML: %v", err)
+			}
+
+			if fm.Name != s.dirName {
+				t.Errorf("name %q does not match the install directory %q", fm.Name, s.dirName)
+			}
+			if !skillNameRe.MatchString(fm.Name) {
+				t.Errorf("name %q must be 1-64 lowercase letters, digits or hyphens", fm.Name)
+			}
+			if fm.Description == "" {
+				t.Error("description is empty")
+			}
+			if n := utf8.RuneCountInString(fm.Description); n > 1024 {
+				t.Errorf("description is %d characters; the limit is 1024", n)
+			}
+			if tag := xmlTagRe.FindString(fm.Description); tag != "" {
+				t.Errorf("description contains the XML tag %q", tag)
+			}
+		})
+	}
+}

cmd/testdata/help/plivo_skill_install.txt

@@ -4,6 +4,7 @@ A skill is a single-file reference (SKILL.md) written for LLM coding agents.
 They are bundled in the binary, so this writes them out without a network call.
 
   cli              the CLI reference — use `plivo` instead of raw curl
+  first-agent      take a new user to a first AI voice agent on a real call
   audio-streaming  connect a WebSocket voice bot to calls with <Stream>
   sip-trunking     connect an AI voice platform over SIP trunking
   voice-xml        write and fix Plivo Voice XML
@@ -15,10 +16,11 @@ target another agent's skills directory, or --print to write the content to
 stdout so any other tool can capture it; both act on a single skill.
 
 Usage:
-  plivo skill install [cli|audio-streaming|sip-trunking|voice-xml|all] [flags]
+  plivo skill install [cli|first-agent|audio-streaming|sip-trunking|voice-xml|all] [flags]
 
 Examples:
   plivo skill install                    # CLI skill -> ~/.claude/skills/plivo-cli/
+  plivo skill install first-agent        # -> ~/.claude/skills/plivo-first-agent/
   plivo skill install voice-xml          # -> ~/.claude/skills/plivo-voice-xml/
   plivo skill install all                # every listed skill
   plivo skill install all --dry-run      # show destinations, write nothing

docs/COMMANDS.md

@@ -3085,6 +3085,7 @@ A skill is a single-file reference (SKILL.md) written for LLM coding agents.
 They are bundled in the binary, so this writes them out without a network call.
 
   cli              the CLI reference — use `plivo` instead of raw curl
+  first-agent      take a new user to a first AI voice agent on a real call
   audio-streaming  connect a WebSocket voice bot to calls with <Stream>
   sip-trunking     connect an AI voice platform over SIP trunking
   voice-xml        write and fix Plivo Voice XML
@@ -3096,13 +3097,14 @@ target another agent's skills directory, or --print to write the content to
 stdout so any other tool can capture it; both act on a single skill.
 
 ```
-plivo skill install [cli|audio-streaming|sip-trunking|voice-xml|all] [flags]
+plivo skill install [cli|first-agent|audio-streaming|sip-trunking|voice-xml|all] [flags]
 ```
 
 Examples:
 
 ```
   plivo skill install                    # CLI skill -> ~/.claude/skills/plivo-cli/
+  plivo skill install first-agent        # -> ~/.claude/skills/plivo-first-agent/
   plivo skill install voice-xml          # -> ~/.claude/skills/plivo-voice-xml/
   plivo skill install all                # every listed skill
   plivo skill install all --dry-run      # show destinations, write nothing