@praxis-ai/praxis 0.1.5 → 0.1.6

package/dist/agentCore/index.d.ts

@@ -29,6 +29,8 @@ import { buildMcpServerProfilesFromManifest, createMcpApplicationStateView, crea
 export { PromptPack, PraxisAgent, PraxisAgentArchetype, STATE_PLANE_STANDARD_CONTROLS, append, compileAgent, endpoint, harness, inspectAgentManifest, loop, mainLoop, markdown, markdownFile, model, modelFleet, overwrite, policy, prepend, replaceLastLines, sandbox, session, statePlane, storage, tool, toolPolicies, tools, validateAgentManifest, type AgentCompileErrorCode, type AgentCompileResult, type AgentIdentity, type AgentManifest, type AgentManifestInspection, type AgentManifestValidationResult, type BaseToolPolicyDecision, type BaseToolPolicyMatrixSpec, type BaseToolPolicyProfile, type BaseToolPolicyRisk, type BaseToolPolicyRule, type HarnessSpec, type FrameworkCoreContractSpec, type LoopSpec, type MainLoopSpec, type ModelEndpointSpec, type ModelFleetSpec, type ModelSpec, type PolicySpec, type PraxisAgentClass, type PraxisAgentInput, type PromptMaterialSource, type PromptPackSpec, type PromptPatchSpec, type SandboxSpec, type SandboxIsolationLevel, type SandboxMountPolicy, type SandboxNetworkRuntimePolicy, type SandboxPlatformSupport, type SandboxPlatformSupportStatus, type SandboxProcessPolicy, type SandboxProviderFamily, type SessionSpec, type StatePlaneSpec, type StorageSpec, type ToolSpec, type ToolPolicyCustomInput, } from "../runtimeImplementation/runtimeAgentManifest.js";
 export { buildMcpServerProfilesFromManifest, createMcpApplicationStateView, createFileMcpPlusProfileStore, createFileMcpPlusSkillStore, createInMemoryMcpPlusOverlayStore, createInMemoryMcpPlusProfileStore, createInMemoryMcpPlusSkillStore, mcp, planMcpHarnessExposure, };
 export type { McpApplicationServerView, McpApplicationServerInput, McpApplicationStateView, McpHarnessExposurePlan, McpHarnessModuleSpec, McpHarnessServerMode, McpHarnessServerSpec, McpPlusLearnedProfile, McpPlusApplicationServerInput, McpPlusOverlayStore, McpPlusOverlayStoreKey, McpPlusProfileProposal, McpPlusProfileStore, McpPlusProfileStoreKey, McpPlusRuntimeOverlay, McpPlusSkillNote, McpPlusSkillStore, McpTransportSpec, } from "../runtimeImplementation/runtime.mcpPlane/index.js";
+export { adviseSkillPromotion, createFileSkillPlaneStore, createInMemorySkillPlaneStore, createSkillWriteProposal, loadSkillHeadsFromSource, loadSkillHeadsFromSources, renderSkillIndexMaterial, skill, } from "../runtimeImplementation/runtime.skillPlane/index.js";
+export type { SkillBody, SkillHead, SkillPlaneBodyLoadPolicy, SkillPlaneIndexPolicy, SkillPlaneLifecyclePolicy, SkillPlaneModuleSpec, SkillPlanePromotionState, SkillPlaneSourceResolutionInput, SkillPlaneScope, SkillPlaneStore, SkillSourceSpec, SkillPromotionAdvice, SkillWriteProposal, } from "../runtimeImplementation/runtime.skillPlane/index.js";
 export { createMemoryPlane, memoryPlane, };
 export type { MemoryArtifactRef, MemoryIndexStatus, MemoryLayout, MemoryPlane, MemoryPlaneOptions, MemoryPolicyRisk, MemoryProfile, MemoryPromptGuide, MemoryReindexResult, MemoryRiskMetadata, MemoryScope, MemorySearchGuide, MemorySearchRequest, MemorySourceType, } from "../memory_managementPool/index.js";
 export { capabilities, capability, createProvisionPlan, dependencies, dependencyAuthoring, provisionRuntimeDescriptor, type CapabilityFallbackSpec, type CapabilityInput, type CapabilityKind, type CapabilityPolicySpec, type CapabilityReadiness, type CapabilitySpec, type CodeIntelligenceCapabilityInput, type ProvisionPlan, type SandboxCapabilityInput, } from "../runtimeImplementation/runtime.provisionPlane/index.js";
@@ -670,6 +672,22 @@ export declare const praxis: Readonly<{
         sqlite(input?: Omit<import("../runtimeImplementation/runtimeAgentManifest.js").StorageSpec, "kind">): import("../runtimeImplementation/runtimeAgentManifest.js").StorageSpec;
         raxWorkspace(input?: Omit<import("../runtimeImplementation/runtimeAgentManifest.js").StorageSpec, "kind">): import("../runtimeImplementation/runtimeAgentManifest.js").StorageSpec;
     };
+    skill: {
+        readonly directory: (directoryPath: string, input?: {
+            scope?: import("../runtimeImplementation/runtime.skillPlane/index.js").SkillPlaneScope;
+        }) => import("../runtimeImplementation/runtime.skillPlane/index.js").SkillSourceSpec;
+        readonly package: (packageName: string, input?: {
+            scope?: import("../runtimeImplementation/runtime.skillPlane/index.js").SkillPlaneScope;
+        }) => import("../runtimeImplementation/runtime.skillPlane/index.js").SkillSourceSpec;
+        readonly inline: (heads: readonly import("../runtimeImplementation/runtime.skillPlane/index.js").SkillHead[]) => import("../runtimeImplementation/runtime.skillPlane/index.js").SkillSourceSpec;
+        readonly module: (input?: {
+            sources?: readonly import("../runtimeImplementation/runtime.skillPlane/index.js").SkillSourceSpec[];
+            indexPolicy?: Partial<import("../runtimeImplementation/runtime.skillPlane/index.js").SkillPlaneIndexPolicy>;
+            bodyLoadPolicy?: Partial<import("../runtimeImplementation/runtime.skillPlane/index.js").SkillPlaneBodyLoadPolicy>;
+            lifecycle?: Partial<import("../runtimeImplementation/runtime.skillPlane/index.js").SkillPlaneLifecyclePolicy>;
+            metadata?: Readonly<Record<string, unknown>>;
+        }) => import("../runtimeImplementation/runtime.skillPlane/index.js").SkillPlaneModuleSpec;
+    };
     memory: Readonly<{
         create: typeof createMemoryPlane;
         initialize: (options?: import("../memory_managementPool/types.js").MemoryPlaneOptions) => Promise<import("../memory_managementPool/types.js").MemoryIndexStatus>;

package/dist/agentCore/index.js

@@ -32,8 +32,10 @@ import { createObservationMaterial, } from "../executionEngine/coreLogic/observa
 import { runtimeAuth, } from "../runtimeImplementation/runtime.authPlane/index.js";
 import { createMemoryPlane, memoryPlane, } from "../memory_managementPool/index.js";
 import { buildMcpServerProfilesFromManifest, createMcpApplicationStateView, createFileMcpPlusProfileStore, createFileMcpPlusSkillStore, createInMemoryMcpPlusOverlayStore, createInMemoryMcpPlusProfileStore, createInMemoryMcpPlusSkillStore, mcp, planMcpHarnessExposure, } from "../runtimeImplementation/runtime.mcpPlane/index.js";
+import { skill, } from "../runtimeImplementation/runtime.skillPlane/index.js";
 export { PromptPack, PraxisAgent, PraxisAgentArchetype, STATE_PLANE_STANDARD_CONTROLS, append, compileAgent, endpoint, harness, inspectAgentManifest, loop, mainLoop, markdown, markdownFile, model, modelFleet, overwrite, policy, prepend, replaceLastLines, sandbox, session, statePlane, storage, tool, toolPolicies, tools, validateAgentManifest, } from "../runtimeImplementation/runtimeAgentManifest.js";
 export { buildMcpServerProfilesFromManifest, createMcpApplicationStateView, createFileMcpPlusProfileStore, createFileMcpPlusSkillStore, createInMemoryMcpPlusOverlayStore, createInMemoryMcpPlusProfileStore, createInMemoryMcpPlusSkillStore, mcp, planMcpHarnessExposure, };
+export { adviseSkillPromotion, createFileSkillPlaneStore, createInMemorySkillPlaneStore, createSkillWriteProposal, loadSkillHeadsFromSource, loadSkillHeadsFromSources, renderSkillIndexMaterial, skill, } from "../runtimeImplementation/runtime.skillPlane/index.js";
 export { createMemoryPlane, memoryPlane, };
 export { capabilities, capability, createProvisionPlan, dependencies, dependencyAuthoring, provisionRuntimeDescriptor, } from "../runtimeImplementation/runtime.provisionPlane/index.js";
 export { component, createRuntimeComponentRegistry, lookupRuntimeComponent, officialRuntimeComponents, } from "../runtimeImplementation/runtime.componentPlane/index.js";
@@ -288,6 +290,7 @@ export const praxis = Object.freeze({
     project: defineProject,
     statePlane,
     storage,
+    skill,
     memory,
     basetool,
     basetools: basetool,

package/dist/executionEngine/promptPack/promptAssembler.js

@@ -59,6 +59,7 @@ function segmentStability(kind) {
     if (kind === "stableSystemCore" ||
         kind === "declaredRuntimeContext" ||
         kind === "toolDeclarations" ||
+        kind === "skillIndex" ||
         kind === "projectContext") {
         return "static";
     }

package/dist/executionEngine/promptPack/promptDefiner.d.ts

@@ -2,9 +2,9 @@ export declare const PROMPT_PACK_INTERNAL_MATERIAL_KINDS: readonly ["system", "u
 export type PromptPackInternalMaterialKind = (typeof PROMPT_PACK_INTERNAL_MATERIAL_KINDS)[number];
 export type PromptPackMaterialKind = PromptPackInternalMaterialKind | "tool-summary" | "command-injection";
 export type PromptPackMaterialSourceCategory = "declared-built-in" | "process-product" | "user-request";
-export declare const PROMPT_PACK_SEGMENT_KINDS: readonly ["stableSystemCore", "declaredRuntimeContext", "toolDeclarations", "projectContext", "sessionSummary", "recentConversation", "memoryContext", "retrievedContext", "observations", "userTurn", "assistantScratchpadPlan"];
+export declare const PROMPT_PACK_SEGMENT_KINDS: readonly ["stableSystemCore", "declaredRuntimeContext", "toolDeclarations", "skillIndex", "projectContext", "sessionSummary", "recentConversation", "memoryContext", "retrievedContext", "observations", "userTurn", "assistantScratchpadPlan"];
 export type PromptPackSegmentKind = (typeof PROMPT_PACK_SEGMENT_KINDS)[number];
-export declare const PROMPT_PACK_PROVIDER_VISIBLE_SEGMENT_KINDS: ("stableSystemCore" | "declaredRuntimeContext" | "toolDeclarations" | "projectContext" | "sessionSummary" | "recentConversation" | "memoryContext" | "retrievedContext" | "observations" | "userTurn")[];
+export declare const PROMPT_PACK_PROVIDER_VISIBLE_SEGMENT_KINDS: ("stableSystemCore" | "declaredRuntimeContext" | "toolDeclarations" | "skillIndex" | "projectContext" | "sessionSummary" | "recentConversation" | "memoryContext" | "retrievedContext" | "observations" | "userTurn")[];
 export declare const BASIC_CORE_PROMPT_MATERIAL_ID: "praxis:basic-core-prompt";
 export declare const BASIC_CORE_PROMPT_SOURCE: "runtime.basicCorePrompt";
 export declare const PROMPT_PACK_TOOL_MATERIAL_TYPES: readonly ["policy", "declaration", "result", "call-state"];
@@ -102,8 +102,8 @@ export declare const promptPackDefinerDescriptor: {
     readonly purpose: "define Praxis internal PromptPack constructs and the protected basic core prompt head";
     readonly internalMaterialKinds: readonly ["system", "user", "tool", "command", "cmp", "memory", "file", "retrieval", "event", "runtime"];
     readonly sourceCategories: readonly ["declared-built-in", "process-product", "user-request"];
-    readonly orderedSegmentKinds: readonly ["stableSystemCore", "declaredRuntimeContext", "toolDeclarations", "projectContext", "sessionSummary", "recentConversation", "memoryContext", "retrievedContext", "observations", "userTurn", "assistantScratchpadPlan"];
-    readonly providerVisibleSegmentKinds: ("stableSystemCore" | "declaredRuntimeContext" | "toolDeclarations" | "projectContext" | "sessionSummary" | "recentConversation" | "memoryContext" | "retrievedContext" | "observations" | "userTurn")[];
+    readonly orderedSegmentKinds: readonly ["stableSystemCore", "declaredRuntimeContext", "toolDeclarations", "skillIndex", "projectContext", "sessionSummary", "recentConversation", "memoryContext", "retrievedContext", "observations", "userTurn", "assistantScratchpadPlan"];
+    readonly providerVisibleSegmentKinds: ("stableSystemCore" | "declaredRuntimeContext" | "toolDeclarations" | "skillIndex" | "projectContext" | "sessionSummary" | "recentConversation" | "memoryContext" | "retrievedContext" | "observations" | "userTurn")[];
     readonly basicCorePromptMaterialId: "praxis:basic-core-prompt";
     readonly providerPayloadCreated: false;
     readonly unsafeSideEffects: false;

package/dist/executionEngine/promptPack/promptDefiner.js

@@ -26,6 +26,7 @@ export const PROMPT_PACK_SEGMENT_KINDS = [
     "stableSystemCore",
     "declaredRuntimeContext",
     "toolDeclarations",
+    "skillIndex",
     "projectContext",
     "sessionSummary",
     "recentConversation",

package/dist/runtimeImplementation/praxisRuntimeKernel.d.ts

@@ -13,6 +13,7 @@ import { type RuntimeBaseToolExecutorPolicy, type RuntimeBaseToolExecutorResourc
 import { type BaseToolDependencyRuntimeMode } from "./runtime.execEngine/baseToolDependencyRuntime.js";
 import { type BaseToolContextSelection, type BaseToolContextUsageRecord } from "./runtime.execEngine/baseToolContextFolding.js";
 import { type PromptContextConversationMessage, type PromptContextSessionSummary } from "./runtime.execEngine/promptContextAssembly.js";
+import { type SkillPlaneStore } from "./runtime.skillPlane/index.js";
 import { type BaseToolPolicyAdjudication } from "./runtime.execEngine/baseToolPolicyAdjudicator.js";
 import { type BaseToolSandboxPlan } from "./runtime.sandboxPlane/baseToolSandboxPlanner.js";
 import type { RuntimeAuthResolver, RuntimeAuthResolverRequest } from "./runtime.authPlane/runtimeAuthResolver.js";
@@ -59,6 +60,9 @@ export type PraxisRuntimeKernelOptions = {
         skillStore?: McpPlusSkillStore;
         reprofileConsecutiveIndexedCalls?: number;
     };
+    skillPlane?: {
+        store?: SkillPlaneStore;
+    };
     baseToolPolicy?: RuntimeBaseToolExecutorPolicy;
     baseToolResourceLimits?: RuntimeBaseToolExecutorResourceLimits;
     store?: RuntimeSessionStateEventStore;

package/dist/runtimeImplementation/praxisRuntimeKernel.js

@@ -27,6 +27,7 @@ import { evaluateBaseToolRuntimeGovernance } from "./runtime.execEngine/baseTool
 import { preflightBaseToolDependencies, } from "./runtime.execEngine/baseToolDependencyRuntime.js";
 import { applyBaseToolContextUsage, createBaseToolContextHeatState, } from "./runtime.execEngine/baseToolContextFolding.js";
 import { assemblePromptContextMaterials, PRAXIS_BASE_TOOL_CALLING_PROTOCOL, } from "./runtime.execEngine/promptContextAssembly.js";
+import { createFileSkillPlaneStore, loadSkillHeadsFromSources, renderSkillIndexMaterial, skillPlaneModuleFrom, } from "./runtime.skillPlane/index.js";
 import { invokeMountedBaseTool } from "./runtime.execEngine/baseToolRuntimeMount.js";
 import { evaluateBaseToolRuntimeReadiness } from "./runtime.execEngine/baseToolSupportCatalog.js";
 import { adjudicateBaseToolPolicy, } from "./runtime.execEngine/baseToolPolicyAdjudicator.js";
@@ -773,6 +774,31 @@ async function discoverRuntimeMcpDynamicSurface(manifest, executor, mcpPlusRunti
         toolDeclarationPreludeMaterials: renderMcpPlusNativePrelude(promptPlan),
     };
 }
+async function discoverRuntimeSkillIndexMaterials(input) {
+    const skillModule = skillPlaneModuleFrom(input.manifest.harness);
+    if (skillModule === undefined)
+        return [];
+    const includeScopes = skillModule.indexPolicy.includeScopes;
+    function scopeMatchesIndexPolicy(head) {
+        const scopes = includeScopes;
+        if (scopes.length === 0)
+            return true;
+        return head.scope !== undefined && scopes.includes(head.scope);
+    }
+    const bySkillId = new Map();
+    for (const head of await loadSkillHeadsFromSources(skillModule.sources, { workspaceRoot: input.workspaceRoot })) {
+        if (scopeMatchesIndexPolicy(head) && !bySkillId.has(head.skillId)) {
+            bySkillId.set(head.skillId, head);
+        }
+    }
+    for (const head of await input.store.listHeads({ scopes: skillModule.indexPolicy.includeScopes })) {
+        if (!bySkillId.has(head.skillId)) {
+            bySkillId.set(head.skillId, head);
+        }
+    }
+    const heads = [...bySkillId.values()].slice(0, skillModule.indexPolicy.maxHeads);
+    return heads.length === 0 ? [] : [renderSkillIndexMaterial(heads)];
+}
 function providerToolMappings(manifest) {
     return createProviderToolMappings(manifest.harness.tools);
 }
@@ -2764,6 +2790,7 @@ async function buildPromptPackAndLower(input) {
             sessionSummary: input.sessionSummary,
             conversationWindow: input.conversationWindow,
             toolDeclarationPreludeMaterials: input.toolDeclarationPreludeMaterials,
+            skillIndexMaterials: input.skillIndexMaterials,
             projectContextGovernanceMaterials: input.projectContextGovernanceMaterials?.map((material) => ({
                 id: material.id,
                 kind: "runtime",
@@ -4134,6 +4161,11 @@ export class PraxisRuntimeKernel {
             const maxToolCalls = manifest.harness.loop.maxToolCalls ?? 4;
             let toolMappings = [];
             let toolDeclarationPreludeMaterials = [];
+            const skillIndexMaterials = await discoverRuntimeSkillIndexMaterials({
+                manifest,
+                workspaceRoot: toolWorkspaceRoot,
+                store: options.skillPlane?.store ?? createFileSkillPlaneStore(path.join(toolWorkspaceRoot, ".rax_workspace", "skills")),
+            });
             async function refreshRuntimeMcpTools(reason) {
                 const dynamicSurface = await discoverRuntimeMcpDynamicSurface(runtimeMcpBaseManifest, executor, mcpPlusRuntime);
                 manifest = withRuntimeHarnessToolLayer(runtimeMcpBaseManifest, dynamicSurface.tools, reason);
@@ -4217,6 +4249,7 @@ export class PraxisRuntimeKernel {
                         sessionSummary: compactSessionSummary,
                         conversationWindow: compactConversationWindow,
                         toolDeclarationPreludeMaterials,
+                        skillIndexMaterials,
                         projectContextGovernanceMaterials: preCompactGovernanceProjectContextMaterials,
                         toolContextSelection,
                         toolContextUsage: toolContextHeatState.usage,
@@ -4462,6 +4495,7 @@ export class PraxisRuntimeKernel {
                                     sessionSummary: compactSessionSummary,
                                     conversationWindow: compactConversationWindow,
                                     toolDeclarationPreludeMaterials,
+                                    skillIndexMaterials,
                                     projectContextGovernanceMaterials: preCompactGovernanceProjectContextMaterials,
                                     toolContextSelection,
                                     toolContextUsage: toolContextHeatState.usage,

package/dist/runtimeImplementation/runtime.execEngine/promptContextAssembly.d.ts

@@ -37,6 +37,7 @@ export type PromptContextAssemblyRequest = {
     conversationWindow?: readonly PromptContextConversationMessage[];
     projectContextGovernanceMaterials?: readonly PromptPackMaterialDraft[];
     toolDeclarationPreludeMaterials?: readonly PromptPackMaterialDraft[];
+    skillIndexMaterials?: readonly PromptPackMaterialDraft[];
     budget?: PromptContextAssemblyBudget;
     toolContextSelection?: BaseToolContextSelection;
     toolContextUsage?: readonly BaseToolContextUsageRecord[];

package/dist/runtimeImplementation/runtime.execEngine/promptContextAssembly.js

@@ -434,6 +434,21 @@ export function assemblePromptContextMaterials(input) {
             toolMaterialType: "policy",
         },
     }));
+    const skillIndexMaterials = (input.skillIndexMaterials ?? []).map((material, index) => ({
+        ...material,
+        id: material.id ?? `runtime:skill-index:${index + 1}`,
+        kind: material.kind,
+        source: material.source ?? "runtime.skillPlane.index",
+        sourceCategory: material.sourceCategory ?? "declared-built-in",
+        priority: material.priority ?? 94 - index,
+        trusted: material.trusted ?? true,
+        scope: material.scope ?? "runtime.skillPlane.index",
+        promptSegmentKind: "skillIndex",
+        metadata: {
+            ...(material.metadata ?? {}),
+            promptSegmentKind: "skillIndex",
+        },
+    }));
     const sessionSummaryMaterial = input.sessionSummary === undefined
         ? []
         : [{
@@ -462,6 +477,7 @@ export function assemblePromptContextMaterials(input) {
         ...sessionSummaryMaterial,
         ...memoryContextMaterials,
         ...toolDeclarationPreludeMaterials,
+        ...skillIndexMaterials,
         {
             id: `task:${input.turnIndex}`,
             kind: "user",
@@ -544,6 +560,7 @@ export function assemblePromptContextMaterials(input) {
             declaredRuntimeContextMaterial,
             toolDeclarationsMaterial,
             ...toolDeclarationPreludeMaterials,
+            ...skillIndexMaterials,
             ...projectContextGovernanceMaterials,
             ...sessionSummaryMaterial,
             ...memoryContextMaterials,

package/dist/runtimeImplementation/runtime.skillPlane/index.d.ts

@@ -0,0 +1,119 @@
+import type { PromptPackMaterialDraft } from "../../executionEngine/promptPack/promptDefiner.js";
+export type SkillPlaneScope = "agent" | "project" | "workspace" | "user" | "session";
+export type SkillPlanePromotionState = "experience" | "skill" | "candidate-mcp-plus" | "mcp-plus" | "tool";
+export type SkillHead = {
+    skillId: string;
+    title: string;
+    summary: string;
+    scope?: SkillPlaneScope;
+    whenToUse?: string;
+    why?: string;
+    keywords?: readonly string[];
+    pitfallsPreview?: readonly string[];
+    bodyRef?: string;
+    promotedFrom?: readonly string[];
+    promotionState?: SkillPlanePromotionState;
+};
+export type SkillBody = SkillHead & {
+    prerequisites?: readonly string[];
+    do?: readonly string[];
+    avoid?: readonly string[];
+    pitfalls?: readonly string[];
+    verification?: readonly string[];
+    examples?: readonly string[];
+    promotionSignals?: readonly string[];
+    updatedAt: string;
+};
+export type SkillSourceSpec = {
+    kind: "directory";
+    path: string;
+    scope?: SkillPlaneScope;
+} | {
+    kind: "package";
+    packageName: string;
+    scope?: SkillPlaneScope;
+} | {
+    kind: "inline";
+    heads: readonly SkillHead[];
+};
+export type SkillPlaneIndexPolicy = {
+    maxHeads: number;
+    includeScopes: readonly SkillPlaneScope[];
+};
+export type SkillPlaneBodyLoadPolicy = {
+    mode: "on-demand" | "eager" | "disabled";
+    maxBodiesPerTurn: number;
+};
+export type SkillPlaneLifecyclePolicy = {
+    allowWrite: boolean;
+    checkpointWrites: boolean;
+    promotion: "off" | "suggest" | "auto";
+};
+export type SkillPlaneModuleSpec = {
+    kind: "praxis.skill.module";
+    version: "praxis.skill.v1";
+    sources: readonly SkillSourceSpec[];
+    indexPolicy: SkillPlaneIndexPolicy;
+    bodyLoadPolicy: SkillPlaneBodyLoadPolicy;
+    lifecycle: SkillPlaneLifecyclePolicy;
+    metadata?: Readonly<Record<string, unknown>>;
+};
+export type SkillPlaneListHeadsQuery = {
+    scopes?: readonly SkillPlaneScope[];
+};
+export type SkillPlaneStore = {
+    listHeads(query?: SkillPlaneListHeadsQuery): Promise<readonly SkillHead[]>;
+    readBody(skillId: string): Promise<SkillBody | undefined>;
+    write(body: SkillBody): Promise<SkillBody>;
+};
+export type SkillPlaneSourceResolutionInput = {
+    workspaceRoot?: string;
+};
+export type SkillWriteProposal = {
+    kind: "praxis.skill.writeProposal";
+    body: SkillBody;
+    reason?: string;
+    safeForRuntimeInspection: true;
+};
+export type SkillPromotionAdvice = {
+    kind: "praxis.skill.promotionAdvice";
+    skillId: string;
+    from?: SkillPlanePromotionState;
+    target: "candidate-mcp-plus";
+    autoGenerateTool: false;
+    reason?: string;
+    signals?: readonly string[];
+};
+export declare const skill: {
+    readonly directory: (directoryPath: string, input?: {
+        scope?: SkillPlaneScope;
+    }) => SkillSourceSpec;
+    readonly package: (packageName: string, input?: {
+        scope?: SkillPlaneScope;
+    }) => SkillSourceSpec;
+    readonly inline: (heads: readonly SkillHead[]) => SkillSourceSpec;
+    readonly module: (input?: {
+        sources?: readonly SkillSourceSpec[];
+        indexPolicy?: Partial<SkillPlaneIndexPolicy>;
+        bodyLoadPolicy?: Partial<SkillPlaneBodyLoadPolicy>;
+        lifecycle?: Partial<SkillPlaneLifecyclePolicy>;
+        metadata?: Readonly<Record<string, unknown>>;
+    }) => SkillPlaneModuleSpec;
+};
+export declare function isSkillPlaneModuleSpec(value: unknown): value is SkillPlaneModuleSpec;
+export declare function skillPlaneModuleFrom(input: {
+    modules?: Readonly<Record<string, unknown>>;
+}): SkillPlaneModuleSpec | undefined;
+export declare function runtimeRequirementsForSkillModule(module: SkillPlaneModuleSpec | undefined): readonly string[];
+export declare function loadSkillHeadsFromSource(source: SkillSourceSpec, input?: SkillPlaneSourceResolutionInput): Promise<readonly SkillHead[]>;
+export declare function loadSkillHeadsFromSources(sources: readonly SkillSourceSpec[], input?: SkillPlaneSourceResolutionInput): Promise<readonly SkillHead[]>;
+export declare function createInMemorySkillPlaneStore(initialBodies?: readonly SkillBody[]): SkillPlaneStore;
+export declare function createFileSkillPlaneStore(rootDir: string): SkillPlaneStore;
+export declare function renderSkillIndexMaterial(heads: readonly SkillHead[]): PromptPackMaterialDraft;
+export declare function createSkillWriteProposal(body: SkillBody, input?: {
+    reason?: string;
+}): SkillWriteProposal;
+export declare function adviseSkillPromotion(skillHead: SkillHead, input?: {
+    reason?: string;
+    signals?: readonly string[];
+}): SkillPromotionAdvice;

package/dist/runtimeImplementation/runtime.skillPlane/index.js

@@ -0,0 +1,274 @@
+/*
+ * 文件定位：Runtime Skill Plane / 技能索引与按需正文加载合约。
+ * 核心目的：让 Praxis runtime 能声明、索引、读取和写入可复用技能经验，
+ * 但不把技能直接降级成工具声明或外部服务配置。
+ */
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
+const DEFAULT_INDEX_POLICY = {
+    maxHeads: 40,
+    includeScopes: ["agent", "project", "workspace"],
+};
+const DEFAULT_BODY_LOAD_POLICY = {
+    mode: "on-demand",
+    maxBodiesPerTurn: 3,
+};
+const DEFAULT_LIFECYCLE_POLICY = {
+    allowWrite: true,
+    checkpointWrites: true,
+    promotion: "suggest",
+};
+export const skill = {
+    directory(directoryPath, input) {
+        return input === undefined
+            ? { kind: "directory", path: directoryPath }
+            : { kind: "directory", path: directoryPath, scope: input.scope };
+    },
+    package(packageName, input) {
+        return input === undefined
+            ? { kind: "package", packageName }
+            : { kind: "package", packageName, scope: input.scope };
+    },
+    inline(heads) {
+        return { kind: "inline", heads };
+    },
+    module(input = {}) {
+        return {
+            kind: "praxis.skill.module",
+            version: "praxis.skill.v1",
+            sources: input.sources ?? [],
+            indexPolicy: {
+                ...DEFAULT_INDEX_POLICY,
+                ...input.indexPolicy,
+            },
+            bodyLoadPolicy: {
+                ...DEFAULT_BODY_LOAD_POLICY,
+                ...input.bodyLoadPolicy,
+            },
+            lifecycle: {
+                ...DEFAULT_LIFECYCLE_POLICY,
+                ...input.lifecycle,
+            },
+            metadata: input.metadata,
+        };
+    },
+};
+export function isSkillPlaneModuleSpec(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return record.kind === "praxis.skill.module" && Array.isArray(record.sources);
+}
+export function skillPlaneModuleFrom(input) {
+    const candidate = input.modules?.skill;
+    return isSkillPlaneModuleSpec(candidate) ? candidate : undefined;
+}
+export function runtimeRequirementsForSkillModule(module) {
+    return module === undefined ? [] : ["runtime.skill"];
+}
+function isSkillHeadLike(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return typeof record.skillId === "string" && typeof record.title === "string" && typeof record.summary === "string";
+}
+function headsFromUnknown(value) {
+    if (Array.isArray(value))
+        return value.filter(isSkillHeadLike);
+    if (typeof value !== "object" || value === null)
+        return [];
+    const record = value;
+    if (Array.isArray(record.skillHeads))
+        return record.skillHeads.filter(isSkillHeadLike);
+    if (Array.isArray(record.heads))
+        return record.heads.filter(isSkillHeadLike);
+    if (Array.isArray(record.skills))
+        return record.skills.filter(isSkillHeadLike);
+    return isSkillHeadLike(value) ? [value] : [];
+}
+function withSourceScope(heads, scope) {
+    if (scope === undefined)
+        return heads;
+    return heads.map((head) => ({
+        ...head,
+        scope: head.scope ?? scope,
+    }));
+}
+export async function loadSkillHeadsFromSource(source, input = {}) {
+    if (source.kind === "inline")
+        return source.heads;
+    if (source.kind === "package") {
+        const module = await import(source.packageName);
+        return withSourceScope([
+            ...headsFromUnknown(module.skillHeads),
+            ...headsFromUnknown(module.heads),
+            ...headsFromUnknown(module.skills),
+            ...headsFromUnknown(module.default),
+        ], source.scope);
+    }
+    const rootDir = path.isAbsolute(source.path)
+        ? source.path
+        : path.resolve(input.workspaceRoot ?? process.cwd(), source.path);
+    let entries;
+    try {
+        entries = await readdir(rootDir);
+    }
+    catch {
+        return [];
+    }
+    const heads = await Promise.all(entries
+        .filter((entry) => entry.endsWith(".json"))
+        .map((entry) => readJsonFile(path.join(rootDir, entry), undefined).then(headsFromUnknown)));
+    return withSourceScope(heads.flat(), source.scope);
+}
+export async function loadSkillHeadsFromSources(sources, input = {}) {
+    const heads = await Promise.all(sources.map((source) => loadSkillHeadsFromSource(source, input)));
+    return heads.flat();
+}
+function headFromBody(body) {
+    return {
+        skillId: body.skillId,
+        title: body.title,
+        summary: body.summary,
+        scope: body.scope,
+        whenToUse: body.whenToUse,
+        why: body.why,
+        keywords: body.keywords,
+        pitfallsPreview: body.pitfallsPreview,
+        bodyRef: body.bodyRef,
+        promotedFrom: body.promotedFrom,
+        promotionState: body.promotionState,
+    };
+}
+function scopeMatches(head, scopes) {
+    if (scopes === undefined || scopes.length === 0)
+        return true;
+    return head.scope !== undefined && scopes.includes(head.scope);
+}
+function sortHeads(heads) {
+    return [...heads].sort((left, right) => left.skillId.localeCompare(right.skillId));
+}
+export function createInMemorySkillPlaneStore(initialBodies = []) {
+    const bodies = new Map(initialBodies.map((body) => [body.skillId, body]));
+    return {
+        async listHeads(query) {
+            return sortHeads([...bodies.values()].map(headFromBody).filter((head) => scopeMatches(head, query?.scopes)));
+        },
+        async readBody(skillId) {
+            return bodies.get(skillId);
+        },
+        async write(body) {
+            bodies.set(body.skillId, body);
+            return body;
+        },
+    };
+}
+async function readJsonFile(filePath, fallback) {
+    try {
+        return JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch {
+        return fallback;
+    }
+}
+async function writeJsonFile(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+}
+function skillFilePart(skillId) {
+    const sanitized = skillId
+        .trim()
+        .replace(/[^a-zA-Z0-9._-]+/gu, "-")
+        .replace(/^[._-]+|[._-]+$/gu, "")
+        .slice(0, 64)
+        .toLowerCase() || "skill";
+    const stableSuffix = createHash("sha256").update(skillId).digest("hex").slice(0, 16);
+    return `${sanitized}-${stableSuffix}.json`;
+}
+export function createFileSkillPlaneStore(rootDir) {
+    function bodyPath(skillId) {
+        return path.join(rootDir, skillFilePart(skillId));
+    }
+    async function listBodies() {
+        let entries;
+        try {
+            entries = await readdir(rootDir);
+        }
+        catch {
+            return [];
+        }
+        const bodies = await Promise.all(entries
+            .filter((entry) => entry.endsWith(".json"))
+            .map((entry) => readJsonFile(path.join(rootDir, entry), undefined)));
+        return bodies.filter((body) => body !== undefined && typeof body.skillId === "string");
+    }
+    return {
+        async listHeads(query) {
+            return sortHeads((await listBodies()).map(headFromBody).filter((head) => scopeMatches(head, query?.scopes)));
+        },
+        async readBody(skillId) {
+            return await readJsonFile(bodyPath(skillId), undefined);
+        },
+        async write(body) {
+            await writeJsonFile(bodyPath(body.skillId), body);
+            return body;
+        },
+    };
+}
+function compactLine(label, value) {
+    if (value === undefined)
+        return undefined;
+    const rendered = typeof value === "string"
+        ? value.trim()
+        : value.map((item) => item.trim()).filter(Boolean).join(", ");
+    return rendered.length === 0 ? undefined : `${label}: ${rendered}`;
+}
+export function renderSkillIndexMaterial(heads) {
+    const lines = ["# Skill Plane Index"];
+    for (const head of sortHeads(heads)) {
+        lines.push(`- ${head.skillId}: ${head.title}. ${head.summary}`);
+        const detailLines = [
+            compactLine("  scope", head.scope),
+            compactLine("  when", head.whenToUse),
+            compactLine("  why", head.why),
+            compactLine("  keywords", head.keywords),
+            compactLine("  pitfalls preview", head.pitfallsPreview),
+            compactLine("  body ref", head.bodyRef),
+            compactLine("  promotion", head.promotionState),
+        ].filter((line) => line !== undefined);
+        lines.push(...detailLines);
+    }
+    return {
+        id: "runtime:skill-plane:index",
+        kind: "runtime",
+        source: "runtime.skillPlane.index",
+        sourceCategory: "declared-built-in",
+        trusted: true,
+        promptSegmentKind: "skillIndex",
+        metadata: {
+            promptSegmentKind: "skillIndex",
+            generatedBy: "runtime.skillPlane",
+        },
+        text: lines.join("\n"),
+    };
+}
+export function createSkillWriteProposal(body, input = {}) {
+    return {
+        kind: "praxis.skill.writeProposal",
+        body,
+        reason: input.reason,
+        safeForRuntimeInspection: true,
+    };
+}
+export function adviseSkillPromotion(skillHead, input = {}) {
+    return {
+        kind: "praxis.skill.promotionAdvice",
+        skillId: skillHead.skillId,
+        from: skillHead.promotionState,
+        target: "candidate-mcp-plus",
+        autoGenerateTool: false,
+        reason: input.reason,
+        signals: input.signals,
+    };
+}

package/dist/runtimeImplementation/runtimeAgentManifest.js

@@ -12,6 +12,7 @@ import { createBaseToolSupportCatalog } from "./runtime.execEngine/baseToolSuppo
 import { canonicalDependencyId, dependencyKindFromId, } from "./runtime.dependencyPlane/index.js";
 import { capability as capabilityAuthoring, } from "./runtime.provisionPlane/index.js";
 import { mcpHarnessModuleFrom, runtimeRequirementsForMcpModule, } from "./runtime.mcpPlane/index.js";
+import { runtimeRequirementsForSkillModule, skillPlaneModuleFrom, } from "./runtime.skillPlane/index.js";
 export class PromptPack {
     promptPackId;
     base;
@@ -1272,6 +1273,7 @@ function normalizeHarness(input, authoring, normalizedTools) {
         runtimeRequirements: cleanList([
             ...(input.runtimeRequirements ?? []),
             ...runtimeRequirementsForMcpModule(mcpHarnessModuleFrom({ modules: input.modules })),
+            ...runtimeRequirementsForSkillModule(skillPlaneModuleFrom({ modules: input.modules })),
         ]),
         capabilities: authoring.capabilities,
         dependencies: authoring.dependencies,

package/examples/fullstack/agents/repoInspector/harness/repoInspectorHarness.ts

@@ -4,6 +4,26 @@ import type { HarnessSpec } from "@praxis-ai/praxis";
 import type { NormalizedRepoInspectorOptions } from "../config/repoInspectorOptions.js";
 import { createRepoInspectorToolSet } from "../tools/toolSet.js";
 
+const repoInspectorSkillModule = praxis.skill.module({
+  sources: [
+    praxis.skill.inline([{
+      skillId: "repo-review.findings-first",
+      title: "Findings First Review",
+      summary: "Lead with actionable findings and put summaries after risks.",
+      scope: "project",
+      whenToUse: "Code review and regression-risk tasks",
+      pitfallsPreview: ["Do not bury test gaps in a summary."],
+    }, {
+      skillId: "repo-inspection.anchor-current-target",
+      title: "Anchor Current Target",
+      summary: "Restate the current repository/path/task before inspecting or editing.",
+      scope: "project",
+      whenToUse: "Long context or task-switching sessions",
+      pitfallsPreview: ["Do not continue a previous repository by inertia."],
+    }]),
+  ],
+});
+
 export function createRepoInspectorHarness(options: NormalizedRepoInspectorOptions): HarnessSpec {
   return praxis.harness({
     modelRef: `model.repoInspector.${options.mode}`,
@@ -30,6 +50,9 @@ export function createRepoInspectorHarness(options: NormalizedRepoInspectorOptio
     memoryRefs: [
       "memory.example.fullstack.mpBridge.contract",
     ],
+    modules: {
+      skill: repoInspectorSkillModule,
+    },
     tools: praxis.tools(createRepoInspectorToolSet(options)),
     policy: praxis.policy({
       allowProviderCall: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxis-ai/praxis",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "private": false,
   "type": "module",
   "description": "Praxis agentCore architecture scaffold, tests, and engineering contracts.",