@agentxm/extension-authoring 0.28.11 → 0.28.13

package/dist/src/create/errors.js

@@ -0,0 +1,54 @@
+/**
+ * Typed refusals the authoring request phase can settle with.
+ *
+ * Each one carries the facts a person needs to recover — the owners they
+ * could have meant, the settings file that records ownership, the name rule
+ * their name broke — and none of them carries rendered prose. The
+ * application boundary owns the sentence; the feature owns the decision.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+/**
+ * No owner is configured for the selected workspace and none was named, so
+ * the package has no authorship to carry. `candidates` are the owners the
+ * person could plausibly have meant, most local first; it may be empty.
+ */
+export class AuthoringOwnerRequired extends Schema.TaggedError()("AuthoringOwnerRequired", {
+    /** The thing being authored, e.g. `skill`. */
+    subject: Schema.String,
+    /** The command route, so a recovery action is a runnable command. */
+    command: Schema.String,
+    /** The name the person asked to create. */
+    name: Schema.String,
+    /** Owners the person could have meant, most local first. */
+    candidates: Schema.Array(Schema.String),
+    /** Workspace-relative settings file that would record the owner. */
+    settingsPath: Schema.String,
+}) {
+}
+/** An explicitly named owner disagrees with the one the workspace records. */
+export class AuthoringOwnerMismatch extends Schema.TaggedError()("AuthoringOwnerMismatch", {
+    requested: Schema.String,
+    configured: Schema.String,
+}) {
+}
+/** The requested name is not a name an authored package can carry. */
+export class ScaffoldNameInvalid extends Schema.TaggedError()("ScaffoldNameInvalid", {
+    subject: Schema.String,
+    name: Schema.String,
+    /** The pattern source every authored name matches. */
+    pattern: Schema.String,
+    maxLength: Schema.Number,
+}) {
+}
+/**
+ * Authoring was requested in a workspace scope that does not hold authored
+ * packages. Only the project workspace does.
+ */
+export class AuthoringScopeUnsupported extends Schema.TaggedError()("AuthoringScopeUnsupported", {
+    subject: Schema.String,
+    scope: Schema.String,
+}) {
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/create/scaffold-name.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The name and owner vocabulary every authored package is created under.
+ *
+ * One pattern, one length bound, one owner normalization for all seven
+ * extension types: the name an author types becomes a directory name, a
+ * settings key, and a Registry package name, so a type that accepted a
+ * different shape would author packages the rest of the system cannot name.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const SCAFFOLD_NAME_PATTERN: RegExp;
+export declare const SCAFFOLD_NAME_MAX_LENGTH = 64;
+export declare const isValidScaffoldName: (name: string) => boolean;
+export declare const normalizeScaffoldOwner: (owner: string) => string & import("effect/Brand").Brand<"Handle">;
+//# sourceMappingURL=scaffold-name.d.ts.map

package/dist/src/create/scaffold-name.js

@@ -0,0 +1,16 @@
+/**
+ * The name and owner vocabulary every authored package is created under.
+ *
+ * One pattern, one length bound, one owner normalization for all seven
+ * extension types: the name an author types becomes a directory name, a
+ * settings key, and a Registry package name, so a type that accepted a
+ * different shape would author packages the rest of the system cannot name.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import { normalizeHandle } from "@agentxm/extension-model/unstable/extensions";
+export const SCAFFOLD_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+export const SCAFFOLD_NAME_MAX_LENGTH = 64;
+export const isValidScaffoldName = (name) => name.length > 0 && name.length <= SCAFFOLD_NAME_MAX_LENGTH && SCAFFOLD_NAME_PATTERN.test(name);
+export const normalizeScaffoldOwner = (owner) => normalizeHandle(owner.startsWith("@") ? owner : `@${owner}`);
+//# sourceMappingURL=scaffold-name.js.map

package/dist/src/create/scaffolds/hook.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The starter content a new hook is created with, including the matcher a
+ * tool-scoped binding defaults to.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Option from "effect/Option";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import { type HookEvent, type HookRuntime } from "@agentxm/extension-model/unstable/hooks/manifest-schema";
+import { type AuthoredScaffold } from "./scaffold.js";
+export declare const hookEntrypointFilename: (runtime: HookRuntime) => string;
+export declare const hookScaffold: (args: {
+    readonly name: string;
+    readonly owner: Handle;
+    readonly runtime: HookRuntime;
+    readonly event: HookEvent;
+    readonly matcher: Option.Option<string>;
+}) => AuthoredScaffold;
+//# sourceMappingURL=hook.d.ts.map

package/dist/src/create/scaffolds/hook.js

@@ -0,0 +1,118 @@
+/**
+ * The starter content a new hook is created with, including the matcher a
+ * tool-scoped binding defaults to.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { decodeExtensionNameSync } from "@agentxm/extension-model/unstable/extensions";
+import { HOOK_EXTENSION_DIR, HOOK_MANIFEST_FILENAME, HOOK_MANIFEST_SCHEMA_URL, } from "@agentxm/extension-model/unstable/hooks/manifest-schema";
+import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
+import { manifestText, stageFileAt } from "./scaffold.js";
+const INITIAL_VERSION = decodeVersionSync("0.1.0");
+/**
+ * Tool events fire on every tool call, so a scaffold that bound them without
+ * a matcher would run the new hook against unrelated tools from its first
+ * invocation. The two write tools are the ones an author almost always means.
+ */
+const DEFAULT_TOOL_MATCHER = "Write|Edit";
+/** Only tool-scoped events carry a matcher; the rest ignore one if given. */
+const isToolEvent = (event) => event === "tool.pre" || event === "tool.post";
+export const hookEntrypointFilename = (runtime) => {
+    switch (runtime) {
+        case "bash":
+            return "hook.sh";
+        case "node":
+            return "hook.js";
+        case "python":
+            return "hook.py";
+    }
+};
+const entrypointBody = (runtime, fqn) => {
+    switch (runtime) {
+        case "bash":
+            return `#!/usr/bin/env bash
+# ${fqn}
+# Receives the agent hook event payload as JSON on stdin.
+set -euo pipefail
+
+payload="$(cat)"
+
+# TODO: inspect "$payload" and implement the hook.
+# Emit JSON on stdout or exit non-zero to influence the agent.
+exit 0
+`;
+        case "node":
+            return `#!/usr/bin/env node
+// ${fqn}
+// Receives the agent hook event payload as JSON on stdin.
+let raw = "";
+process.stdin.on("data", (chunk) => {
+  raw += chunk;
+});
+process.stdin.on("end", () => {
+  const payload = raw ? JSON.parse(raw) : {};
+
+  // TODO: inspect payload and implement the hook.
+  // Emit JSON on stdout or exit non-zero to influence the agent.
+  process.exit(0);
+});
+`;
+        case "python":
+            return `#!/usr/bin/env python3
+"""${fqn}
+
+Receives the agent hook event payload as JSON on stdin.
+"""
+import json
+import sys
+
+raw = sys.stdin.read()
+payload = json.loads(raw) if raw else {}
+
+# TODO: inspect payload and implement the hook.
+# Emit JSON on stdout or exit non-zero to influence the agent.
+sys.exit(0)
+`;
+    }
+};
+export const hookScaffold = (args) => {
+    const entrypointFile = hookEntrypointFilename(args.runtime);
+    const entrypoint = `src/${entrypointFile}`;
+    const matcher = isToolEvent(args.event)
+        ? Option.getOrElse(args.matcher, () => DEFAULT_TOOL_MATCHER)
+        : undefined;
+    const fqn = `${args.owner}/${HOOK_EXTENSION_DIR}/${args.name}`;
+    const manifest = {
+        $schema: HOOK_MANIFEST_SCHEMA_URL,
+        owner: args.owner,
+        type: "hook",
+        name: decodeExtensionNameSync(args.name),
+        version: INITIAL_VERSION,
+        runtime: args.runtime,
+        entrypoint,
+        bindings: [
+            matcher === undefined ? { on: args.event } : { on: args.event, matcherRaw: matcher },
+        ],
+    };
+    return {
+        subject: "Hook",
+        version: INITIAL_VERSION,
+        contentFiles: [HOOK_MANIFEST_FILENAME, entrypoint],
+        entryFile: entrypoint,
+        populate: (stagingPath) => Effect.gen(function* () {
+            const path = yield* Path.Path;
+            yield* stageFileAt({
+                path: path.join(stagingPath, HOOK_MANIFEST_FILENAME),
+                contents: manifestText(manifest),
+            });
+            yield* stageFileAt({
+                path: path.join(stagingPath, "src", entrypointFile),
+                contents: entrypointBody(args.runtime, fqn),
+            });
+        }),
+    };
+};
+//# sourceMappingURL=hook.js.map

package/dist/src/create/scaffolds/knowledge.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The starter content a new Knowledge bundle is created with.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Option from "effect/Option";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import { type AuthoredScaffold } from "./scaffold.js";
+export declare const knowledgeScaffold: (args: {
+    readonly name: string;
+    readonly owner: Handle;
+    readonly description: Option.Option<string>;
+}) => AuthoredScaffold;
+//# sourceMappingURL=knowledge.d.ts.map

package/dist/src/create/scaffolds/knowledge.js

@@ -0,0 +1,45 @@
+/**
+ * The starter content a new Knowledge bundle is created with.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { decodeExtensionNameSync } from "@agentxm/extension-model/unstable/extensions";
+import { KNOWLEDGE_MANIFEST_FILENAME, KNOWLEDGE_MANIFEST_SCHEMA_URL, KNOWLEDGE_SOURCE_DIR, } from "@agentxm/extension-model/unstable/knowledge";
+import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
+import { manifestText, stageFileAt } from "./scaffold.js";
+const BUNDLE_INDEX = `${KNOWLEDGE_SOURCE_DIR}/index.md`;
+const INITIAL_VERSION = decodeVersionSync("0.1.0");
+export const knowledgeScaffold = (args) => {
+    const name = decodeExtensionNameSync(args.name);
+    const manifest = {
+        $schema: KNOWLEDGE_MANIFEST_SCHEMA_URL,
+        owner: args.owner,
+        name,
+        version: INITIAL_VERSION,
+        type: "knowledge",
+        format: { name: "okf", version: "0.2" },
+        bundleRoot: KNOWLEDGE_SOURCE_DIR,
+        ...(Option.isSome(args.description) ? { description: args.description.value } : {}),
+    };
+    return {
+        subject: "Knowledge bundle",
+        version: INITIAL_VERSION,
+        contentFiles: [KNOWLEDGE_MANIFEST_FILENAME, BUNDLE_INDEX],
+        entryFile: BUNDLE_INDEX,
+        populate: (stagingPath) => Effect.gen(function* () {
+            const path = yield* Path.Path;
+            yield* stageFileAt({
+                path: path.join(stagingPath, KNOWLEDGE_MANIFEST_FILENAME),
+                contents: manifestText(manifest),
+            });
+            yield* stageFileAt({
+                path: path.join(stagingPath, KNOWLEDGE_SOURCE_DIR, "index.md"),
+                contents: `---\nokf_version: "0.2"\n---\n# ${name}\n\n<!-- Discovery map: describe this bundle's scope, then group and annotate links to its concepts. -->\n`,
+            });
+        }),
+    };
+};
+//# sourceMappingURL=knowledge.js.map

package/dist/src/create/scaffolds/mcp-server.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The starter manifest a new MCP server is created with.
+ *
+ * The scaffold declares a placeholder npm stdio package under an example
+ * reverse-DNS server name: a new server has no published artifact yet, and
+ * the author replaces both before publishing.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import { type AuthoredScaffold } from "./scaffold.js";
+export declare const mcpServerScaffold: (args: {
+    readonly name: string;
+    readonly owner: Handle;
+    readonly description: string;
+}) => AuthoredScaffold;
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/src/create/scaffolds/mcp-server.js

@@ -0,0 +1,57 @@
+/**
+ * The starter manifest a new MCP server is created with.
+ *
+ * The scaffold declares a placeholder npm stdio package under an example
+ * reverse-DNS server name: a new server has no published artifact yet, and
+ * the author replaces both before publishing.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
+import { decodeExtensionNameSync } from "@agentxm/extension-model/unstable/extensions";
+import { MCP_SERVER_MANIFEST_FILENAME, MCP_SERVER_MANIFEST_SCHEMA_URL, MCP_SERVER_REGISTRY_SERVER_SCHEMA_URL, } from "@agentxm/extension-model/unstable/mcps/manifest-schema";
+import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
+import { manifestText, stageFileAt } from "./scaffold.js";
+const INITIAL_VERSION = decodeVersionSync("0.1.0");
+const PLACEHOLDER_SERVER_NAMESPACE = "io.github.example";
+export const mcpServerScaffold = (args) => {
+    const description = args.description || `MCP server ${args.name}`;
+    const manifest = {
+        $schema: MCP_SERVER_MANIFEST_SCHEMA_URL,
+        owner: args.owner,
+        type: "mcp-server",
+        name: decodeExtensionNameSync(args.name),
+        version: INITIAL_VERSION,
+        description,
+        license: "MIT",
+        server: {
+            $schema: MCP_SERVER_REGISTRY_SERVER_SCHEMA_URL,
+            name: `${PLACEHOLDER_SERVER_NAMESPACE}/${args.name}`,
+            description,
+            version: INITIAL_VERSION,
+            packages: [
+                {
+                    registryType: "npm",
+                    identifier: args.name,
+                    version: INITIAL_VERSION,
+                    transport: { type: "stdio" },
+                },
+            ],
+        },
+    };
+    return {
+        subject: "MCP server",
+        version: INITIAL_VERSION,
+        contentFiles: [MCP_SERVER_MANIFEST_FILENAME],
+        entryFile: MCP_SERVER_MANIFEST_FILENAME,
+        populate: (stagingPath) => Effect.gen(function* () {
+            const path = yield* Path.Path;
+            yield* stageFileAt({
+                path: path.join(stagingPath, MCP_SERVER_MANIFEST_FILENAME),
+                contents: manifestText(manifest),
+            });
+        }),
+    };
+};
+//# sourceMappingURL=mcp-server.js.map

package/dist/src/create/scaffolds/pack.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The starter manifest a new pack is created with: an empty membership the
+ * author fills with `axm packs add`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import { type AuthoredScaffold } from "./scaffold.js";
+export declare const packScaffold: (args: {
+    readonly name: string;
+    readonly owner: Handle;
+}) => AuthoredScaffold;
+//# sourceMappingURL=pack.d.ts.map

package/dist/src/create/scaffolds/pack.js

@@ -0,0 +1,37 @@
+/**
+ * The starter manifest a new pack is created with: an empty membership the
+ * author fills with `axm packs add`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
+import { decodeExtensionNameSync } from "@agentxm/extension-model/unstable/extensions";
+import { PACK_MANIFEST_FILENAME, PACK_MANIFEST_SCHEMA_URL, } from "@agentxm/extension-model/unstable/packs/manifest-schema";
+import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
+import { manifestText, stageFileAt } from "./scaffold.js";
+const INITIAL_VERSION = decodeVersionSync("0.0.1");
+export const packScaffold = (args) => {
+    const manifest = {
+        $schema: PACK_MANIFEST_SCHEMA_URL,
+        owner: args.owner,
+        type: "pack",
+        name: decodeExtensionNameSync(args.name),
+        version: INITIAL_VERSION,
+        dependencies: {},
+    };
+    return {
+        subject: "Pack",
+        version: INITIAL_VERSION,
+        contentFiles: [PACK_MANIFEST_FILENAME],
+        entryFile: PACK_MANIFEST_FILENAME,
+        populate: (stagingPath) => Effect.gen(function* () {
+            const path = yield* Path.Path;
+            yield* stageFileAt({
+                path: path.join(stagingPath, PACK_MANIFEST_FILENAME),
+                contents: manifestText(manifest),
+            });
+        }),
+    };
+};
+//# sourceMappingURL=pack.js.map

package/dist/src/create/scaffolds/rule.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The starter content a new rule is created with.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Option from "effect/Option";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import { type AuthoredScaffold } from "./scaffold.js";
+export declare const ruleScaffold: (args: {
+    readonly name: string;
+    readonly owner: Handle;
+    readonly title: Option.Option<string>;
+}) => AuthoredScaffold;
+//# sourceMappingURL=rule.d.ts.map

package/dist/src/create/scaffolds/rule.js

@@ -0,0 +1,46 @@
+/**
+ * The starter content a new rule is created with.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { decodeExtensionNameSync } from "@agentxm/extension-model/unstable/extensions";
+import { RULE_BODY_FILENAME, RULE_MANIFEST_FILENAME, RULE_MANIFEST_SCHEMA_URL, } from "@agentxm/extension-model/unstable/rules/manifest-schema";
+import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
+import { manifestText, stageFileAt } from "./scaffold.js";
+/** Rule bodies live under `src/` alongside every other package-body type. */
+const RULE_SOURCE_DIR = "src";
+const RULE_BODY = `${RULE_SOURCE_DIR}/${RULE_BODY_FILENAME}`;
+const INITIAL_VERSION = decodeVersionSync("0.1.0");
+export const ruleScaffold = (args) => {
+    const name = decodeExtensionNameSync(args.name);
+    const title = Option.getOrElse(args.title, () => String(name));
+    const manifest = {
+        $schema: RULE_MANIFEST_SCHEMA_URL,
+        owner: args.owner,
+        name,
+        version: INITIAL_VERSION,
+        type: "rule",
+        title,
+    };
+    return {
+        subject: "Rule",
+        version: INITIAL_VERSION,
+        contentFiles: [RULE_MANIFEST_FILENAME, RULE_BODY],
+        entryFile: RULE_BODY,
+        populate: (stagingPath) => Effect.gen(function* () {
+            const path = yield* Path.Path;
+            yield* stageFileAt({
+                path: path.join(stagingPath, RULE_MANIFEST_FILENAME),
+                contents: manifestText(manifest),
+            });
+            yield* stageFileAt({
+                path: path.join(stagingPath, RULE_SOURCE_DIR, RULE_BODY_FILENAME),
+                contents: `# ${title}\n\nDescribe the behavior this rule asks agents to follow.\n`,
+            });
+        }),
+    };
+};
+//# sourceMappingURL=rule.js.map

package/dist/src/create/scaffolds/scaffold.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What a scaffold for one extension type contributes to a creation.
+ *
+ * Everything that differs between the seven types — the manifest, the starter
+ * body, the file the author edits next, the initial version — is decided
+ * here; everything they share — ownership, naming, the canonical location,
+ * the create-only preflight, desired state, projection, the transaction — is
+ * decided once by the create use case.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type { Version } from "@agentxm/extension-model/unstable/version-constraints";
+import { AuthoringFailed } from "../../errors.js";
+/** One extension type's contribution to a creation. */
+export interface AuthoredScaffold {
+    /** Sentence-cased subject used in refusals, e.g. `Knowledge bundle`. */
+    readonly subject: string;
+    /** Version the scaffolded manifest carries. */
+    readonly version: Version;
+    /**
+     * Package-relative files the scaffold writes, in the order a plan lists
+     * them. They are also the files the canonical staging requires before the
+     * package is swapped into place.
+     */
+    readonly contentFiles: ReadonlyArray<string>;
+    /** Package-relative file the author edits next. */
+    readonly entryFile: string;
+    /** Write the package body into a staging directory. */
+    readonly populate: (stagingPath: string) => Effect.Effect<void, AuthoringFailed, FileSystem.FileSystem | Path.Path>;
+}
+/** Serialize a manifest the way every authored manifest is written. */
+export declare const manifestText: (manifest: unknown) => string;
+/**
+ * Create a directory inside the staging tree, reporting the failure as an
+ * authoring failure rather than a raw platform error.
+ */
+export declare const stageDirectory: (directory: string) => Effect.Effect<void, AuthoringFailed, FileSystem.FileSystem>;
+/** Write one staged file, naming the file in the failure. */
+export declare const stageFile: (args: {
+    readonly path: string;
+    readonly contents: string;
+}) => Effect.Effect<void, AuthoringFailed, FileSystem.FileSystem>;
+/** Stage a file and every directory above it inside the staging tree. */
+export declare const stageFileAt: (args: {
+    readonly path: string;
+    readonly contents: string;
+}) => Effect.Effect<void, AuthoringFailed, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/src/create/scaffolds/scaffold.js

@@ -0,0 +1,45 @@
+/**
+ * What a scaffold for one extension type contributes to a creation.
+ *
+ * Everything that differs between the seven types — the manifest, the starter
+ * body, the file the author edits next, the initial version — is decided
+ * here; everything they share — ownership, naming, the canonical location,
+ * the create-only preflight, desired state, projection, the transaction — is
+ * decided once by the create use case.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { AuthoringFailed } from "../../errors.js";
+/** Serialize a manifest the way every authored manifest is written. */
+export const manifestText = (manifest) => `${JSON.stringify(manifest, null, 2)}\n`;
+/**
+ * Create a directory inside the staging tree, reporting the failure as an
+ * authoring failure rather than a raw platform error.
+ */
+export const stageDirectory = (directory) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    yield* fs.makeDirectory(directory, { recursive: true }).pipe(Effect.mapError((cause) => new AuthoringFailed({
+        category: "internal",
+        detail: `Failed to create the staged directory ${directory}`,
+        cause,
+    })));
+});
+/** Write one staged file, naming the file in the failure. */
+export const stageFile = (args) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    yield* fs.writeFileString(args.path, args.contents).pipe(Effect.mapError((cause) => new AuthoringFailed({
+        category: "internal",
+        detail: `Failed to write the staged file ${args.path}`,
+        cause,
+    })));
+});
+/** Stage a file and every directory above it inside the staging tree. */
+export const stageFileAt = (args) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    yield* stageDirectory(path.dirname(args.path));
+    yield* stageFile(args);
+});
+//# sourceMappingURL=scaffold.js.map

