Complete Skills v2 platform maturity

Author: Winlifes

docs/agent-architecture-improvement-plan.md

@@ -503,12 +503,36 @@ Turn the architecture review into an executable backlog for Funplay's local agen
 |---|---|---|---|---|
 | P65-1 | Add lazy supporting-file listing and reading for Skill packages. | Completed | Registered `list_agent_skill_files` and `read_agent_skill_file` as read-only Native tools. Supporting-file reads are scoped to the selected Skill package, reject path traversal and symlinks, skip `SKILL.md`, reject binary-like files, and cap file size/content. | `npm run agent:skills-v2-benchmark`; `npm run build`; `npm run test:runtime`; `npm run agent:roadmap-audit` |
 
+## Phase 66: Skills v2 Trust And Permission Boundaries
+
+| ID | Requirement | Status | Implementation Notes | Verification |
+|---|---|---|---|---|
+| P66-1 | Add Skill trust, source verification, permission policy, and script execution boundaries. | Completed | Filesystem Skills now expose trust level, verification status, content SHA-256, permission policy, script policy, and declared scripts. Approval-required or untrusted Skills are excluded from metadata auto-activation, and declared scripts are metadata only: execution must go through ordinary Agent tools and the existing permission broker. Native/Claude prompts and skill tools surface these boundaries. | `npm run agent:skills-v2-benchmark`; `npm run build`; `npm run agent:roadmap-audit` |
+
+## Phase 67: Claude SDK Skills Integration
+
+| ID | Requirement | Status | Implementation Notes | Verification |
+|---|---|---|---|---|
+| P67-1 | Integrate Claude SDK native Skills support where available. | Completed | Claude SDK options now apply Skills-aware `settings`: inactive Skills are hidden from model auto-selection, inactive user-invocable Skills remain slash-visible, and inline Skill shell execution is disabled. When a Claude SDK AgentDefinition is active, Funplay attaches active filesystem Skill names to that agent's `skills` allowlist. | `npm run agent:skills-v2-benchmark`; `npm run build`; `npm run agent:roadmap-audit` |
+
+## Phase 68: Skills v2 Observability
+
+| ID | Requirement | Status | Implementation Notes | Verification |
+|---|---|---|---|---|
+| P68-1 | Add Skill activation runtime events, replay export, and transcript visibility. | Completed | Active filesystem Skill selections now persist as `skill_activation` runtime events, appear in replay metrics and Agent Core debugger parts, and render in completed chat transcripts from structured Agent Core system parts. The Skills v2 benchmark includes these observability checks. | `npm run agent:skills-v2-benchmark`; `npm run build`; `npm run agent:roadmap-audit` |
+
 ## Phase 69: Skills v2 Benchmark Gate
 
 | ID | Requirement | Status | Implementation Notes | Verification |
 |---|---|---|---|---|
 | P69-1 | Add deterministic Skills v2 benchmark coverage. | Completed | Added `scripts/agent-skills-v2-benchmark.mjs` and `npm run agent:skills-v2-benchmark`, covering registry discovery, metadata context, explicit and automatic activation, supporting-file reads, and read-only tool-boundary checks. The main deterministic `agent:benchmark` now includes this Skills v2 slice. | `npm run agent:skills-v2-benchmark`; `npm run build`; `npm run test:runtime`; `npm run agent:benchmark`; `npm run agent:roadmap-audit` |
 
+## Phase 70: Skills v2 Settings UI
+
+| ID | Requirement | Status | Implementation Notes | Verification |
+|---|---|---|---|---|
+| P70-1 | Mature the Settings UI for source precedence, conflicts, updates, and project overrides. | Completed | Added a main-process filesystem Skill registry IPC endpoint and rendered it in Project Settings. The Skills page now shows source precedence, same-name override conflicts, trust/verification status, permission policy, script policy, and suggested tools alongside existing catalog sync/update and custom project Skill override controls. | `npm run agent:skills-v2-benchmark`; `npm run build`; `npm run agent:roadmap-audit` |
+
 ## Next Roadmap: Claude Code MCP Platform Parity
 
 This draft section is intentionally not encoded as audited implementation rows. Convert each item into a numbered phase row only when that item enters active implementation.

docs/skills-v2-roadmap.md

