feat(skills): skill import pipeline — archive, well-known registry, and ClawHub sources

[anconina]

Summary

Skills can now be imported from packaged archives and remote registries, not just GitHub directory URLs — through one staged, fail-closed pipeline shared by the skills_manage agent tool and the comis skills import CLI command.

Four import sources

• GitHub directory URL (the existing default)
• Packaged archive by URL or local path (.skill, .zip, .tar/.tar.gz) via --source archive — unpacked by an in-house, bounded extractor (no archive lib dependency)
• Well-known registry index via --source wellknown --registry <url> — registries must be explicitly allowlisted (default-empty allowlist)
• ClawHub @owner/slug via --source clawhub — honors the top-level verify verdict fail-closed, refuses before download on a failing verdict, pins the download by sha256 when the registry provides one

Pipeline hardening

• Text-only import: non-text payload files are dropped and reported; what lands on disk is inspectable Markdown/text
• Refuse-on-collision with existing skills; typed rejects (no throws) on mid-stream body errors and streaming timeouts
• MCP servers declared by an imported skill are persisted disabled until an operator enables them
• Single confirm surfaces both warnable classes (tool grants + CLI commands) before anything is written; acknowledged warnings are echoed on success
• skills.import.requireOfficialPublisher (default true) gates ClawHub installs on server-asserted publisher provenance; officialPublisher is recorded in the skill's provenance
• Imported skills land in a dedicated imported trust tier; a boot sweep retrofits/repairs prior imports and resumes interrupted commits (two-phase import-commit)

Frontmatter mapping

• Imported SKILL.md frontmatter is rewritten to the spec-pure form with Comis-specific fields under metadata.comis; the legacy Comis top-level form is still accepted with a WARN during a migration window

Observability & docs

• Import posture surfaces in the boot config_posture record and comis fleet findings
• New docs/skills/importing.mdx; updates to the manifest, data-directory, CLI, JSON-RPC, and config references

Testing

• Test-first throughout: each production commit is preceded by the failing-test commit that pins it
• New unit suites across daemon skills pipeline, CLI, config schema, and API contracts; integration tests for import commit, boot-sweep retrofit, and schema drift
• pnpm validate (docs:check, clean build, cycle checks, security lint, coverage) runs via the pre-push hook; pnpm validate:full on Linux is still pending before merge

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
comis	🟢 Ready	View Preview	Jul 7, 2026, 7:00 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[github-actions]

PR description incomplete

Please fill in all required sections before this PR can be reviewed.

Required sections: Description, Related Issue, Type of Change, Checklist, RED Test Proof.

For code changes in packages/*/src/**, paste the failing test output (test name + assertion error) from before the production patch in the RED Test Proof section, or write EXEMPT: <reason> for docs/CI/config-only PRs.

See CONTRIBUTING.md for the full contribution bar.

[anconina]

Code review

Found 2 issues:

1. mapForeignFrontmatter silently discards a pre-existing spec-pure metadata.comis carrier whenever any top-level legacy extension key is also present (bug due to packages/skills/src/skills/import/frontmatter-map.ts: the carrier preserved via metaMap["comis"] = entry is later unconditionally overwritten by metaMap["comis"] = JSON.stringify(extensionBag) — no merge, no warning). Example: frontmatter with metadata.comis carrying mcpServers/permissions/disableModelInvocation: true plus a stray top-level userInvocable: false imports with metadata.comis reduced to {"userInvocable":false}, so a skill the author explicitly hid from model invocation silently becomes model-invocable. This also contradicts the module's own contract that every dropped field is "DROPPED with a warning naming the exact key", and the inline comment at the preserve site claiming foreign namespaces "are reconciled at assembly". No test covers the combination.

Preserve site:

comis/packages/skills/src/skills/import/frontmatter-map.ts

Lines 331 to 337 in 5094263

	}
	if (key === "comis" && typeof entry === "string") {
	// An already-spec-pure carrier: preserve it (foreign namespaces, if any,
	// are reconciled at assembly).
	metaMap["comis"] = entry;
	continue;
	}

Clobber site:

comis/packages/skills/src/skills/import/frontmatter-map.ts

Lines 600 to 606 in 5094263

	}
	if (Object.keys(extensionBag).length > 0) {
	// The platform extension bag rides as a JSON string under metadata.comis; the
	// shipped lift parses it and merges each known extension key onto the manifest.
	metaMap["comis"] = JSON.stringify(extensionBag);
	}
	if (Object.keys(metaMap).length > 0) {

2. The new comis skills import section in the CLI reference documents --source as only github | archive and omits --registry entirely, while the CLI shipped in this same PR accepts four sources (github, archive, wellknown, clawhub) plus a --registry flag (CLAUDE.md says "Keep docs/**/*.mdx up to date in the same change that alters anything they describe — user-facing behavior, config keys/defaults, CLI commands/flags"). The other docs pages (docs/skills/importing.mdx, json-rpc.mdx, config-yaml.mdx) cover all four sources correctly — only docs/reference/cli.mdx drifted.

