feat(clawdhub): soft delete skills

- make changelog optional for publish/sync
- add CLI delete/undelete + API routes
- hide deleted skills from search/download
- add e2e + manual testing doc + changelog

Author: steipete

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.0.2 — Unreleased
+- CLI: make changelog optional for updates (`publish`, `sync`).
+- Registry: allow empty changelog on updated versions.
+- CLI: use `--cli-version` (free `--version` for skill semver flags).
+- CLI: add `delete` / `undelete` (owner/admin) for soft deletion.
+- Registry: hide soft-deleted skills from `search`, `skill`, `download` (unless restored).
+- Tests: add delete/undelete coverage (unit + e2e).
+
+## 0.0.1 — 2026-01-04
+- Initial beta release of `clawdhub` CLI + `clawdhub-schema`.

convex/http.ts

@@ -4,6 +4,8 @@ import { auth } from './auth'
 import { downloadZip } from './downloads'
 import {
   cliPublishHttp,
+  cliSkillDeleteHttp,
+  cliSkillUndeleteHttp,
   cliUploadUrlHttp,
   cliWhoamiHttp,
   getSkillHttp,
@@ -57,4 +59,16 @@ http.route({
   handler: cliPublishHttp,
 })
 
+http.route({
+  path: ApiRoutes.cliSkillDelete,
+  method: 'POST',
+  handler: cliSkillDeleteHttp,
+})
+
+http.route({
+  path: ApiRoutes.cliSkillUndelete,
+  method: 'POST',
+  handler: cliSkillUndeleteHttp,
+})
+
 export default http

convex/httpApi.handlers.test.ts

@@ -242,4 +242,33 @@ describe('httpApi handlers', () => {
     expect(json.ok).toBe(true)
     expect(json.skillId).toBe('s')
   })
+
+  it('cliSkillDeleteHandler returns 401 when unauthorized', async () => {
+    vi.mocked(requireApiTokenUser).mockRejectedValueOnce(new Error('Unauthorized'))
+    const request = new Request('https://x/api/cli/skill/delete', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ slug: 'demo' }),
+    })
+    const response = await __handlers.cliSkillDeleteHandler({} as never, request, true)
+    expect(response.status).toBe(401)
+  })
+
+  it('cliSkillDeleteHandler calls mutation and returns ok', async () => {
+    vi.mocked(requireApiTokenUser).mockResolvedValueOnce({ userId: 'user1' } as never)
+    const runMutation = vi.fn().mockResolvedValue({ ok: true })
+    const request = new Request('https://x/api/cli/skill/delete', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ slug: 'demo' }),
+    })
+    const response = await __handlers.cliSkillDeleteHandler({ runMutation } as never, request, true)
+    expect(response.status).toBe(200)
+    expect(runMutation).toHaveBeenCalledWith(expect.anything(), {
+      userId: 'user1',
+      slug: 'demo',
+      deleted: true,
+    })
+    expect(await response.json()).toEqual({ ok: true })
+  })
 })

convex/httpApi.ts

@@ -1,4 +1,9 @@
-import { CliPublishRequestSchema, parseArk } from 'clawdhub-schema'
+import {
+  ApiCliSkillDeleteResponseSchema,
+  CliPublishRequestSchema,
+  CliSkillDeleteRequestSchema,
+  parseArk,
+} from 'clawdhub-schema'
 import { api, internal } from './_generated/api'
 import type { Id } from './_generated/dataModel'
 import { httpAction } from './_generated/server'