@@ -1,6 +1,6 @@
 # Skills v2 Platform Roadmap
 
-Last updated: 2026-05-15
+Last updated: 2026-05-16
 
 ## Maturity Target
 
@@ -25,11 +25,11 @@ Funplay Skills v2 should behave like a platform capability, not a large prompt f
 | SK63-1 | Replace eager prompt injection with automatic metadata-based activation. | Completed |
 | SK64-1 | Add explicit `/skill-name` invocation and session-visible activation state. | Completed |
 | SK65-1 | Add supporting-file lazy loading with size limits and provenance. | Completed |
-| SK66-1 | Add Skill trust, source verification, permission policy, and script execution boundaries. | Not started |
-| SK67-1 | Integrate Claude SDK native Skills support where available. | Not started |
-| SK68-1 | Add Skill activation/runtime events, replay export, and UI visibility. | Not started |
+| SK66-1 | Add Skill trust, source verification, permission policy, and script execution boundaries. | Completed |
+| SK67-1 | Integrate Claude SDK native Skills support where available. | Completed |
+| SK68-1 | Add Skill activation/runtime events, replay export, and UI visibility. | Completed |
 | SK69-1 | Add deterministic and live Skill benchmark gates. | Completed |
-| SK70-1 | Mature the Settings UI for source precedence, conflicts, updates, and project overrides. | Not started |
+| SK70-1 | Mature the Settings UI for source precedence, conflicts, updates, and project overrides. | Completed |
 
 ## Phase 61 Verification
 
@@ -65,8 +65,40 @@ Funplay Skills v2 should behave like a platform capability, not a large prompt f
 - Supporting file reads are scoped to the selected Skill directory, skip symlinks, reject path traversal and binary-like files, and cap file size/content.
 - Regression checks: `npm run agent:skills-v2-benchmark`, `npm run build`, `npm run test:runtime`
 
+## Phase 66 Verification
+
+- Filesystem Skills now carry trust level, source verification status, content SHA-256, permission policy, script policy, and declared script metadata.
+- Project/user/plugin Skills receive local provenance; user/plugin sources can be trusted, while catalog/custom sources default to unverified approval-required handling.
+- Skills marked approval-required or untrusted are not auto-activated by metadata matching; explicit invocation and read tools still surface the policy.
+- Declared scripts are metadata only and never execute through the Skill system directly; they must go through normal host tools and permission broker checks.
+- Native and Claude prompts, `list_agent_skills`, and `read_agent_skill` now show trust, verification, permission, and script boundaries.
+- Regression checks: `npm run agent:skills-v2-benchmark`, `npm run build`
+
+## Phase 67 Verification
+
+- Claude SDK sessions now receive Skills-aware settings when filesystem Skills exist.
+- Inactive Skills are hidden from model auto-selection with `skillOverrides`, while user-invocable inactive Skills remain slash-visible.
+- Skill inline shell execution is disabled through SDK settings.
+- When the caller uses a Claude SDK AgentDefinition, active Funplay Skills are attached to that agent's `skills` allowlist.
+- Regression checks: `npm run agent:skills-v2-benchmark`, `npm run build`
+
+## Phase 68 Verification
+
+- Active filesystem Skill selections now persist as first-class `skill_activation` runtime events.
+- Agent replay exports include Skill activation metrics and convert persisted activations into structured Agent Core system parts.
+- Completed chat transcript rendering now shows activated Skills from Agent Core parts without parsing assistant pseudo text.
+- The Skills v2 benchmark now includes activation-event, replay, and transcript visibility checks.
+- Regression checks: `npm run agent:skills-v2-benchmark`, `npm run build`
+
 ## Phase 69 Verification
 
 - Added `npm run agent:skills-v2-benchmark` with focused registry, activation, supporting-file, and read-only tool-boundary checks.
 - The deterministic `npm run agent:benchmark` suite now includes the Skills v2 platform slice.
 - Regression checks: `npm run agent:skills-v2-benchmark`, `npm run build`, `npm run test:runtime`, `npm run agent:roadmap-audit`, `npm run agent:benchmark`
+
+## Phase 70 Verification
+
+- Project Settings now loads the filesystem Skill registry through a main-process IPC path.
+- The Skills settings view shows source precedence, same-name override conflicts, trust/verification status, permission policy, script policy, and suggested tools.
+- Existing catalog sync/update and project custom Skill override controls remain available beside the Claude Code filesystem registry view.
+- Regression checks: `npm run agent:skills-v2-benchmark`, `npm run build`