package/dist/src/create/scaffolds/skill.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The starter content a new skill is created with.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import { type AuthoredScaffold } from "./scaffold.js";
+export declare const skillScaffold: (args: {
+    readonly name: string;
+    readonly owner: Handle;
+}) => AuthoredScaffold;
+//# sourceMappingURL=skill.d.ts.map

package/dist/src/create/scaffolds/skill.js

@@ -0,0 +1,47 @@
+/**
+ * The starter content a new skill is created with.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
+import { decodeExtensionNameSync } from "@agentxm/extension-model/unstable/extensions";
+import { MANIFEST_FILENAME, MANIFEST_SCHEMA_URL, } from "@agentxm/extension-model/unstable/skills/manifest-schema";
+import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
+import { manifestText, stageFileAt } from "./scaffold.js";
+const SKILL_BODY = "src/SKILL.md";
+const INITIAL_VERSION = decodeVersionSync("0.0.1");
+const skillBody = (name) => `---
+name: ${name}
+description: Describe when this skill should be triggered by the agent
+---
+
+Describe what this skill does and when to use it.
+`;
+export const skillScaffold = (args) => {
+    const manifest = {
+        $schema: MANIFEST_SCHEMA_URL,
+        owner: args.owner,
+        type: "skill",
+        name: decodeExtensionNameSync(args.name),
+        version: INITIAL_VERSION,
+    };
+    return {
+        subject: "Skill",
+        version: INITIAL_VERSION,
+        contentFiles: [MANIFEST_FILENAME, SKILL_BODY],
+        entryFile: SKILL_BODY,
+        populate: (stagingPath) => Effect.gen(function* () {
+            const path = yield* Path.Path;
+            yield* stageFileAt({
+                path: path.join(stagingPath, MANIFEST_FILENAME),
+                contents: manifestText(manifest),
+            });
+            yield* stageFileAt({
+                path: path.join(stagingPath, ...SKILL_BODY.split("/")),
+                contents: skillBody(args.name),
+            });
+        }),
+    };
+};
+//# sourceMappingURL=skill.js.map

package/dist/src/create/scaffolds/subagent.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The starter content a new subagent is created with.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import { type AuthoredScaffold } from "./scaffold.js";
+export declare const subagentScaffold: (args: {
+    readonly name: string;
+    readonly owner: Handle;
+}) => AuthoredScaffold;
+//# sourceMappingURL=subagent.d.ts.map