@@ -188,6 +193,38 @@ async function cliPublishHandler(ctx: HttpCtx, request: Request) {
 
 export const cliPublishHttp = httpAction(cliPublishHandler)
 
+async function cliSkillDeleteHandler(ctx: HttpCtx, request: Request, deleted: boolean) {
+  let body: unknown
+  try {
+    body = await request.json()
+  } catch {
+    return text('Invalid JSON', 400)
+  }
+
+  try {
+    const { userId } = await requireApiTokenUser(ctx, request)
+    const args = parseArk(CliSkillDeleteRequestSchema, body, 'Delete payload')
+    await ctx.runMutation(internal.skills.setSkillSoftDeletedInternal, {
+      userId,
+      slug: args.slug,
+      deleted,
+    })
+    const ok = parseArk(ApiCliSkillDeleteResponseSchema, { ok: true }, 'Delete response')
+    return json(ok)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Delete failed'
+    if (message.toLowerCase().includes('unauthorized')) return text('Unauthorized', 401)
+    return text(message, 400)
+  }
+}
+
+export const cliSkillDeleteHttp = httpAction((ctx, request) =>
+  cliSkillDeleteHandler(ctx, request, true),
+)
+export const cliSkillUndeleteHttp = httpAction((ctx, request) =>
+  cliSkillDeleteHandler(ctx, request, false),
+)
+
 function json(value: unknown, status = 200) {
   return new Response(JSON.stringify(value), {
     status,
@@ -243,4 +280,5 @@ export const __handlers = {
   cliWhoamiHandler,
   cliUploadUrlHandler,
   cliPublishHandler,
+  cliSkillDeleteHandler,
 }

convex/schema.ts

@@ -30,6 +30,7 @@ const skills = defineTable({
   ownerUserId: v.id('users'),
   latestVersionId: v.optional(v.id('skillVersions')),
   tags: v.record(v.string(), v.id('skillVersions')),
+  softDeletedAt: v.optional(v.number()),
   badges: v.object({
     redactionApproved: v.optional(
       v.object({

convex/search.ts

@@ -58,6 +58,7 @@ export const hydrateResults = internalQuery({
       const embedding = await ctx.db.get(embeddingId)
       if (!embedding) continue
       const skill = await ctx.db.get(embedding.skillId)
+      if (skill?.softDeletedAt) continue
       const version = await ctx.db.get(embedding.versionId)
       entries.push({ embeddingId, skill, version })
     }

convex/skills.ts

@@ -48,7 +48,7 @@ export const getBySlug = query({
       .query('skills')
       .withIndex('by_slug', (q) => q.eq('slug', args.slug))
       .unique()
-    if (!skill) return null
+    if (!skill || skill.softDeletedAt) return null
     const latestVersion = skill.latestVersionId ? await ctx.db.get(skill.latestVersionId) : null
     const owner = await ctx.db.get(skill.ownerUserId)
     return { skill, latestVersion, owner }
@@ -74,21 +74,27 @@ export const list = query({
   handler: async (ctx, args) => {
     const limit = args.limit ?? 24
     if (args.batch) {
-      return ctx.db
+      const entries = await ctx.db
         .query('skills')
         .withIndex('by_batch', (q) => q.eq('batch', args.batch))
         .order('desc')
-        .take(limit)
+        .take(limit * 5)
+      return entries.filter((skill) => !skill.softDeletedAt).slice(0, limit)
     }
     const ownerUserId = args.ownerUserId
     if (ownerUserId) {
-      return ctx.db
+      const entries = await ctx.db
         .query('skills')
         .withIndex('by_owner', (q) => q.eq('ownerUserId', ownerUserId))
         .order('desc')
-        .take(limit)
+        .take(limit * 5)
+      return entries.filter((skill) => !skill.softDeletedAt).slice(0, limit)
     }
-    return ctx.db.query('skills').order('desc').take(limit)
+    const entries = await ctx.db
+      .query('skills')
+      .order('desc')
+      .take(limit * 5)
+    return entries.filter((skill) => !skill.softDeletedAt).slice(0, limit)
   },
 })
 
@@ -164,11 +170,7 @@ export async function publishVersionForUser(
   if (!semver.valid(version)) {
     throw new ConvexError('Version must be valid semver')
   }
-  const existingSkill = await ctx.runQuery(internal.skills.getSkillBySlugInternal, { slug })
   const changelogText = args.changelog.trim()
-  if (existingSkill && !changelogText) {
-    throw new ConvexError('Changelog is required for updates')
-  }
 
   const sanitizedFiles = args.files.map((file) => ({
     ...file,
@@ -418,6 +420,7 @@ export const insertVersion = internalMutation({
         ownerUserId: userId,
         latestVersionId: undefined,
         tags: {},
+        softDeletedAt: undefined,
         badges: { redactionApproved: undefined },
         stats: { downloads: 0, stars: 0, versions: 0, comments: 0 },
         createdAt: now,
@@ -461,6 +464,7 @@ export const insertVersion = internalMutation({
       latestVersionId: versionId,
       tags: nextTags,
       stats: { ...skill.stats, versions: skill.stats.versions + 1 },
+      softDeletedAt: undefined,
       updatedAt: now,
     })
 
@@ -493,6 +497,61 @@ export const insertVersion = internalMutation({
   },
 })
 
+export const setSkillSoftDeletedInternal = internalMutation({
+  args: {
+    userId: v.id('users'),
+    slug: v.string(),
+    deleted: v.boolean(),
+  },
+  handler: async (ctx, args) => {
+    const user = await ctx.db.get(args.userId)
+    if (!user || user.deletedAt) throw new Error('User not found')
+
+    const slug = args.slug.trim().toLowerCase()
+    if (!slug) throw new Error('Slug required')
+
+    const skill = await ctx.db
+      .query('skills')
+      .withIndex('by_slug', (q) => q.eq('slug', slug))
+      .unique()
+    if (!skill) throw new Error('Skill not found')
+
+    if (skill.ownerUserId !== args.userId) {
+      assertRole(user, ['admin', 'moderator'])
+    }
+
+    const now = Date.now()
+    await ctx.db.patch(skill._id, {
+      softDeletedAt: args.deleted ? now : undefined,
+      updatedAt: now,
+    })
+
+    const embeddings = await ctx.db
+      .query('skillEmbeddings')
+      .withIndex('by_skill', (q) => q.eq('skillId', skill._id))
+      .collect()
+    for (const embedding of embeddings) {
+      await ctx.db.patch(embedding._id, {
+        visibility: args.deleted
+          ? 'deleted'
+          : visibilityFor(embedding.isLatest, embedding.isApproved),
+        updatedAt: now,
+      })
+    }
+
+    await ctx.db.insert('auditLogs', {
+      actorUserId: args.userId,
+      action: args.deleted ? 'skill.delete' : 'skill.undelete',
+      targetType: 'skill',
+      targetId: skill._id,
+      metadata: { slug, softDeletedAt: args.deleted ? now : null },
+      createdAt: now,
+    })
+
+    return { ok: true as const }
+  },
+})
+
 async function fetchText(
   ctx: { storage: { get: (id: Id<'_storage'>) => Promise<Blob | null> } },
   storageId: Id<'_storage'>,

docs/manual-testing.md

@@ -0,0 +1,43 @@
+# Manual testing (CLI)
+
+## Setup
+- Ensure logged in: `bun clawdhub whoami` (or `bun clawdhub login`).
+- Optional: set env
+  - `CLAWDHUB_SITE=https://clawdhub.com`
+  - `CLAWDHUB_REGISTRY=https://clawdhub.com`
+
+## Smoke
+- `bun clawdhub --help`
+- `bun clawdhub --cli-version`
+- `bun clawdhub whoami`
+
+## Search
+- `bun clawdhub search gif --limit 5`
+
+## Install / list / update
+- `mkdir -p /tmp/clawdhub-manual && cd /tmp/clawdhub-manual`
+- `bunx clawdhub@beta install gifgrep --force`
+- `bunx clawdhub@beta list`
+- `bunx clawdhub@beta update gifgrep --force`
+
+## Publish (changelog optional)
+- `mkdir -p /tmp/clawdhub-skill-demo/SKILL && cd /tmp/clawdhub-skill-demo`
+- Create files:
+  - `SKILL.md`
+  - `notes.md`
+- Publish:
+  - `bun clawdhub publish . --slug clawdhub-manual-<ts> --name "Manual <ts>" --version 1.0.0 --tags latest`
+- Publish update with empty changelog:
+  - `bun clawdhub publish . --slug clawdhub-manual-<ts> --name "Manual <ts>" --version 1.0.1 --tags latest`
+
+## Delete / undelete (owner/admin)
+- `bun clawdhub delete clawdhub-manual-<ts> --yes`
+- Verify hidden:
+  - `curl -i "https://clawdhub.com/api/skill?slug=clawdhub-manual-<ts>"`
+- Restore:
+  - `bun clawdhub undelete clawdhub-manual-<ts> --yes`
+- Cleanup:
+  - `bun clawdhub delete clawdhub-manual-<ts> --yes`
+
+## Sync
+- `bun clawdhub sync --dry-run --all`

docs/spec.md

@@ -97,7 +97,7 @@ From SKILL.md frontmatter + AgentSkills + Clawdis extensions:
 - Each upload is a new `SkillVersion`.
 - `latest` tag always points to most recent version unless user re-tags.
 - Rollback: move `latest` (and optionally other tags) to an older version.
-- Changelog required for any update.
+- Changelog is optional.
 
 ## Search
 - Vector search over: SKILL.md + other text files + metadata summary.