@frontera-sdk/cli 0.1.0 → 1.43.6

package/src/commands/secret/index-commands.ts

@@ -0,0 +1,195 @@
+import { PlatformApi } from '../../api/platform-api'
+import { CliError, UsageError } from '../../errors'
+import { readSecretValue } from '../../secrets'
+import { table } from '../../table'
+import { flagString, type Command } from '../types'
+
+/**
+ * Workspace secrets.
+ *
+ * The reason this noun exists: an automation names a secret rather than
+ * carrying its value — `ctx.http`'s `auth: { secret }` — and until now the CLI
+ * could deploy that automation while nothing could create the secret it named.
+ * The value therefore had to be typed into the Console by hand, which is the
+ * one step an FDE cannot script.
+ *
+ * A value NEVER arrives as a flag. `--value hunter2` lands in shell history and
+ * in the process list on a shared machine, and a CLI that accepts it will have
+ * it used, so the inline form is refused rather than discouraged.
+ */
+
+/** Same rule the service enforces, checked here to save a round trip. */
+const NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/
+
+interface SecretRow {
+  name?: string
+  description?: string | null
+  type?: string | null
+  provider?: string | null
+  updatedAt?: string | null
+  dependents?: Array<{ kind?: string; displayName?: string; name?: string }>
+}
+
+async function requireWorkspaceId(api: PlatformApi): Promise<string> {
+  const me = await api.whoami()
+  if (!me.workspaceId) {
+    throw new CliError('this credential is not scoped to a workspace', {
+      code: 'FORBIDDEN',
+      hint: 'use a workspace key (sk-ws-…) created for the workspace you mean',
+    })
+  }
+  return me.workspaceId
+}
+
+const list: Command = {
+  meta: {
+    noun: 'secret',
+    verb: 'list',
+    args: [],
+    flags: {},
+    summary: 'List secret names in this workspace — never their values',
+    examples: ['frontera secret list', 'frontera secret list --json'],
+  },
+  async run(ctx) {
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const rows = (await api.workspaceSecrets(await requireWorkspaceId(api))) as SecretRow[]
+
+    return {
+      data: rows,
+      text:
+        rows.length === 0
+          ? 'No secrets in this workspace.'
+          : table(
+              // `used by` is what makes a delete decision possible without
+              // opening the Console — the service computes it from every path a
+              // credential is actually reached through.
+              ['name', 'used by', 'description'],
+              rows.map((s) => [
+                s.name ?? '?',
+                (s.dependents ?? [])
+                  .map((d) => d.displayName ?? d.name ?? d.kind ?? '')
+                  .filter(Boolean)
+                  .join(', '),
+                s.description ?? '',
+              ]),
+              [undefined, 40, 40],
+            ),
+    }
+  },
+}
+
+const set: Command = {
+  meta: {
+    noun: 'secret',
+    verb: 'set',
+    args: [
+      {
+        name: 'name',
+        required: true,
+        description: 'UPPER_SNAKE_CASE name an automation or install refers to',
+      },
+    ],
+    flags: { from: 'string', description: 'string' },
+    summary: 'Create or replace a secret, reading the value from stdin or a file',
+    examples: [
+      'op read op://vault/stripe/key | frontera secret set STRIPE_API_KEY --from -',
+      'frontera secret set STRIPE_API_KEY --from ./key.txt',
+    ],
+  },
+  async run(ctx) {
+    const name = ctx.positional[0]
+    if (!name) {
+      throw new UsageError('missing <name>', 'frontera secret set <NAME> --from - (or --from ./file)')
+    }
+    if (!NAME_PATTERN.test(name)) {
+      throw new UsageError(
+        `"${name}" is not a valid secret name`,
+        'uppercase letters, digits and underscores, starting with a letter — e.g. STRIPE_API_KEY',
+      )
+    }
+
+    const from = flagString(ctx, 'from')
+    if (!from) {
+      throw new UsageError(
+        'missing --from',
+        // Named rather than implied: a caller that has to guess will guess an
+        // inline flag, which is the thing this refuses.
+        'pass `--from -` to read the value from stdin, or `--from ./file` to read it from a file',
+      )
+    }
+
+    // Trailing newline stripped: `echo secret | …` and `op read …` both add one,
+    // and a credential that differs from the intended value by an invisible byte
+    // fails at the far end of an integration with no clue why.
+    const value = (await readSecretValue(from)).replace(/\r?\n$/, '')
+    if (value.length === 0) {
+      throw new CliError('the value read was empty', {
+        code: 'USAGE',
+        hint: from === '-' ? 'nothing arrived on stdin — is the pipe connected?' : `${from} is empty`,
+      })
+    }
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    const workspaceId = await requireWorkspaceId(api)
+    const description = flagString(ctx, 'description')
+
+    // List, then create or replace. The service has no upsert, and choosing by
+    // NAME rather than by the shape of a failure is what makes this reliable:
+    // the first version of this command decided from the error and silently
+    // stopped replacing anything the day a duplicate stopped being a CONFLICT.
+    const existing = (await api.workspaceSecrets(workspaceId)) as SecretRow[]
+    const existed = existing.some((s) => s.name === name)
+
+    if (existed) {
+      await api.updateWorkspaceSecret(workspaceId, name, { value, description })
+    } else {
+      // A concurrent create — two people seeding the same workspace — is the one
+      // case the list cannot rule out, so a CONFLICT here becomes the replace it
+      // was always going to be rather than an error the caller must interpret.
+      await api.createWorkspaceSecret(workspaceId, { name, value, description }).catch(
+        async (err: unknown) => {
+          if ((err as { code?: string }).code !== 'CONFLICT') throw err
+          await api.updateWorkspaceSecret(workspaceId, name, { value, description })
+        },
+      )
+    }
+
+    return {
+      data: { name, action: existed ? 'replaced' : 'created' },
+      // The value is never echoed, not even truncated — a prefix of a key is
+      // still a prefix of a key, and this text lands in CI logs.
+      text: [
+        `${existed ? 'replaced' : 'created'} ${name}`,
+        `  reference it from an automation as auth: { secret: '${name}' }, and grant secret:${name}`,
+      ].join('\n'),
+    }
+  },
+}
+
+const remove: Command = {
+  meta: {
+    noun: 'secret',
+    verb: 'delete',
+    args: [{ name: 'name', required: true, description: 'secret name, from `frontera secret list`' }],
+    flags: {},
+    summary: 'Delete a secret, unless something still depends on it',
+    examples: ['frontera secret delete STRIPE_API_KEY'],
+  },
+  async run(ctx) {
+    const name = ctx.positional[0]
+    if (!name) throw new UsageError('missing <name>', 'frontera secret list — then pass a name')
+
+    const api = new PlatformApi(ctx.apiUrl, ctx.token)
+    await api.deleteWorkspaceSecret(await requireWorkspaceId(api), name)
+
+    // No `--force`. The service refuses while anything still resolves the
+    // secret and says what, and an override here would only move the outage
+    // from this command to whatever was depending on it.
+    return {
+      data: { name, deleted: true },
+      text: `deleted ${name}`,
+    }
+  },
+}
+
+export const secretCommands: Command[] = [list, set, remove]

