@hasna/skills 0.1.59 → 0.1.61

package/dist/lib/infra-identifiers.d.ts

@@ -0,0 +1,144 @@
+/**
+ * infra-identifiers.ts — R4 enforcement: vendor infrastructure identifiers live
+ * behind ONE indirection.
+ *
+ * The open-source repository must never name the infrastructure of whoever
+ * happens to operate it. Account IDs, ARNs, ECS cluster/service/task-family
+ * names, container names and health hosts are properties of a *deployment*, not
+ * of the software, so they resolve at deploy time from a deploy manifest or CI
+ * variables. At most one tracked line may name where that manifest lives.
+ *
+ * This module expresses that as a set of PROPERTIES rather than a blocklist of
+ * known-bad strings, so it survives renaming (`skills-prod-worker` ->
+ * `widgets-stage-queue` is caught just the same) and catches semantic inversion
+ * (re-hardcoding a value that used to be parameterized).
+ *
+ * The five properties:
+ *
+ *   1. `aws-account-id`  — a literal 12-digit AWS account ID. Anchored on
+ *      non-alphanumeric/non-hyphen boundaries so it does NOT fire inside UUIDs
+ *      (`...-8000-000000000000`) or 13-digit millisecond epochs.
+ *   2. `aws-arn`         — an ARN whose account field is a literal.
+ *   3. `infra-resource-name` — the `<app>-<env>[-<component>]` naming convention
+ *      that AWS resources follow, with a LITERAL app segment. A name assembled
+ *      from a substitution (`${{ env.APP }}-prod-gha-deploy`) is compliant and
+ *      is not flagged.
+ *   4. `unparameterized-workflow-infra` — inside a workflow, an env assignment
+ *      whose key names an infrastructure resource (CLUSTER / SERVICE / FAMILY /
+ *      CONTAINER / ECR / HEALTH_URL / SUBNET / SECURITY_GROUP) but whose value
+ *      contains no substitution at all. This is the rule that catches a plain
+ *      literal like `skills-worker` that follows no naming convention.
+ *   5. `workflow-vendor-host` — a literal URL host inside a workflow that is not
+ *      a well-known CI/tooling host. Deploy and health targets are deployment
+ *      configuration, not source.
+ *
+ * Plus one cardinality property: `manifest-location-not-unique` — more than one
+ * tracked line naming the deploy-manifest location.
+ */
+export type InfraRuleId = "aws-account-id" | "aws-arn" | "infra-resource-name" | "unparameterized-workflow-infra" | "workflow-vendor-host" | "manifest-location-not-unique" | "unscannable-file" | "unparseable-workflow";
+export type InfraFinding = {
+    file: string;
+    line: number;
+    ruleId: InfraRuleId;
+    /** The offending text, trimmed to keep CI logs readable. */
+    match: string;
+    message: string;
+};
+export type ScannedFile = {
+    /** Repo-relative path, POSIX separators. */
+    path: string;
+    content: string;
+};
+/**
+ * The detector's own module and test are exempt from the repository scan.
+ *
+ * They exist to DEFINE and EXERCISE these patterns, so they necessarily contain
+ * a literal account ID, a literal ARN and a literal resource name as test
+ * vectors — a scanner that flags its own fixtures is a scanner that gets
+ * disabled. The exemption is deliberately two exact paths, never a prefix or a
+ * glob, and `infra-identifiers.test.ts` asserts that this set does not grow.
+ * (Same shape as the audited `scanAllowlist` in scripts/release-guard.ts.)
+ */
+export declare const SELF_EXCLUDED_PATHS: readonly string[];
+/**
+ * Scan already-loaded file contents for R4 violations. Pure — no filesystem, no
+ * git — so it is trivially testable with synthetic inputs.
+ */
+export declare function scanInfraIdentifiers(files: ScannedFile[]): InfraFinding[];
+/**
+ * List git-tracked files. `git ls-files` never descends into `node_modules`
+ * unless it is tracked, which sidesteps the CI-grep-vs-interactive-grep trap:
+ * GNU grep in CI does not auto-exclude `node_modules`, and two vendored trees
+ * exist in this repo. The explicit filter below is belt-and-braces for the case
+ * where a vendored tree IS tracked.
+ */
+/**
+ * Whether `repoRoot` is inside a git work tree.
+ *
+ * R4 is a property of a *repository*: the leak it prevents lives in tracked
+ * files such as `.github/workflows`. The release guard is also exercised against
+ * synthetic package fixtures in a bare temp directory, where there are no
+ * tracked files and the rule has nothing to say. Callers use this to tell
+ * "not applicable here" apart from "the scan broke", which must stay fatal.
+ *
+ * This is NOT an escape hatch for the real repository: `bun test` runs the scan
+ * against the repo root on every CI run regardless of what the release guard
+ * decides, so the property cannot lapse by moving where the guard is invoked.
+ */
+export declare function isGitWorkTree(repoRoot: string): boolean;
+export declare function listTrackedFiles(repoRoot: string): string[];
+/**
+ * Why a tracked file was not scanned. Every tracked path lands in exactly one of
+ * scanned / skipped / self-excluded, and the scan asserts the three add up.
+ * There is no fourth outcome and no silent drop.
+ */
+export type SkipReason = "binary-content" | "not-a-regular-file" | "unreadable";
+/**
+ * Tracked paths permitted to go unscanned, matched exactly on (path, reason).
+ *
+ * Empty, and asserted empty. Any skip at all fails the scan: a file the guard
+ * did not read is a file the guard did not clear, and "logged but forgiven" is
+ * how the NUL-drop survived in the first place. Adding an entry here is a
+ * deliberate, reviewable act.
+ */
+export declare const PINNED_SKIPS: readonly SkippedFile[];
+export type SkippedFile = {
+    path: string;
+    reason: SkipReason;
+};
+export type ReadResult = {
+    files: ScannedFile[];
+    skipped: SkippedFile[];
+};
+/**
+ * Read tracked files for scanning.
+ *
+ * This function used to do `if (buffer.includes(0)) continue` — dropping any
+ * file containing a NUL byte, with no counter and no warning. That is a bypass,
+ * not a heuristic: appending one NUL to a comment removed a file from the scan
+ * entirely, and `src/lib/content-scan.ts` (which then wrote its composite-key
+ * separator as a raw NUL) was already being dropped on a clean tree.
+ *
+ * A NUL byte is now simply a byte. The content is decoded and scanned like any
+ * other; the patterns work fine on a string that happens to contain U+0000.
+ * The only remaining non-scans are the ones named in SkipReason, and each is
+ * returned to the caller rather than swallowed.
+ */
+export declare function readTrackedFiles(repoRoot: string, paths: string[]): ReadResult;
+export type InfraScanResult = {
+    findings: InfraFinding[];
+    scannedFileCount: number;
+    /** Every tracked file that was not scanned, with the reason. Never empty-by-omission. */
+    skippedFiles: SkippedFile[];
+    trackedFileCount: number;
+};
+/**
+ * Scan the repository's tracked files.
+ *
+ * Throws rather than returning a clean result when the scan cannot honestly
+ * claim coverage: no tracked files, an accounting shortfall, no workflow
+ * scanned, or the deploy pipeline missing from the files actually read. Every
+ * one of those would otherwise be a vacuous pass.
+ */
+export declare function scanRepositoryInfraIdentifiers(repoRoot: string): InfraScanResult;
+export declare function formatInfraFindings(findings: InfraFinding[]): string;