electron/main/agent-platform/claude/prompt-builder.ts

@@ -119,6 +119,9 @@ export function formatUserSkills(params: GenericAgentRuntimeParams): string {
               `## ${skill.name}`,
               skill.description ? `Purpose: ${skill.description}` : '',
               `Source: ${skill.source}`,
+              `Trust: ${skill.trustLevel} · Verification: ${skill.verificationStatus}`,
+              `Permission policy: ${skill.permissionPolicy} (skill metadata does not grant tool permission)`,
+              `Script policy: ${skill.scriptPolicy}${skill.declaredScripts?.length ? ` · ${skill.declaredScripts.length} declared script(s), run only through normal host tool permission` : ''}`,
               skill.allowedTools?.length ? `Suggested tools: ${skill.allowedTools.join(', ')}` : '',
               'Instructions:',
               skill.instruction
@@ -136,6 +139,9 @@ export function formatUserSkills(params: GenericAgentRuntimeParams): string {
               skill.description ? `Purpose: ${skill.description}` : '',
               `Source: ${skill.source}`,
               `Invocable: user=${skill.userInvocable ? 'yes' : 'no'} model=${skill.modelInvocable ? 'yes' : 'no'}`,
+              `Trust: ${skill.trustLevel} · Verification: ${skill.verificationStatus}`,
+              `Permission policy: ${skill.permissionPolicy}`,
+              skill.declaredScripts?.length ? `Declared scripts: ${skill.declaredScripts.length} (execute only through normal host tool permission)` : '',
               skill.allowedTools?.length ? `Allowed tools: ${skill.allowedTools.join(', ')}` : ''
             ].filter(Boolean).join('\n')
           )

electron/main/agent-platform/claude/runtime.ts

@@ -739,6 +739,24 @@ export function createClaudeSdkPermissionHandler(params: GenericAgentRuntimePara
   };
 }
 