package/src/commands/skill/bundle-commands.ts

@@ -0,0 +1,327 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, sep } from 'node:path'
+
+import matter from 'gray-matter'
+
+import { PlatformApi } from '../../api/platform-api'
+import { CliError, UsageError } from '../../errors'
+import { flagBool, flagString, type Command } from '../types'
+import { resolveSkillRef } from './resolve'
+
+/**
+ * Folder-based skill authoring: `pull` hydrates a bundle directory from the
+ * platform, `push` upserts one from disk. The layout is the same one the web
+ * ZIP round-trip uses (docs/workspace-skill-bundles.md):
+ *
+ *   my-skill/
+ *   ├── SKILL.md      frontmatter + body
+ *   ├── refs/         markdown references, inlined
+ *   ├── scripts/      text scripts, inlined as fenced code (never executed)
+ *   └── anything else — an asset, path kept verbatim
+ *
+ * `visible` assets are marked in SKILL.md frontmatter as `visibleAssets:` (a
+ * list of asset paths) so the flag survives the round-trip without inventing a
+ * sidecar metadata file.
+ */
+
+interface SkillDoc {
+  id?: string
+  name?: string
+  displayName?: string
+  trigger?: string
+  description?: string
+  keywords?: string[] | null
+  body?: string
+  references?: Array<{ filename: string; content: string }> | null
+  scripts?: Array<{ path: string; content: string }> | null
+  assets?: Array<{
+    path: string
+    storageKey: string
+    mime: string
+    bytes: number
+    sha256: string
+    visible?: boolean
+  }> | null
+  enabled?: boolean
+  sortOrder?: number
+}
+
+const REF_DIRS = ['refs', 'references'] as const
+const SCRIPT_DIR = 'scripts'
+
+const MIME_BY_EXT: Record<string, string> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  webp: 'image/webp',
+  gif: 'image/gif',
+  woff2: 'font/woff2',
+  woff: 'font/woff',
+  ttf: 'font/ttf',
+  css: 'text/css',
+  csv: 'text/csv',
+  json: 'application/json',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+}
+
+function mimeFromPath(path: string): string {
+  return MIME_BY_EXT[path.split('.').pop()?.toLowerCase() ?? ''] ?? 'application/octet-stream'
+}
+
+/** `workspace/{ws}/skill-assets/{sha}.{ext}` → `{sha}.{ext}`, or null. */
+function assetFilename(storageKey: string): string | null {
+  const m = /^workspace\/[^/]+\/skill-assets\/([0-9a-f]{6,64}\.[A-Za-z0-9]+)$/.exec(storageKey)
+  return m ? m[1]! : null
+}
+
+function toSkillMd(doc: SkillDoc): string {
+  const data: Record<string, unknown> = { name: doc.name }
+  if (doc.displayName != null) data.displayName = doc.displayName
+  if (doc.trigger != null) data.trigger = doc.trigger
+  if (doc.description != null) data.description = doc.description
+  if (doc.keywords?.length) data.keywords = doc.keywords
+  if (doc.enabled != null) data.enabled = doc.enabled
+  if (typeof doc.sortOrder === 'number') data.sortOrder = doc.sortOrder
+  const visible = (doc.assets ?? []).filter((a) => a.visible).map((a) => a.path)
+  if (visible.length) data.visibleAssets = visible
+  return matter.stringify(doc.body ?? '', data)
+}
+
+/**
+ * Write one bundle file under `dir`. `rel` comes from the server (asset/script
+ * paths); the upsert validates it, but a compromised or older server must not
+ * be able to write outside the bundle directory — reject rather than trust.
+ */
+function writeBundleFile(dir: string, rel: string, content: string | Uint8Array): void {
+  if (!rel || rel.startsWith('/') || rel.split('/').some((seg) => seg === '..' || seg === '')) {
+    throw new CliError(`refusing to write "${rel}" — path escapes the bundle directory`, {
+      code: 'VALIDATION',
+      hint: 'fix the asset/script path on the server and pull again',
+    })
+  }
+  const path = join(dir, ...rel.split('/'))
+  mkdirSync(dirname(path), { recursive: true })
+  if (typeof content === 'string') writeFileSync(path, content, 'utf8')
+  else writeFileSync(path, content)
+}
+
+const pull: Command = {
+  meta: {
+    noun: 'skill',
+    verb: 'pull',
+    args: [{ name: 'skill', required: true, description: 'skill name or id, from `frontera skill list`' }],
+    flags: { dir: 'string', force: 'boolean' },
+    summary: 'Hydrate a skill bundle folder (SKILL.md, refs/, scripts/, assets) from the platform',
+    examples: [
+      'frontera skill pull brand-guidelines',
+      'frontera skill pull brand-guidelines --dir ~/skills/brand-guidelines --force',
+    ],
+    optionalProject: true,
+  },
+
+  async run(ctx) {
+    const ref = ctx.positional[0]
+    if (!ref) throw new UsageError('missing <skill>', 'frontera skill pull <skill> [--dir <path>]')
+
+    const client = new PlatformApi(ctx.apiUrl, ctx.token)
+    const id = await resolveSkillRef(client, ref)
+    const doc = (await client.workspaceSkill(id)) as SkillDoc
+    if (!doc.name) throw new CliError('skill has no name', { code: 'INTERNAL_ERROR', hint: 'run `frontera skill list` and pull by id' })
+
+    const dir = flagString(ctx, 'dir') ?? join(ctx.cwd, doc.name)
+    const skillMdPath = join(dir, 'SKILL.md')
+    if (existsSync(skillMdPath) && !flagBool(ctx, 'force')) {
+      throw new CliError(`refusing to overwrite ${skillMdPath}`, {
+        code: 'CONFLICT',
+        hint: 're-run with --force to replace the bundle in place',
+      })
+    }
+
+    mkdirSync(dirname(skillMdPath), { recursive: true })
+    writeFileSync(skillMdPath, toSkillMd(doc), 'utf8')
+    const written: string[] = ['SKILL.md']
+
+    for (const ref of doc.references ?? []) {
+      writeBundleFile(dir, `refs/${ref.filename}`, ref.content)
+      written.push(`refs/${ref.filename}`)
+    }
+    for (const script of doc.scripts ?? []) {
+      writeBundleFile(dir, script.path, script.content)
+      written.push(script.path)
+    }
+
+    // Assets need the workspace segment for the download route; a workspace
+    // key resolves its own scope, so whoami is authoritative.
+    const assets = doc.assets ?? []
+    if (assets.length > 0) {
+      const who = await client.whoami()
+      if (!who.workspaceId) {
+        throw new CliError('cannot download assets without a workspace scope', {
+          code: 'FORBIDDEN',
+          hint: 'use a workspace-scoped API key',
+        })
+      }
+      for (const asset of assets) {
+        const filename = assetFilename(asset.storageKey)
+        if (!filename) continue
+        const bytes = await client.downloadSkillAsset(who.workspaceId, filename)
+        writeBundleFile(dir, asset.path, bytes)
+        written.push(`${asset.path}${asset.visible ? ' *' : ''}`)
+      }
+    }
+
+    return {
+      data: { name: doc.name, dir, files: written },
+      text: [`pulled ${doc.name} → ${dir}`, ...written.map((f) => `  ${f}`)].join('\n'),
+    }
+  },
+}
+
+/** Walk a bundle dir, classify every file the way the web importer does. */
+export function readBundle(dir: string): {
+  skillMd: string
+  references: Array<{ filename: string; content: string }>
+  scripts: Array<{ path: string; content: string }>
+  assetFiles: Array<{ path: string; bytes: Uint8Array }>
+} {
+  const skillMdPath = join(dir, 'SKILL.md')
+  if (!existsSync(skillMdPath)) {
+    throw new CliError(`no SKILL.md in ${dir}`, {
+      code: 'NOT_FOUND',
+      hint: 'point at a bundle folder — see docs/workspace-skill-bundles.md',
+    })
+  }
+
+  const references: Array<{ filename: string; content: string }> = []
+  const scripts: Array<{ path: string; content: string }> = []
+  const assetFiles: Array<{ path: string; bytes: Uint8Array }> = []
+  const fatalUtf8 = new TextDecoder('utf-8', { fatal: true })
+
+  const walk = (current: string): void => {
+    for (const entry of readdirSync(current)) {
+      const full = join(current, entry)
+      const rel = relative(dir, full).split(sep).join('/')
+      const base = entry
+      if (base === '.DS_Store' || base.startsWith('._') || base === 'Thumbs.db' || base === '.git') continue
+      if (statSync(full).isDirectory()) {
+        walk(full)
+        continue
+      }
+      if (rel === 'SKILL.md') continue
+      const [top] = rel.split('/')
+      if ((REF_DIRS as readonly string[]).includes(top!)) {
+        references.push({ filename: rel.split('/').slice(1).join('/'), content: readFileSync(full, 'utf8') })
+        continue
+      }
+      if (top === SCRIPT_DIR) {
+        try {
+          scripts.push({ path: rel, content: fatalUtf8.decode(readFileSync(full)) })
+        } catch {
+          throw new CliError(`script "${rel}" is not valid UTF-8 text`, {
+            code: 'VALIDATION',
+            hint: 'scripts/ may only contain text files — put binaries under assets/',
+          })
+        }
+        continue
+      }
+      // Loose markdown is neither reference nor asset — same rule as the web
+      // importer, which ignores it rather than guessing.
+      if (rel.endsWith('.md')) continue
+      assetFiles.push({ path: rel, bytes: new Uint8Array(readFileSync(full)) })
+    }
+  }
+  walk(dir)
+
+  references.sort((a, b) => a.filename.localeCompare(b.filename))
+  scripts.sort((a, b) => a.path.localeCompare(b.path))
+  assetFiles.sort((a, b) => a.path.localeCompare(b.path))
+  return { skillMd: readFileSync(skillMdPath, 'utf8'), references, scripts, assetFiles }
+}
+
+const push: Command = {
+  meta: {
+    noun: 'skill',
+    verb: 'push',
+    args: [{ name: 'dir', required: false, description: 'bundle folder (default: current directory)' }],
+    flags: { dir: 'string' },
+    summary: 'Create or update a workspace skill from a bundle folder, uploading its assets',
+    examples: ['frontera skill push ./brand-guidelines', 'frontera skill push'],
+    optionalProject: true,
+  },
+
+  async run(ctx) {
+    const dir = ctx.positional[0] ?? flagString(ctx, 'dir') ?? ctx.cwd
+    const bundle = readBundle(dir)
+
+    const parsed = matter(bundle.skillMd)
+    const fm = parsed.data as Record<string, unknown>
+    const name = typeof fm.name === 'string' ? fm.name.trim() : ''
+    if (!name) {
+      throw new CliError('SKILL.md frontmatter is missing "name"', {
+        code: 'VALIDATION',
+        hint: 'the frontmatter name is the canonical identity — folder names are cosmetic',
+      })
+    }
+    const visibleAssets = Array.isArray(fm.visibleAssets)
+      ? fm.visibleAssets.filter((v): v is string => typeof v === 'string')
+      : []
+
+    const api = client(ctx)
+    const assets: NonNullable<SkillDoc['assets']> = []
+    for (const file of bundle.assetFiles) {
+      const mime = mimeFromPath(file.path)
+      const uploaded = await api.uploadSkillAsset(file.bytes, file.path.split('/').pop()!, mime)
+      const sha = assetFilename(uploaded.storagePath)?.split('.')[0] ?? ''
+      assets.push({
+        path: file.path,
+        storageKey: uploaded.storagePath,
+        mime: uploaded.mediaType || mime,
+        bytes: file.bytes.length,
+        sha256: sha,
+        ...(visibleAssets.includes(file.path) ? { visible: true } : {}),
+      })
+    }
+
+    const skill = {
+      name,
+      displayName: typeof fm.displayName === 'string' ? fm.displayName : undefined,
+      trigger: typeof fm.trigger === 'string' && fm.trigger.trim() ? fm.trigger.trim() : undefined,
+      description: typeof fm.description === 'string' ? fm.description : undefined,
+      keywords: Array.isArray(fm.keywords)
+        ? fm.keywords.filter((k): k is string => typeof k === 'string')
+        : undefined,
+      body: parsed.content.replace(/^\n+/, ''),
+      references: bundle.references.length ? bundle.references : undefined,
+      scripts: bundle.scripts.length ? bundle.scripts : undefined,
+      assets: assets.length ? assets : undefined,
+      enabled: typeof fm.enabled === 'boolean' ? fm.enabled : undefined,
+      sortOrder: typeof fm.sortOrder === 'number' ? fm.sortOrder : undefined,
+    }
+
+    const summary = await api.importWorkspaceSkills([skill])
+    if (summary.errors?.length) {
+      throw new CliError(`push failed: ${summary.errors[0]!.message}`, {
+        code: 'VALIDATION',
+        hint: 'fix the bundle and re-run `frontera skill push`',
+      })
+    }
+
+    const verb = summary.created > 0 ? 'created' : 'updated'
+    return {
+      data: { name, ...summary, assets: assets.length, scripts: bundle.scripts.length, references: bundle.references.length },
+      text:
+        `${verb} ${name} — ${bundle.references.length} reference(s), ` +
+        `${bundle.scripts.length} script(s), ${assets.length} asset(s)` +
+        (assets.some((a) => a.visible) ? ` (${assets.filter((a) => a.visible).length} visible)` : ''),
+    }
+  },
+}
+
+// One PlatformApi per run is enough; a tiny helper keeps push readable.
+function client(ctx: { apiUrl: string; token: string }): PlatformApi {
+  return new PlatformApi(ctx.apiUrl, ctx.token)
+}
+
+export const skillBundleCommands: Command[] = [pull, push]