Docs:

comis/docs/reference/cli.mdx

Lines 1430 to 1438 in 5094263

	|------------|-------------|
	| `skills import <ref>` | Import a skill. `<ref>` is a GitHub directory URL (default) or an archive URL (with `--source archive`). |
	| Flag | Values | Description |
	|------|--------|-------------|
	| `--source <source>` | `github` \| `archive` | Acquisition channel. `github` (default) treats `<ref>` as a directory URL; `archive` treats it as a `.skill`/`.zip`/`.tar` URL. |
	| `--scope <scope>` | `local` \| `shared` | `local` (default) installs into this agent's workspace; `shared` installs into the global directory (default agent only). |
	| `--confirm` | flag | Confirm a re-import whose content diverges from the pinned hash of a prior import of the **same** source. Never overrides a name collision on an unprovenanced or foreign-source skill -- delete that skill first. There is no `force` flag. |
	| `--format <format>` | `table` \| `json` | Output format (default `table`). |

CLI implementation:

comis/packages/cli/src/commands/skills.ts

Lines 52 to 64 in 5094263

	)
	.option(
	"--source <source>",
	"Acquisition channel: github (a directory URL), archive (a .skill/zip/tar URL), " +
	"wellknown (resolve <ref> as a skill name from --registry), " +
	"or clawhub (resolve <ref> as an @owner/slug from ClawHub). Defaults to github.",
	)
	.option(
	"--registry <registry>",
	"Registry origin (https://host[:port]) to resolve the skill <ref> from — required with --source wellknown. " +
	"Must be allowlisted in skills.import.registries.",
	)
	.option(

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[anconina]

Code review (addendum)

Follow-up from a deeper comment-vs-code pass over the import pipeline. Found 3 additional issues (the frontmatter-map.ts carrier clobber from the earlier review was independently re-confirmed by exercising the code and is not repeated here):

1. acquire.ts violates its own "never throws" contract on the archiveUrl streaming path (bug due to readCappedBody's read loop having no try/catch). The module doc states "Result-typed throughout; no throws escape" and acquire's JSDoc states "Never throws — a reject is a typed AcquireError", but a body error after headers arrive — a connection reset mid-body, or the AbortSignal.timeout(30_000) firing while the body streams — rejects out of await reader.read(), escapes through the unguarded await readCappedBody(...), and throws out of acquire() and stageImport() as an untyped error instead of a typed, hint-carrying reject. The sibling resolvers guard exactly this branch (clawhub-source.ts / wellknown-source.ts wrap the identical read loop in try/catch with TimeoutError/AbortError mapped to typed rejects) — acquire.ts is the unpatched copy of the same helper.

Unguarded read loop:

comis/packages/skills/src/skills/import/acquire.ts

Lines 160 to 174 in 5094263

	const chunks: Uint8Array[] = [];
	let total = 0;
	for (;;) {
	const { done, value } = await reader.read();
	if (done) break;
	if (value === undefined) continue;
	total += value.byteLength;
	if (total > maxBytes) {
	await reader.cancel();
	return err(overCapError(maxBytes));
	}
	chunks.push(value);
	}
	return ok(Buffer.concat(chunks));
	}

"Never throws" contract + unguarded await:

comis/packages/skills/src/skills/import/acquire.ts

Lines 218 to 221 in 5094263

	const body = await readCappedBody(response, deps.caps.maxArchiveBytes);
	if (!body.ok) return body;
	return ok({ kind: "archive", bytes: body.value });

and

comis/packages/skills/src/skills/import/acquire.ts

Lines 241 to 247 in 5094263

	/**
	* Acquire the raw skill bytes / files from one source. Every `archiveUrl` fetch
	* is SSRF-pinned and byte-capped; `archiveBytes` is size-capped before decode;
	* a `fileSet` passes through untouched. Never throws — a reject is a typed
	* {@link AcquireError}.
	*/
	export async function acquire(

Guarded sibling for comparison:

comis/packages/skills/src/skills/import/sources/clawhub-source.ts

Lines 221 to 256 in 5094263

	try {
	for (;;) {
	const { done, value } = await reader.read();
	if (done) break;
	if (value === undefined) continue;
	total += value.byteLength;
	if (total > maxBytes) {
	await reader.cancel();
	return err(overCapError(maxBytes, what, capName));
	}
	chunks.push(value);
	}
	} catch (e) {
	suppressError(reader.cancel(), "cancel body reader after a mid-stream read error");
	// The only AbortSignal on the pinned fetch is AbortSignal.timeout(30_000),
	// so a Timeout/Abort raised during read() IS the streaming-timeout branch;
	// any other rejection is an unresponsive-registry dependency failure.
	const name = e instanceof Error ? e.name : "";
	if (name === "TimeoutError" || name === "AbortError") {
	return err(
	mkErr(
	"timeout",
	`reading ${what} from the ${REGISTRY_LABEL} registry timed out mid-stream (the 30s per-fetch cap fired while the body was streaming)`,
	"the registry sent headers then stalled the body; verify it responds fully within 30s",
	),
	);
	}
	return err(
	mkErr(
	"dependency",
	`reading ${what} from the ${REGISTRY_LABEL} registry failed mid-stream: ${e instanceof Error ? e.message : String(e)}`,
	"verify the registry is reachable and responsive; the fetch is pinned to the SSRF-validated IP and aborts after 30s",
	),
	);
	}
	return ok(Buffer.concat(chunks));

2. Three comments in bundle-install-helper.ts describe the pre-PR handler routing and now invert the PR's central trust boundary: they say applyBundleInstall (the trusted path that persists enabled: true and auto-connects) is invoked from skills.import + skills.upload, but this PR rerouted exactly those two handlers onto importThroughPipeline → applyImportedBundleInstall (disabled-by-default, never auto-connects); runBundleInstallHook → applyBundleInstall now serves only skills.create + skills.update. A reader trusting the comments would conclude a third-party import flows through the auto-connecting path — the opposite of the shipped design. The stale sites: the module doc ("the three skill install RPC handlers (skills.import, skills.create, skills.upload)"), the applyImportedBundleInstall docstring added by this PR ("the trusted create/upload path"), and the runBundleInstallHook docstring (same three-handler list).

comis/packages/daemon/src/skills/bundle-install-helper.ts

Lines 6 to 12 in 5094263

	*
	* Invoked from the three skill install RPC handlers (skills.import,
	* skills.create, skills.upload) AFTER the existing file-write + registry.init()
	* steps. Reads the freshly-written SKILL.md, runs Phase A via resolveBundle,
	* and on success commits via persistMcpServers + a sequential per-entry
	* manager.connect.
	*

,

comis/packages/daemon/src/skills/bundle-install-helper.ts

Lines 426 to 429 in 5094263

	*
	* Unlike {@link applyBundleInstall} (the trusted create/upload path, which
	* persists `enabled: true` and auto-connects), an IMPORTED skill's bundled MCP
	* entries persist DISABLED and are NEVER connected at install. The operator opts

,

comis/packages/daemon/src/skills/bundle-install-helper.ts

Lines 492 to 497 in 5094263

	/**
	* Thin wrapper invoked from each of the three install RPC handlers
	* (skills.import, skills.create, skills.upload) to keep their per-handler
	* wiring to a single line. Unpacks `force` + `_context` from the dispatcher-
	* raw params and delegates to applyBundleInstall.
	*

Actual call sites:

comis/packages/daemon/src/api/skill-handlers.ts

Lines 257 to 259 in 5094263

	const uploadCtx = rawParams._context as ImportCtx;
	const uploaded = await importThroughPipeline(deps, {
	acquireInput: { kind: "fileSet", files: uploadFiles },

and

comis/packages/daemon/src/api/skill-handlers.ts

Lines 650 to 652 in 5094263

	}
	await runBundleInstallHook(deps, params.name, skillDir, rawParams);

3. The PR-added doc comment on AcquisitionSourceSchema claims the registry-resolver channels are not yet implemented — "Only github / archive land in this slice; the registry-resolver channels (wellknown / clawhub) are modeled ahead of their handlers" — but the same PR ships both as live import paths: the request enum accepts them, the daemon dispatches resolveWellKnownFileSet / resolveClawHubFileSet, and the CLI exposes both sources. The comment describes them as inert placeholders when they are production channels.

comis/packages/core/src/api-contracts/workspace/skill-handlers.ts

Lines 18 to 25 in 5094263

	/**
	* Acquisition channel for an imported skill (HOW the bytes arrived) — distinct
	* from the trust-tier `source` below. Only `github` / `archive` land in this
	* slice; the registry-resolver channels (`wellknown` / `clawhub`) are modeled
	* ahead of their handlers so the provenance summary is forward-stable.
	*/
	const AcquisitionSourceSchema = z.enum([

Live dispatch:

comis/packages/daemon/src/api/skill-handlers.ts

Lines 339 to 341 in 5094263

	}
	const resolved = await resolveWellKnownFileSet(deps, {
	registry,

and

comis/packages/daemon/src/api/skill-handlers.ts

Lines 359 to 361 in 5094263

	}
	const resolved = await resolveClawHubFileSet(deps, {
	name: registryName,

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}