fix: skills list output

Author: tmm

.changeset/fix-skills-list-root-command.md

@@ -0,0 +1,5 @@
+---
+'incur': patch
+---
+
+Fixed `skills list` not including root command skill.

src/Cli.ts

@@ -697,6 +697,7 @@ async function serveImpl(
           depth: options.sync?.depth ?? 1,
           description: options.description,
           include: options.sync?.include,
+          rootCommand: options.rootCommand,
         })
         if (result.length === 0) {
           writeln('No skills found.')

src/Help.ts

@@ -261,7 +261,10 @@ function envEntries(schema: z.ZodObject<any>) {
 }
 
 /** Extracts option entries from a Zod object schema. */
-function optionEntries(schema: z.ZodObject<any>, alias?: Partial<Record<string, string>> | undefined) {
+function optionEntries(
+  schema: z.ZodObject<any>,
+  alias?: Partial<Record<string, string>> | undefined,
+) {
   const entries: {
     flag: string
     description: string

src/Skill.test.ts

@@ -286,7 +286,7 @@ describe('split', () => {
     expect(files[0]!.content).toMatchInlineSnapshot(`
       "---
       name: gh-auth
-      description: Authenticate with GitHub. Log in, Check status. Run \`gh auth --help\` for usage details.
+      description: Authenticate with GitHub. Run \`gh auth --help\` for usage details.
       requires_bin: gh
       command: gh auth
       ---
@@ -304,7 +304,7 @@ describe('split', () => {
     expect(files[1]!.content).toMatchInlineSnapshot(`
       "---
       name: gh-pr
-      description: Manage pull requests. List PRs, Create PR. Run \`gh pr --help\` for usage details.
+      description: Manage pull requests. Run \`gh pr --help\` for usage details.
       requires_bin: gh
       command: gh pr
       ---
@@ -321,11 +321,9 @@ describe('split', () => {
     `)
   })
 
-  test('depth 1 without group descriptions uses child descriptions', () => {
+  test('depth 1 without group descriptions uses fallback hint', () => {
     const files = Skill.split('gh', commands, 1)
-    expect(files[0]!.content).toContain(
-      'description: Log in, Check status. Run `gh auth --help` for usage details.',
-    )
+    expect(files[0]!.content).toContain('description: Run `gh auth --help` for usage details.')
   })
 
   test('depth 2 groups by first two segments', () => {

src/Skill.ts

@@ -130,15 +130,9 @@ function renderGroup(
   prefix?: string | undefined,
 ): string {
   const groupDesc = prefix ? groups.get(prefix) : undefined
-  const childDescs = cmds.map((c) => c.description).filter(Boolean) as string[]
-  const descParts: string[] = []
-  if (groupDesc) descParts.push(groupDesc.replace(/\.$/, ''))
-  if (childDescs.length > 0)
-    descParts.push(childDescs.map((d) => d.replace(/\.$/, '')).join(', '))
-  const description =
-    descParts.length > 0
-      ? `${descParts.join('. ')}. Run \`${title} --help\` for usage details.`
-      : `Run \`${title} --help\` for usage details.`
+  const description = groupDesc
+    ? `${groupDesc.replace(/\.$/, '')}. Run \`${title} --help\` for usage details.`
+    : `Run \`${title} --help\` for usage details.`
 
   const fm = ['---', `name: ${slugify(title)}`]
   fm.push(`description: ${description}`)

src/SyncSkills.test.ts

@@ -177,6 +177,25 @@ test('list returns empty for CLI with no commands', async () => {
   expect(result).toHaveLength(0)
 })
 
+test('list includes root command skill', async () => {
+  const cli = Cli.create('test', {
+    description: 'A test CLI',
+    run: () => ({ ok: true }),
+  })
+  cli.command('ping', { description: 'Health check', run: () => ({}) })
+
+  const commands = Cli.toCommands.get(cli)!
+  const rootCommand = Cli.toRootDefinition.get(cli as any)!
+  const result = await SyncSkills.list('test', commands, {
+    description: 'A test CLI',
+    rootCommand,
+  })
+
+  const names = result.map((s) => s.name)
+  expect(names).toContain('test')
+  expect(names).toContain('test-ping')
+})
+
 test('list results are sorted alphabetically', async () => {
   const cli = Cli.create('test')
   cli.command('zebra', { description: 'Z command', run: () => ({}) })

src/SyncSkills.ts

@@ -136,7 +136,7 @@ export async function list(
 
   const groups = new Map<string, string>()
   if (description) groups.set(name, description)
-  const entries = collectEntries(commands, [], groups)
+  const entries = collectEntries(commands, [], groups, options.rootCommand)
   const files = Skill.split(name, entries, depth, groups)
 
   const skills: list.Skill[] = []
@@ -191,6 +191,18 @@ export declare namespace list {
     description?: string | undefined
     /** Glob patterns for directories containing SKILL.md files to include. */
     include?: string[] | undefined
+    /** Root command definition (when the CLI itself is a command). */
+    rootCommand?:
+      | {
+          description?: string | undefined
+          args?: any
+          env?: any
+          hint?: string | undefined
+          options?: any
+          output?: any
+          examples?: any[] | undefined
+        }
+      | undefined
   }
   /** A skill entry with install status. */
   type Skill = {

src/e2e.test.ts

@@ -2909,7 +2909,7 @@ describe('.well-known/skills', () => {
     `)
     expect(result.body.skills[0]).toMatchInlineSnapshot(`
       {
-        "description": "Proxy to HTTP API. Run \`app api --help\` for usage details.",
+        "description": "Run \`app api --help\` for usage details.",
         "files": [
           "SKILL.md",
         ],
@@ -2927,7 +2927,7 @@ describe('.well-known/skills', () => {
     expect(result.body).toMatchInlineSnapshot(`
       "---
       name: app-ping
-      description: Health check. Run \`app ping --help\` for usage details.
+      description: Run \`app ping --help\` for usage details.
       requires_bin: app
       command: app ping
       ---