package/src/commands/skill/index-commands.ts

@@ -1,7 +1,9 @@
 import { PlatformApi } from '../../api/platform-api'
-import { CliError, UsageError } from '../../errors'
+import { UsageError } from '../../errors'
 import { table } from '../../table'
 import type { Command } from '../types'
+import { resolveSkillRef } from './resolve'
+import { skillBundleCommands } from './bundle-commands'
 
 interface SkillRow {
   id?: string
@@ -16,30 +18,6 @@ interface SkillRow {
  * harness and is written by `frontera init`, and it is not `frontera app add`,
  * which copies registry source into a project. One word, one meaning.
  */
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
-
-async function resolveSkillRef(client: PlatformApi, ref: string): Promise<string> {
-  if (UUID.test(ref)) return ref
-
-  const rows = (await client.workspaceSkills()) as SkillRow[]
-  const match =
-    rows.find((s) => (s.name ?? '').toLowerCase() === ref.toLowerCase()) ??
-    rows.find((s) => (s.displayName ?? '').toLowerCase() === ref.toLowerCase())
-  if (match?.id) return match.id
-
-  const near = rows
-    .filter((s) => `${s.name ?? ''} ${s.displayName ?? ''}`.toLowerCase().includes(ref.toLowerCase()))
-    .map((s) => s.name)
-    .filter(Boolean)
-
-  throw new CliError(`no skill named "${ref}"`, {
-    code: 'NOT_FOUND',
-    hint:
-      near.length > 0
-        ? `did you mean ${near.slice(0, 3).join(', ')}?`
-        : 'run `frontera skill list` to see names and ids',
-  })
-}
 
 const list: Command = {
   meta: {
@@ -91,6 +69,8 @@ const get: Command = {
       trigger?: string
       keywords?: string[] | null
       references?: Array<{ filename?: string }> | null
+      scripts?: Array<{ path?: string }> | null
+      assets?: Array<{ path?: string; visible?: boolean }> | null
     }
 
     // The body is markdown a person reads, and JSON-encoding it turns every
@@ -102,6 +82,16 @@ const get: Command = {
       ['trigger', doc.trigger],
       ['keywords', doc.keywords?.join(', ')],
       ['references', doc.references?.map((r) => r.filename).filter(Boolean).join(', ')],
+      ['scripts', doc.scripts?.map((s) => s.path).filter(Boolean).join(', ')],
+      // Bundled binaries. `*` marks the ones loaded into model context on every
+      // skill load, since that is the line item with an ongoing token cost.
+      [
+        'assets',
+        doc.assets
+          ?.map((a) => `${a.path}${a.visible ? ' *' : ''}`)
+          .filter(Boolean)
+          .join(', '),
+      ],
     ].filter(([, v]) => v) as Array<[string, string]>
 
     return {
@@ -115,26 +105,30 @@ const get: Command = {
   },
 }
 
-const RESERVED = 'skill writes are not available in this release; list and get are read-only'
-
-const reserved: Command[] = (
-  [
-    ['apply', 'Create or update a workspace skill from a document'],
-    ['delete', 'Delete a workspace skill'],
-  ] as const
-).map(([verb, summary]) => ({
+const remove: Command = {
   meta: {
     noun: 'skill',
-    verb,
-    args: [],
+    verb: 'delete',
+    args: [{ name: 'skill', required: true, description: 'skill name or id, from `frontera skill list`' }],
     flags: {},
-    summary,
-    examples: [`frontera skill ${verb} <id>`],
-    reserved: RESERVED,
+    summary: 'Delete a workspace skill and its bindings to agents',
+    examples: ['frontera skill delete brand-guidelines'],
   },
-  async run(): Promise<never> {
-    throw new Error(RESERVED)
+  async run(ctx) {
+    const ref = ctx.positional[0]
+    if (!ref) throw new UsageError('missing <skill>', 'frontera skill list — then pass a name or id')
+
+    const client = new PlatformApi(ctx.apiUrl, ctx.token)
+    const id = await resolveSkillRef(client, ref)
+    await client.deleteWorkspaceSkill(id)
+
+    return {
+      data: { id, name: ref, deleted: true },
+      // Bindings going too is the part worth stating: an agent that loaded this
+      // skill loses it at its next run, with no version to fall back to.
+      text: `deleted ${ref} — any agent bound to it no longer loads it`,
+    }
   },
-}))
+}
 
-export const skillCommands: Command[] = [list, get, ...reserved]
+export const skillCommands: Command[] = [list, get, ...skillBundleCommands, remove]

package/src/commands/skill/resolve.ts

@@ -0,0 +1,34 @@
+import { PlatformApi } from '../../api/platform-api'
+import { CliError } from '../../errors'
+
+interface SkillRow {
+  id?: string
+  name?: string
+  displayName?: string
+  description?: string
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+export async function resolveSkillRef(client: PlatformApi, ref: string): Promise<string> {
+  if (UUID.test(ref)) return ref
+
+  const rows = (await client.workspaceSkills()) as SkillRow[]
+  const match =
+    rows.find((s) => (s.name ?? '').toLowerCase() === ref.toLowerCase()) ??
+    rows.find((s) => (s.displayName ?? '').toLowerCase() === ref.toLowerCase())
+  if (match?.id) return match.id
+
+  const near = rows
+    .filter((s) => `${s.name ?? ''} ${s.displayName ?? ''}`.toLowerCase().includes(ref.toLowerCase()))
+    .map((s) => s.name)
+    .filter(Boolean)
+
+  throw new CliError(`no skill named "${ref}"`, {
+    code: 'NOT_FOUND',
+    hint:
+      near.length > 0
+        ? `did you mean ${near.slice(0, 3).join(', ')}?`
+        : 'run `frontera skill list` to see names and ids',
+  })
+}