+function buildClaudeSdkSkillSettings(
+  params: GenericAgentRuntimeParams,
+  activeSkillNames: string[]
+): ClaudeAgentSdkOptions['settings'] | undefined {
+  const skillIndex = params.context.toolContext.skillIndex;
+  if (!skillIndex.length && !activeSkillNames.length) {
+    return undefined;
+  }
+  const active = new Set(activeSkillNames);
+  return {
+    disableSkillShellExecution: true,
+    skillOverrides: Object.fromEntries(skillIndex.map((skill) => [
+      skill.name,
+      active.has(skill.name) ? 'on' : skill.userInvocable ? 'user-invocable-only' : 'off'
+    ]))
+  };
+}
+
 export function createClaudeCodeSdkOptions(params: GenericAgentRuntimeParams, allowWriteTools: boolean, options: {
   cwd: string;
   abortController: AbortController;
@@ -753,6 +771,8 @@ export function createClaudeCodeSdkOptions(params: GenericAgentRuntimeParams, al
     allowWriteTools,
     supportsHostControlledWrites: true
   });
+  const activeSkillNames = params.context.toolContext.activeSkills.map((skill) => skill.name);
+  const skillSettings = buildClaudeSdkSkillSettings(params, activeSkillNames);
   const sdkOptions: ClaudeAgentSdkOptions = {
     cwd: options.cwd,
     abortController: options.abortController,
@@ -768,6 +788,7 @@ export function createClaudeCodeSdkOptions(params: GenericAgentRuntimeParams, al
     env: options.env ?? buildClaudeCodeSdkEnv(params.provider),
     settingSources: resolveClaudeSdkSettingSources(params.provider),
     mcpServers: buildFunplayMcpServers(params, options.cwd, profile),
+    settings: skillSettings,
     enableFileCheckpointing: Boolean(params.checkpointSnapshotId),
     canUseTool: options.canUseTool,
     stderr: options.stderr
@@ -817,6 +838,15 @@ export function createClaudeCodeSdkOptions(params: GenericAgentRuntimeParams, al
   }
   if (runtimeOverrides?.agent?.trim()) {
     sdkOptions.agent = runtimeOverrides.agent.trim();
+    if (activeSkillNames.length && sdkOptions.agents?.[sdkOptions.agent]) {
+      sdkOptions.agents = {
+        ...sdkOptions.agents,
+        [sdkOptions.agent]: {
+          ...sdkOptions.agents[sdkOptions.agent],
+          skills: activeSkillNames
+        }
+      };
+    }
   }
 
   if (model) {

electron/main/agent-platform/native/prompt.ts

@@ -137,6 +137,9 @@ export function createNativeRuntimeUserPrompt(
               `## ${skill.name}`,
               skill.description ? `用途：${skill.description}` : '',
               `来源：${skill.source}`,
+              `信任：${skill.trustLevel} · 验证：${skill.verificationStatus}`,
+              `权限策略：${skill.permissionPolicy}（只约束 Skill 工作流，不授予工具权限）`,
+              `脚本策略：${skill.scriptPolicy}${skill.declaredScripts?.length ? ` · 声明脚本 ${skill.declaredScripts.length} 个，必须通过普通工具权限流程执行` : ''}`,
               skill.allowedTools?.length ? `建议工具：${skill.allowedTools.join(', ')}` : '',
               '执行准则：',
               skill.instruction
@@ -155,6 +158,9 @@ export function createNativeRuntimeUserPrompt(
               skill.description ? `用途：${skill.description}` : '',
               `来源：${skill.source}`,
               `可调用：user=${skill.userInvocable ? 'yes' : 'no'} model=${skill.modelInvocable ? 'yes' : 'no'}`,
+              `信任：${skill.trustLevel} · 验证：${skill.verificationStatus}`,
+              `权限策略：${skill.permissionPolicy}`,
+              skill.declaredScripts?.length ? `声明脚本：${skill.declaredScripts.length} 个（不能直接执行，需普通工具权限）` : '',
               skill.allowedTools?.length ? `建议工具：${skill.allowedTools.join(', ')}` : ''
             ].filter(Boolean).join('\n')
           )

electron/main/agent-platform/replay-log.ts

@@ -35,6 +35,7 @@ export function buildAgentReplayMetrics(run: AgentRuntimeStatus): AgentReplayMet
   const events = run.events ?? [];
   const usageTotals = latestUsageTotals(run);
   const usageEventCount = events.filter((event) => event.type === 'usage').length;
+  const skillActivationCount = events.filter((event) => event.type === 'skill_activation' && event.skillActivation).length;
   const toolUseIds = new Set(events
     .filter((event) => event.type === 'tool_use' && event.toolUse?.toolUseId)
     .map((event) => event.toolUse?.toolUseId as string));
@@ -64,7 +65,8 @@ export function buildAgentReplayMetrics(run: AgentRuntimeStatus): AgentReplayMet
     toolRetryCount: countRepeatedToolResults(events),
     recoveryEventCount: recoveryEvents.length,
     apiRetryCount,
-    contextRetryCount
+    contextRetryCount,
+    skillActivationCount
   };
 }
 

electron/main/agent-platform/run-registry.ts

@@ -7,6 +7,7 @@ import type {
   AgentRuntimeStatus,
   AgentRuntimeTimelineEntry,
   AgentRuntimeToolBoundary,
+  AgentSkillActivation,
   AgentToolArtifact,
   AgentToolBrowserResult,
   AgentToolChangedFile,
@@ -319,6 +320,26 @@ export function recordActiveRunTodoUpdate(runId: string, input: NonNullable<Agen
   persistRuntimeRun(updated);
 }
 
+export function recordActiveRunSkillActivation(runId: string, input: AgentSkillActivation): void {
+  const run = activeRunsById.get(runId);
+  if (!run) {
+    return;
+  }
+
+  const updated: ActiveAgentRun = {
+    ...run,
+    updatedAt: nowIso()
+  };
+  updated.events = appendRuntimeEvent(updated, {
+    type: 'skill_activation',
+    status: updated.status,
+    statusMessage: `Skill activated: ${input.name}`,
+    skillActivation: input
+  });
+  activeRunsById.set(runId, updated);
+  persistRuntimeRun(updated);
+}
+
 export function findActiveRunBySession(sessionId: string): ActiveAgentRun | undefined {
   return [...activeRunsById.values()].find((run) => run.sessionId === sessionId);
 }