package/dist/lib/installer.d.ts

@@ -1,10 +1,11 @@
 /**
  * Skill setup and project preferences.
  *
- * Skills are discovered through the CLI/MCP registry and executed from the
- * bundled package or the remote platform. This module deliberately does not
- * copy skill source, SKILL.md, package.json, scripts, or runtime folders into
- * projects or agent-native skill folders.
+ * Skills are discovered through the CLI/MCP registry and executed from the bundled
+ * package or the remote platform. Project state remains metadata-only pins. Agent skill
+ * folders, however, are now written by the last-mile sync: installSkillForAgent() writes a
+ * per-tool-adapted SKILL.md into an agent's folder, non-clobbering, marking each directory
+ * it owns so a re-sync never overwrites a skill the user hand-authored.
  */
 import { type SkillMeta } from "./registry.js";
 import { type ProjectSkillPin } from "./project-state.js";
@@ -99,6 +100,19 @@ export interface AgentInstallOptions {
 }
 export declare function getAgentSkillsDir(agent: AgentTarget, scope?: AgentScope, projectDir?: string): string;
 export declare function getAgentSkillPath(name: string, agent: AgentTarget, scope?: AgentScope, projectDir?: string): string;
-export declare function installSkillForAgent(name: string, options: AgentInstallOptions, _generateSkillMd?: (name: string) => string | null): InstallResult;
-export declare function removeSkillForAgent(_name: string, _options: AgentInstallOptions): boolean;
+/**
+ * Write a skill's SKILL.md into one agent's skill folder, per-tool adapted and
+ * non-clobbering.
+ *
+ * This used to be a stub that refused every call ("pins, not installs"). The last-mile
+ * work reverses that: agents load skills from these folders, so `skills sync` writes them
+ * there. An unmanaged directory with SKILL.md can be explicitly adopted with
+ * `overwrite`; any other pre-existing unmarked directory is never touched. Managed
+ * writes replace the complete owned directory — see writeManagedSkillDir.
+ */
+export declare function installSkillForAgent(name: string, options: AgentInstallOptions & {
+    overwrite?: boolean;
+    dryRun?: boolean;
+}, generateSkillMd?: (name: string) => string | null): InstallResult;
+export declare function removeSkillForAgent(name: string, options: AgentInstallOptions): boolean;
 export {};

package/dist/lib/native-storage.d.ts

@@ -1,9 +1,21 @@
-export type SkillsStorageMode = "local" | "remote" | "hybrid";
+/**
+ * There is no storage "mode" either.
+ *
+ * This layer used to carry a declared local|remote|hybrid label. Nothing ever
+ * branched on it: it was echoed into `storage status` and `storage sync-plan`
+ * beside databaseConfigured/s3Configured, which are read from the actual
+ * configuration. A declared label can contradict them (mode=remote with no
+ * database URL), so it was a second, weaker answer to a question already
+ * answered truthfully. What the store does is derived from what you configured:
+ * on-box SQLite plus files, plus Postgres and/or S3 when their env vars are set.
+ *
+ * Deleting the label left the variable that used to hold it merely *unread*, which
+ * is the worse failure and is now refused: see lib/retired-settings.ts.
+ */
 export declare const SKILLS_STORAGE_TABLES: readonly ["skills_sync_records", "skills_sync_cursors"];
 export declare const STORAGE_TABLES: readonly ["skills_sync_records", "skills_sync_cursors"];
 export type SkillsStorageTable = typeof SKILLS_STORAGE_TABLES[number];
 export interface SkillsNativeStorageConfig {
-    mode: SkillsStorageMode;
     databaseUrl?: string;
     databaseSsl?: boolean;
     databaseSchema?: string;
@@ -16,7 +28,6 @@ export interface SkillsNativeStorageConfig {
     dryRun: boolean;
 }
 export declare const SKILLS_NATIVE_STORAGE_ENV: {
-    readonly mode: "HASNA_SKILLS_STORAGE_MODE";
     readonly databaseUrl: "HASNA_SKILLS_DATABASE_URL";
     readonly databaseSsl: "HASNA_SKILLS_DATABASE_SSL";
     readonly databaseSchema: "HASNA_SKILLS_DATABASE_SCHEMA";
@@ -32,7 +43,6 @@ export declare const SKILLS_NATIVE_STORAGE_ENV: {
     readonly dryRun: "HASNA_SKILLS_SYNC_DRY_RUN";
 };
 export declare const SKILLS_NATIVE_STORAGE_FALLBACK_ENV: {
-    readonly mode: "SKILLS_STORAGE_MODE";
     readonly databaseUrl: "SKILLS_DATABASE_URL";
     readonly databaseSsl: "SKILLS_DATABASE_SSL";
     readonly databaseSchema: "SKILLS_DATABASE_SCHEMA";
@@ -48,7 +58,6 @@ export declare const SKILLS_NATIVE_STORAGE_FALLBACK_ENV: {
     readonly dryRun: "SKILLS_SYNC_DRY_RUN";
 };
 export declare const SKILLS_STORAGE_ENV: {
-    readonly mode: "HASNA_SKILLS_STORAGE_MODE";
     readonly databaseUrl: "HASNA_SKILLS_DATABASE_URL";
     readonly databaseSsl: "HASNA_SKILLS_DATABASE_SSL";
     readonly databaseSchema: "HASNA_SKILLS_DATABASE_SCHEMA";
@@ -64,7 +73,6 @@ export declare const SKILLS_STORAGE_ENV: {
     readonly dryRun: "HASNA_SKILLS_SYNC_DRY_RUN";
 };
 export declare const SKILLS_STORAGE_FALLBACK_ENV: {
-    readonly mode: "SKILLS_STORAGE_MODE";
     readonly databaseUrl: "SKILLS_DATABASE_URL";
     readonly databaseSsl: "SKILLS_DATABASE_SSL";
     readonly databaseSchema: "SKILLS_DATABASE_SCHEMA";
@@ -81,18 +89,14 @@ export declare const SKILLS_STORAGE_FALLBACK_ENV: {
 };
 export declare function resolveSkillsNativeStorageConfig(env?: Record<string, string | undefined>): SkillsNativeStorageConfig;
 export declare function resolveStorageConfig(env?: Record<string, string | undefined>): SkillsNativeStorageConfig;
-export declare function getSkillsStorageMode(env?: Record<string, string | undefined>): SkillsStorageMode;
-export declare function getStorageMode(env?: Record<string, string | undefined>): SkillsStorageMode;
 export declare function getSkillsStorageDatabaseEnv(env?: Record<string, string | undefined>): string;
 export declare function getStorageDatabaseEnv(env?: Record<string, string | undefined>): string;
 export declare function getSkillsStorageDatabaseUrl(env?: Record<string, string | undefined>): string | undefined;
 export declare function getStorageDatabaseUrl(env?: Record<string, string | undefined>): string | undefined;
 export interface SkillsNativeStorageStatus {
     package: "open-skills";
-    mode: SkillsStorageMode;
     tables: readonly SkillsStorageTable[];
     env: {
-        mode: string;
         databaseUrl: string;
         s3Bucket: string;
     };
@@ -106,7 +110,6 @@ export interface SkillsNativeStorageStatus {
         s3Configured: boolean;
         databaseEnv: string;
         s3BucketEnv: string;
-        activeModeEnv: string;
         activeDatabaseEnv: string;
         activeS3BucketEnv: string;
         region: string;

package/dist/lib/packlist.d.ts

@@ -6,6 +6,19 @@
  * copy of the `files` array. This guarantees the safety guards scan exactly what
  * ships, including the effect of the `files` allow/deny globs.
  */
+/**
+ * Parse `npm pack --json`, returning null rather than throwing when the output is
+ * not a usable manifest.
+ *
+ * npm does not always produce the JSON it promises. Observed in CI: a first,
+ * cold `npm pack` invocation took 5s, exited 0, and wrote nothing to stdout,
+ * which surfaced as a bare `SyntaxError: JSON Parse error: Unexpected EOF` from
+ * inside a boundary test - an unactionable failure that says nothing about
+ * packaging. Later calls in the same run, with the same package.json, succeeded
+ * in ~1.2s. Returning null lets the caller fall back to `bun pm pack` instead of
+ * failing the build on npm's flakiness.
+ */
+export declare function parseNpmPackJson(stdout: string): string[] | null;
 /**
  * Return the sorted list of package-relative file paths that would be published.
  * Prefers `npm pack` (authoritative for npm) and falls back to `bun pm pack`.

package/dist/lib/portable-skills-files.d.ts

@@ -0,0 +1,25 @@
+import type { SkillKind } from "./registry-types.js";
+import { type PortableSkillManifest } from "./portable-skills-types.js";
+export declare function normalizePortableSkillName(name: string): string;
+export declare function readPortableSkillManifest(skillPath: string, fallbackName?: string): PortableSkillManifest;
+export declare function parseSkillKind(value: string | undefined): SkillKind | undefined;
+export declare function createInstructionManifest(name: string, options: {
+    description: string;
+}): PortableSkillManifest;
+export declare function writeInstructionSkillTemplate(skillPath: string, manifest: PortableSkillManifest): void;
+export declare function createPortableManifest(name: string, options: {
+    description: string;
+}): PortableSkillManifest;
+export declare function writePortableSkillTemplate(skillPath: string, manifest: PortableSkillManifest): void;
+export declare function ensurePortableSkillFiles(skillPath: string, manifest: PortableSkillManifest): PortableSkillManifest;
+/**
+ * Instruction (prose) skills are consumed by agent renderers/MCP docs, not run
+ * locally, so `port` must never fabricate executable stubs (package.json, bin,
+ * src/index.ts, tsconfig.json, AGENTS.md). It keeps the copied SKILL.md verbatim
+ * and writes a minimal skill.json declaring `kind: "instruction"`.
+ */
+export declare function ensureInstructionSkillFiles(skillPath: string, manifest: PortableSkillManifest): PortableSkillManifest;
+export declare function copySkillDirectory(source: string, destination: string): void;
+export declare function renderSkillJson(manifest: PortableSkillManifest): string;
+export declare function hasPackageDependencies(pkgPath: string): boolean;
+export declare function displayName(name: string): string;

package/dist/lib/portable-skills-types.d.ts

@@ -0,0 +1,105 @@
+import type { SkillKind } from "./registry-types.js";
+export declare const PORTABLE_SKILL_STANDARD = "hasna.skill.v1";
+export declare const PORTABLE_SKILL_SCHEMA = "https://hasna.dev/schemas/skill.v1.json";
+export declare const PORTABLE_SKILL_DEFAULT_VERSION = "0.1.0";
+/**
+ * Artifact class of a portable skill.
+ * - `executable`: a runnable skill folder (package.json + bin + src entry).
+ * - `instruction`: a prose-only agent skill (SKILL.md primary, optional skill.json).
+ *
+ * Re-exports the canonical SkillKind (defined in registry-types) for existing consumers.
+ */
+export type { SkillKind };
+export interface PortableSkillInput {
+    name: string;
+    type: string;
+    required?: boolean;
+    description?: string;
+}
+export interface PortableSkillCommand {
+    name: string;
+    description?: string;
+    entry?: string;
+    command?: string;
+    args?: string[];
+}
+export interface PortableSkillManifest {
+    $schema?: string;
+    standard: typeof PORTABLE_SKILL_STANDARD | string;
+    name: string;
+    description: string;
+    version: string;
+    displayName?: string;
+    category?: string;
+    tags?: string[];
+    kind?: SkillKind;
+    inputs: PortableSkillInput[];
+    commands: PortableSkillCommand[];
+}
+export interface PortableSkillSummary {
+    name: string;
+    displayName: string;
+    description: string;
+    version: string;
+    path: string;
+    commands: PortableSkillCommand[];
+    source: "custom";
+    standard: string;
+}
+export interface PortableSkillOptions {
+    rootDir?: string;
+    homeDir?: string;
+}
+export interface ScaffoldPortableSkillOptions extends PortableSkillOptions {
+    description?: string;
+    overwrite?: boolean;
+    kind?: SkillKind;
+}
+export interface PortPortableSkillOptions extends PortableSkillOptions {
+    name?: string;
+    overwrite?: boolean;
+    /**
+     * Permit an imported skill name that shadows a bundled official skill.
+     * Without this, `port` refuses to silently override the official corpus.
+     */
+    allowShadow?: boolean;
+}
+export interface BulkPortPortableSkillOptions extends PortableSkillOptions {
+    overwrite?: boolean;
+    /** When false, the first failure is rethrown. Defaults to true (skip-on-error). */
+    continueOnError?: boolean;
+}
+export interface BulkPortImportedEntry {
+    name: string;
+    path: string;
+    sourcePath: string;
+}
+export interface BulkPortSkippedEntry {
+    sourcePath: string;
+    name?: string;
+    reason: string;
+}
+export interface BulkPortResult {
+    root: string;
+    total: number;
+    succeeded: number;
+    failed: number;
+    imported: BulkPortImportedEntry[];
+    skipped: BulkPortSkippedEntry[];
+}
+export interface PortableSkillWriteResult {
+    name: string;
+    path: string;
+    manifest: PortableSkillManifest;
+    created: boolean;
+}
+export interface PortableSkillRunOptions extends PortableSkillOptions {
+    stdio?: "inherit" | "pipe";
+    env?: Record<string, string>;
+}
+export interface PortableSkillRunResult {
+    exitCode: number;
+    stdout?: string;
+    stderr?: string;
+    error?: string;
+}

package/dist/lib/portable-skills.d.ts

@@ -1,116 +1,34 @@
 import type { SkillKind, SkillMeta } from "./registry-types.js";
 import { type SkillValidationResult } from "./skill-validation.js";
-export declare const PORTABLE_SKILL_STANDARD = "hasna.skill.v1";
-export declare const PORTABLE_SKILL_SCHEMA = "https://hasna.dev/schemas/skill.v1.json";
-export declare const PORTABLE_SKILL_DEFAULT_VERSION = "0.1.0";
+import { normalizePortableSkillName, readPortableSkillManifest } from "./portable-skills-files.js";
+import type { BulkPortPortableSkillOptions, BulkPortResult, PortableSkillOptions, PortableSkillRunOptions, PortableSkillRunResult, PortableSkillSummary, PortableSkillWriteResult, PortPortableSkillOptions, ScaffoldPortableSkillOptions } from "./portable-skills-types.js";
+export { normalizePortableSkillName, readPortableSkillManifest, };
+export * from "./portable-skills-types.js";
 /**
- * Artifact class of a portable skill.
- * - `executable`: a runnable skill folder (package.json + bin + src entry).
- * - `instruction`: a prose-only agent skill (SKILL.md primary, optional skill.json).
+ * Resolve the corpus: the directory holding one folder per installed skill.
  *
- * Re-exports the canonical SkillKind (defined in registry-types) for existing consumers.
+ * Precedence is explicit-over-ambient, most specific first:
+ *   1. `options.rootDir`  - the corpus, named outright (no `installed` suffix)
+ *   2. `options.homeDir`  - <home>/.hasna/skills/installed
+ *   3. `getDataDir()`     - <app folder>/installed, where the app folder is
+ *                           $HASNA_SKILLS_DIR, else ~/.hasna/skills
+ *
+ * The app folder holds app data (config.json, skills.db, auth.json); the corpus
+ * is a named subfolder of it, matching every sibling Hasna app. One variable
+ * relocates the app folder and the corpus moves with it.
+ *
+ * `options.homeDir` used to sit *below* the $HASNA_SKILLS_DIR lookup, so an
+ * ambient environment variable silently overrode an argument the caller had
+ * passed deliberately - the caller could not target a directory at all once the
+ * variable was set anywhere in the process. Reading the environment is now left
+ * entirely to getDataDir(), so there is one place that knows the variable's name
+ * and one rule for which source wins.
  */
-export type { SkillKind };
-export interface PortableSkillInput {
-    name: string;
-    type: string;
-    required?: boolean;
-    description?: string;
-}
-export interface PortableSkillCommand {
-    name: string;
-    description?: string;
-    entry?: string;
-    command?: string;
-    args?: string[];
-}
-export interface PortableSkillManifest {
-    $schema?: string;
-    standard: typeof PORTABLE_SKILL_STANDARD | string;
-    name: string;
-    description: string;
-    version: string;
-    displayName?: string;
-    category?: string;
-    tags?: string[];
-    kind?: SkillKind;
-    inputs: PortableSkillInput[];
-    commands: PortableSkillCommand[];
-}
-export interface PortableSkillSummary {
-    name: string;
-    displayName: string;
-    description: string;
-    version: string;
-    path: string;
-    commands: PortableSkillCommand[];
-    source: "custom";
-    standard: string;
-}
-export interface PortableSkillOptions {
-    rootDir?: string;
-    homeDir?: string;
-}
-export interface ScaffoldPortableSkillOptions extends PortableSkillOptions {
-    description?: string;
-    overwrite?: boolean;
-    kind?: SkillKind;
-}
-export interface PortPortableSkillOptions extends PortableSkillOptions {
-    name?: string;
-    overwrite?: boolean;
-    /**
-     * Permit an imported skill name that shadows a bundled official skill.
-     * Without this, `port` refuses to silently override the official corpus.
-     */
-    allowShadow?: boolean;
-}
-export interface BulkPortPortableSkillOptions extends PortableSkillOptions {
-    overwrite?: boolean;
-    /** When false, the first failure is rethrown. Defaults to true (skip-on-error). */
-    continueOnError?: boolean;
-}
-export interface BulkPortImportedEntry {
-    name: string;
-    path: string;
-    sourcePath: string;
-}
-export interface BulkPortSkippedEntry {
-    sourcePath: string;
-    name?: string;
-    reason: string;
-}
-export interface BulkPortResult {
-    root: string;
-    total: number;
-    succeeded: number;
-    failed: number;
-    imported: BulkPortImportedEntry[];
-    skipped: BulkPortSkippedEntry[];
-}
-export interface PortableSkillWriteResult {
-    name: string;
-    path: string;
-    manifest: PortableSkillManifest;
-    created: boolean;
-}
-export interface PortableSkillRunOptions extends PortableSkillOptions {
-    stdio?: "inherit" | "pipe";
-    env?: Record<string, string>;
-}
-export interface PortableSkillRunResult {
-    exitCode: number;
-    stdout?: string;
-    stderr?: string;
-    error?: string;
-}
-export declare function normalizePortableSkillName(name: string): string;
 export declare function getPortableSkillsRoot(options?: PortableSkillOptions): string;
 export declare function getPortableSkillPath(name: string, options?: PortableSkillOptions): string;
 export declare function findPortableSkill(name: string, options?: PortableSkillOptions): PortableSkillSummary | null;
 export declare function listPortableSkills(options?: PortableSkillOptions): PortableSkillSummary[];
 export declare function listPortableSkillMetas(options?: PortableSkillOptions): SkillMeta[];
-export declare function readPortableSkillManifest(skillPath: string, fallbackName?: string): PortableSkillManifest;
 export declare function isOfficialSkillName(name: string): boolean;
 export declare function scaffoldPortableSkill(name: string, options?: ScaffoldPortableSkillOptions): PortableSkillWriteResult;
 /**
@@ -120,5 +38,36 @@ export declare function scaffoldPortableSkill(name: string, options?: ScaffoldPo
  */
 export declare function portPortableSkillDirectory(sourceDir: string, options?: BulkPortPortableSkillOptions): BulkPortResult;
 export declare function portPortableSkill(sourcePath: string, options?: PortPortableSkillOptions): PortableSkillWriteResult;
+/** Metadata a Skills instance reports for a skill, used to fill the corpus manifest. */
+export interface CorpusSkillMeta {
+    displayName?: string;
+    description?: string;
+    category?: string;
+    tags?: string[];
+    version?: string;
+    kind?: SkillKind;
+}
+export interface WriteCorpusSkillInput {
+    name: string;
+    /** The SKILL.md document as served by the instance. Written verbatim. */
+    skillMd: string;
+    meta?: CorpusSkillMeta | null;
+}
+/**
+ * Write a skill fetched from a Skills instance into the local corpus
+ * (~/.hasna/skills/installed/<name>/), so loadRegistry() surfaces it to both the CLI
+ * (`skills list --all`) and the MCP (`list_skills`) with no further step — the whole
+ * point of the pull: the corpus is already a first-class registry source.
+ *
+ * SKILL.md is written verbatim: it is the agent-facing artifact and the registry's
+ * frontmatter source. A canonical skill.json is written beside it so
+ * listPortableSkillMetas() reports the right kind/category/tags/version even when the
+ * fetched SKILL.md carries thin frontmatter.
+ *
+ * Idempotent: re-writing the same fetched bytes yields byte-identical files. It
+ * overwrites SKILL.md and skill.json — the instance is the source of truth for a pulled
+ * skill — but removes nothing else, so a re-pull never destroys sibling files.
+ */
+export declare function writeCorpusSkill(input: WriteCorpusSkillInput, options?: PortableSkillOptions): PortableSkillWriteResult;
 export declare function validatePortableSkillDirectory(name: string, skillPath: string): SkillValidationResult;
 export declare function runPortableSkill(name: string, args: string[], options?: PortableSkillRunOptions): Promise<PortableSkillRunResult>;

package/dist/lib/pull.d.ts

@@ -0,0 +1,41 @@
+import { type PortableSkillOptions } from "./portable-skills.js";
+import type { SkillKind } from "./registry-types.js";
+/**
+ * The slice of RemoteSkillsClient that `pullSkills` needs. Narrowed to an interface so a
+ * test can inject a fake and the real HTTP client (which satisfies it structurally) is
+ * only constructed on the production path.
+ */
+export interface SkillPullClient {
+    listSkills(): Promise<unknown[]>;
+    getSkill(slug: string): Promise<unknown>;
+    getSkillMd(slug: string): Promise<string | null>;
+}
+export interface PullSkillsOptions extends PortableSkillOptions {
+    /** Explicit skill names to pull. Ignored when `all` is set. */
+    names?: string[];
+    /** Pull every skill the instance serves. */
+    all?: boolean;
+    /**
+     * Client override. `undefined` (the default) resolves one from configuration;
+     * `null` models "no credential available" so the null-handling path stays testable.
+     */
+    client?: SkillPullClient | null;
+}
+export interface PulledSkillResult {
+    name: string;
+    success: boolean;
+    path?: string;
+    kind?: SkillKind;
+    version?: string;
+    /** True when the pull created the corpus entry, false when it updated an existing one. */
+    created?: boolean;
+    error?: string;
+}
+export interface PullSkillsResult {
+    results: PulledSkillResult[];
+}
+export declare class PullSkillError extends Error {
+    readonly detail?: string[] | undefined;
+    constructor(message: string, detail?: string[] | undefined);
+}
+export declare function pullSkills(options?: PullSkillsOptions): Promise<PullSkillsResult>;