@aicf/agent-skills 1.0.0-rc.4

package/skills/aicf-migration/references/conversion-playbook.md

@@ -0,0 +1,9 @@
+# Conversion Playbook
+
+1. Split broad tools into narrow capabilities.
+2. Add entity manifests where domain objects are shared.
+3. Define strict input and output schemas.
+4. Add policy, risk, lifecycle, approval, audit, and idempotency metadata.
+5. Route only selected read/prepare slices to models.
+6. Wire handlers to existing app services.
+7. Add deterministic evals and red-team tests.

package/skills/aicf-migration/references/legacy-tool-riskmap.md

@@ -0,0 +1,14 @@
+# Legacy Tool Risk Map
+
+Classify legacy tools by:
+
+- data sensitivity.
+- side effects.
+- tenant/account scope.
+- external communication.
+- money movement.
+- permissions.
+- workflow impact.
+- existing validation and policy gaps.
+
+Use the highest applicable risk tier until controls prove otherwise.

package/skills/aicf-migration/references/migration-inventory.md

@@ -0,0 +1,12 @@
+# Migration Inventory
+
+Capture:
+
+- model providers and caller code.
+- tool/function definitions.
+- prompt templates and context sources.
+- data access and side effects.
+- auth, tenant, account, and permission sources.
+- evals, traces, error handling, and current rollout controls.
+
+Keep inventory public-safe when stored in this package.

package/skills/aicf-migration/references/rollout-plan.md

@@ -0,0 +1,12 @@
+# Rollout Plan
+
+Recommended stages:
+
+- inventory and design.
+- shadow mode.
+- read-only mode.
+- limited canary.
+- production gate.
+- rollback or disable path.
+
+Each stage should have success criteria, monitoring, and rollback instructions.

package/skills/aicf-observability-replay/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: aicf-observability-replay
+description:
+  Add AICF tracing, OpenTelemetry-style events, Langfuse/export adapters, replay
+  fixtures, simulation, and trace-to-golden workflows while keeping raw prompts and
+  provider payloads redacted by default.
+license: MIT
+compatibility:
+  Codex and Agent Skills-compatible coding agents. Works in repositories using AICF or
+  migrating to AICF.
+metadata:
+  aicf.skill.version: "1.0.0-rc.4"
+  aicf.skill.package: "@aicf/agent-skills"
+  aicf.skill.category: "observability-replay"
+  aicf.skill.scope: "builder"
+  aicf.skill.strictness: "fail-closed-runtime"
+---
+
+# AICF Observability Replay
+
+## Purpose
+
+Guide traceability, replay, simulation, and trace-to-golden work while keeping sensitive
+content out of default telemetry and eval artifacts.
+
+## Use this skill when
+
+- Adding AICF trace events, span metadata, optional observability adapters, replay
+  fixtures, or trace-to-golden workflows.
+- Testing redaction, provider attribution, replay determinism, or eval score capture.
+- Turning sanitized runtime behavior into regression fixtures.
+
+## Do not use this skill when
+
+- Building an observability platform or requiring external SDKs at root import time.
+- Capturing raw sensitive model input or provider transport bodies by default.
+- Running live providers in normal tests.
+
+## Inputs to inspect first
+
+- Observability modules, runtime trace events, provider loops, eval runner, replay
+  fixtures, redaction helpers, and package tests.
+- References: [trace span map](references/trace-span-map.md),
+  [replay simulation](references/replay-simulation.md),
+  [trace-to-golden](references/trace-to-golden.md), and
+  [redacted telemetry](references/redacted-telemetry.md).
+
+## Workflow
+
+1. Add trace events for context build, routing, model call, tool call, policy decision,
+   prepare, approval, commit, final response, and eval score.
+2. Include run ID, provider, model, capability IDs, schema version, selected slice,
+   redacted args hash, decision reasons, latency, cost/tokens where available, and
+   outcome.
+3. Redact sensitive content before sinks, exports, and replay fixtures.
+4. Add replay fixture generation for deterministic mock, policy-only, router-only, and
+   validation-only paths.
+5. Add trace-to-golden drafts with review required by default.
+6. Keep OpenTelemetry and Langfuse integration optional and adapter-isolated.
+7. Add tests for redaction, provider attribution, sink failure isolation, and replay
+   determinism.
+
+Use [replay fixture](assets/replay-fixture.json) and
+[trace-to-golden template](assets/trace-to-golden-template.yaml) as examples.
+
+## Required outputs
+
+- Trace/replay implementation or audit notes.
+- Sanitized replay or eval draft fixtures where requested.
+- Tests proving redaction and deterministic replay behavior.
+
+## Validation
+
+- Run observability, replay, eval, or provider mock tests relevant to the change.
+- Confirm trace events contain provider attribution only when metadata supplies it.
+- Confirm trace-to-golden output requires human review.
+
+## Hard rules
+
+- Do not capture private model input or provider transport bodies by default.
+- Do not let sink failures fail runtime execution.
+- Do not make optional observability SDKs required by root/runtime imports.
+- Do not commit generated traces or archives.
+
+## Handoff format
+
+Report events added, replay modes covered, redaction behavior, optional adapters
+touched, tests run, and remaining review gaps.

package/skills/aicf-observability-replay/assets/replay-fixture.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": "1.0",
+  "traceId": "trace_example_001",
+  "mode": "deterministic_mock",
+  "selectedCapabilities": ["support.ticket.get"],
+  "toolCalls": [
+    {
+      "callId": "call_example_001",
+      "capabilityId": "support.ticket.get",
+      "argsHash": "hash_example_args"
+    }
+  ],
+  "toolResults": [
+    {
+      "callId": "call_example_001",
+      "status": "ok",
+      "resultHash": "hash_example_result"
+    }
+  ],
+  "redactionSummary": {
+    "rawContentIncluded": false
+  }
+}

package/skills/aicf-observability-replay/assets/trace-to-golden-template.yaml

@@ -0,0 +1,14 @@
+schemaVersion: "1.0"
+suite: synthetic-support
+requireReview: true
+sourceTraceRef:
+  traceId: trace_example_001
+expected:
+  selectedCapabilities:
+    - support.ticket.get
+  forbiddenToolCalls: []
+  privateDetailsExcluded: true
+scorers:
+  - selected_capability_exact
+  - no_forbidden_tool_call
+  - private_detail_excluded

package/skills/aicf-observability-replay/references/redacted-telemetry.md

@@ -0,0 +1,7 @@
+# Redacted Telemetry
+
+Default telemetry should include IDs, hashes, counts, status, reasons, provider/model
+metadata, latency, token or cost summaries, and safe outcome summaries.
+
+Default telemetry should not include private prompts, provider transport bodies,
+secrets, stack traces, account IDs, tenant IDs, or sensitive tool output.

package/skills/aicf-observability-replay/references/replay-simulation.md

@@ -0,0 +1,10 @@
+# Replay Simulation
+
+Replay modes should avoid live calls by default:
+
+- deterministic mock compares recorded safe snapshots.
+- policy only reruns decisions.
+- router only reruns selected slices.
+- tool validation only reruns parsing and schema validation.
+
+Live replay must require explicit opt-in and caller-provided provider code.

package/skills/aicf-observability-replay/references/trace-span-map.md

@@ -0,0 +1,17 @@
+# Trace Span Map
+
+Recommended trace events:
+
+- runtime start and end.
+- context build.
+- capability route.
+- provider call.
+- tool call parse.
+- tool execution.
+- policy decision.
+- action prepare, approval, commit, verify.
+- eval scoring.
+- runtime error.
+
+Use stable AICF attributes and provider attributes only when the event supplies provider
+metadata.

package/skills/aicf-observability-replay/references/trace-to-golden.md

@@ -0,0 +1,12 @@
+# Trace To Golden
+
+Trace-to-golden drafts should include:
+
+- selected capability expectations.
+- tool input subsets.
+- policy decision and action state.
+- forbidden tool calls.
+- private-detail exclusion checks.
+- review metadata.
+
+Raw content is excluded unless an explicitly unsafe diagnostic mode is requested.

package/skills/aicf-policy-and-risk/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: aicf-policy-and-risk
+description:
+  Implement or audit AICF policy broker, risk tiers, semantic invariants, tenant
+  isolation, permissions, entitlements, approval requirements, and fail-closed runtime
+  decisions.
+license: MIT
+compatibility:
+  Codex and Agent Skills-compatible coding agents. Works in repositories using AICF or
+  migrating to AICF.
+metadata:
+  aicf.skill.version: "1.0.0-rc.4"
+  aicf.skill.package: "@aicf/agent-skills"
+  aicf.skill.category: "policy-risk"
+  aicf.skill.scope: "builder"
+  aicf.skill.strictness: "fail-closed-runtime"
+---
+
+# AICF Policy And Risk
+
+## Purpose
+
+Guide implementation or review of policy decisions so AICF capabilities fail closed,
+respect tenant/account/user context, and keep side effects under host authority.
+
+## Use this skill when
+
+- Adding or auditing a policy broker, decision request, or risk tier rule.
+- Checking tenant isolation, permissions, entitlements, autonomy, approvals, or
+  idempotency.
+- Investigating why a capability should be denied, allowed, or approval-required.
+- Adding tests for semantic invariants or runtime decision behavior.
+
+## Do not use this skill when
+
+- Creating provider adapters, model loops, long-running workflows, or storage systems.
+- Granting the model authority to override host policy.
+- Weakening validation to make a tool call pass.
+
+## Inputs to inspect first
+
+- Capability manifests, policy docs, runtime context builder, router, executor, and
+  lifecycle manager.
+- Existing tests for decisions, approvals, idempotency, and invalid args.
+- References for [policy broker contract](references/policy-broker-contract.md),
+  [risk tiers](references/risktier-rules.md),
+  [decision matrix](references/deny-approval-allow-matrix.md), and
+  [semantic invariants](references/semantic-invariants.md).
+
+## Workflow
+
+1. Identify the capability, operation, risk tier, side effects, lifecycle state, and
+   required context.
+2. Verify user, account, tenant, permission, autonomy, and entitlement inputs come from
+   host-controlled context.
+3. Apply semantic invariants before policy hooks.
+4. Let host hooks only make decisions stricter.
+5. Return structured deny, approval-required, or allow decisions with safe reason codes.
+6. Add tests for missing context, invalid args, risk ceilings, approval requirements,
+   and hook failures.
+7. Keep policy decision records public-safe.
+
+Use [policy broker template](assets/policy-broker.template.ts) and
+[decision fixture](assets/policy-decision-fixture.json) as safe starting points.
+
+## Required outputs
+
+- Policy or risk changes with reason codes and tests.
+- Updated docs or fixtures only when public contracts change.
+- A clear statement of denied, approval-required, and allowed paths.
+
+## Validation
+
+- Run targeted runtime/policy tests and the package check relevant to the repo.
+- Confirm errors are safe and stack traces or internal diagnostics are not model-facing.
+- Confirm policy failures do not call handlers or commit side effects.
+
+## Hard rules
+
+- Fail closed when context, args, policy state, or host hooks are missing or ambiguous.
+- Do not allow host hooks to turn a denial into allow.
+- Do not expose commit to model-originated tool execution.
+- Do not store raw identifiers in public evidence by default.
+
+## Handoff format
+
+List decisions changed, reason codes, tests added, commands run, and any remaining host
+integration obligations.

package/skills/aicf-policy-and-risk/assets/policy-broker.template.ts

@@ -0,0 +1,29 @@
+import type { JsonObject } from "ai-capability-framework";
+
+export type ExamplePolicyDecision = {
+  allowed: boolean;
+  approvalRequired: boolean;
+  reasons: string[];
+};
+
+export function decideExamplePolicy(input: {
+  capabilityId: string;
+  operation: string;
+  args?: JsonObject;
+  permissions: string[];
+  tenantPresent: boolean;
+}): ExamplePolicyDecision {
+  if (!input.tenantPresent) {
+    return {
+      allowed: false,
+      approvalRequired: false,
+      reasons: ["missing_tenant_context"]
+    };
+  }
+  if (
+    !input.permissions.includes(`capability:${input.capabilityId}:${input.operation}`)
+  ) {
+    return { allowed: false, approvalRequired: false, reasons: ["missing_permission"] };
+  }
+  return { allowed: true, approvalRequired: false, reasons: ["policy_allowed"] };
+}

package/skills/aicf-policy-and-risk/assets/policy-decision-fixture.json

@@ -0,0 +1,15 @@
+{
+  "capabilityId": "support.ticket.get",
+  "operation": "read",
+  "context": {
+    "subjectRef": "subject_hash_example",
+    "tenantRef": "tenant_hash_example",
+    "permissions": ["capability:support.ticket.get:read"],
+    "autonomyTier": "assistive"
+  },
+  "expected": {
+    "allowed": true,
+    "approvalRequired": false,
+    "reasons": ["policy_allowed"]
+  }
+}

package/skills/aicf-policy-and-risk/references/deny-approval-allow-matrix.md

@@ -0,0 +1,12 @@
+# Deny, Approval, Allow Matrix
+
+| Condition                                   | Decision                                   |
+| ------------------------------------------- | ------------------------------------------ |
+| Missing required subject/account/tenant     | deny                                       |
+| Invalid args                                | deny                                       |
+| Capability disabled or deprecated by policy | deny                                       |
+| Risk above autonomy ceiling                 | deny or approval required, based on policy |
+| Prepare needs human approval                | approval required                          |
+| Commit lacks stored prepared action         | deny                                       |
+| Host hook throws                            | deny                                       |
+| All required checks pass                    | allow                                      |

package/skills/aicf-policy-and-risk/references/policy-broker-contract.md

@@ -0,0 +1,13 @@
+# Policy Broker Contract
+
+The broker maps runtime context and a capability request to one of three outcomes:
+
+- deny
+- approval required
+- allow
+
+Inputs must include capability ID, operation, args when required, subject/account/tenant
+context, permissions, autonomy, and risk limits.
+
+Policy hooks may add denials or approval requirements. They must not override core
+safety denials.

package/skills/aicf-policy-and-risk/references/risktier-rules.md

@@ -0,0 +1,10 @@
+# Risk Tier Rules
+
+- Low: read-only, narrow, no sensitive data.
+- Medium: scoped data access, workflow preparation, or moderate operational impact.
+- High: money movement, personal data, external messages, destructive behavior, or
+  permission-sensitive work.
+- Critical: irreversible or broad high-impact action, privileged account changes, or
+  regulated data exposure.
+
+When in doubt, infer the higher risk and require explicit controls.

package/skills/aicf-policy-and-risk/references/semantic-invariants.md

@@ -0,0 +1,9 @@
+# Semantic Invariants
+
+- Commit cannot be model-executed.
+- Prepare and commit links must refer to the expected capability IDs.
+- Destructive and money-moving actions require audit and idempotency.
+- Tenant-scoped capabilities require tenant context.
+- Account-scoped capabilities require account context.
+- Output validation failures become safe runtime failures.
+- Terminal action states cannot return to approved or pending.

package/skills/aicf-provider-conformance/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: aicf-provider-conformance
+description:
+  "Validate AICF capabilities across provider and framework adapters: OpenAI, Anthropic
+  Claude, Google Gemini, Vercel AI SDK, MCP, LangChain/LangGraph, and Semantic
+  Kernel-compatible workflows."
+license: MIT
+compatibility:
+  Codex and Agent Skills-compatible coding agents. Works in repositories using AICF or
+  migrating to AICF.
+metadata:
+  aicf.skill.version: "1.0.0-rc.4"
+  aicf.skill.package: "@aicf/agent-skills"
+  aicf.skill.category: "provider-conformance"
+  aicf.skill.scope: "builder"
+  aicf.skill.strictness: "fail-closed-runtime"
+---
+
+# AICF Provider Conformance
+
+## Purpose
+
+Guide provider and framework conformance work so one routed AICF capability slice maps
+safely and reversibly across supported descriptor and runtime bridges.
+
+## Use this skill when
+
+- Validating OpenAI, Anthropic Claude, Google Gemini, Vercel AI SDK, MCP,
+  LangChain/LangGraph, or Semantic Kernel-compatible exports.
+- Checking schema normalization, tool-name mapping, reverse binding, tool-call parsing,
+  or model-safe tool results.
+- Running or updating a cross-provider conformance matrix.
+
+## Do not use this skill when
+
+- Adding a new provider runtime implementation.
+- Calling live models or provider APIs.
+- Weakening AICF schemas to satisfy a provider.
+- Building a model gateway.
+
+## Inputs to inspect first
+
+- Provider adapter code, shared provider helpers, conformance tests, fixtures, schemas,
+  docs, and public examples.
+- References: [provider matrix](references/provider-normalization-matrix.md),
+  [schema compatibility](references/schema-compatibility.md),
+  [tool-call mapping](references/tool-call-mapping.md), and
+  [runtime boundaries](references/provider-runtime-boundaries.md).
+
+## Workflow
+
+1. Identify the target provider or framework bridge.
+2. Export descriptors from the routed read/prepare slice.
+3. Validate provider-safe names, collision handling, and reverse binding.
+4. Validate schema normalization and deterministic diagnostics for unsupported schema
+   features.
+5. Validate tool-call parsing, arg validation, and unknown-tool handling.
+6. Validate model-safe result envelopes and approval-required behavior.
+7. Confirm commit capabilities are not exported or executable.
+8. Run or update the conformance matrix with structured pass/fail output.
+
+Use [conformance case](assets/provider-conformance-case.yaml) and
+[provider matrix](assets/provider-matrix.json) templates as starting points.
+
+## Required outputs
+
+- Provider conformance changes or a conformance report summary.
+- Diagnostics for unsupported schema features, collisions, invalid args, and unsafe
+  exports.
+- Tests or fixtures proving provider-safe behavior.
+
+## Validation
+
+- Run provider conformance tests and package checks relevant to the repo.
+- Confirm root/runtime imports remain free of optional provider SDK requirements.
+- Confirm provider outputs never include private diagnostics or raw transport bodies.
+
+## Hard rules
+
+- AICF validation remains canonical.
+- Reverse mapping must use generated bindings, not guessed provider names.
+- Commit capabilities must not be model-exposed.
+- Live provider calls must stay opt-in.
+
+## Handoff format
+
+Report providers checked, descriptors exported, failures or warnings, tests run, and
+remaining conformance gaps.

package/skills/aicf-provider-conformance/assets/provider-conformance-case.yaml

@@ -0,0 +1,18 @@
+id: support.ticket.get.provider_matrix
+providerTargets:
+  - openai
+  - anthropic
+  - gemini
+  - ai-sdk
+  - mcp
+capabilityId: support.ticket.get
+expected:
+  descriptorExported: true
+  commitExported: false
+  argsValidation: canonical_aicf
+  modelSafeEnvelope: true
+scorers:
+  - tool_name_valid
+  - binding_matches_capability
+  - no_commit_export
+  - safe_error_envelope

package/skills/aicf-provider-conformance/assets/provider-matrix.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": "1.0",
+  "providers": [
+    "openai",
+    "anthropic",
+    "gemini",
+    "ai-sdk",
+    "mcp",
+    "langchain",
+    "semantic-kernel-openapi"
+  ],
+  "dimensions": [
+    "descriptor_export",
+    "schema_normalization",
+    "tool_call_parsing",
+    "model_safe_envelope",
+    "commit_not_exported"
+  ]
+}

package/skills/aicf-provider-conformance/references/provider-normalization-matrix.md

@@ -0,0 +1,14 @@
+# Provider Normalization Matrix
+
+Track each provider target against:
+
+- descriptor export.
+- provider-safe name mapping.
+- schema normalization.
+- schema downgrade diagnostics.
+- tool-call parsing.
+- arg validation.
+- model-safe result envelope.
+- approval-required handling.
+- commit-not-exported behavior.
+- provider error normalization.

package/skills/aicf-provider-conformance/references/provider-runtime-boundaries.md

@@ -0,0 +1,10 @@
+# Provider Runtime Boundaries
+
+Provider runtimes and bridges must:
+
+- expose only routed read/prepare capabilities.
+- keep commit host-controlled.
+- keep SDK imports optional and subpath isolated.
+- avoid raw transport capture by default.
+- use mock clients in normal tests.
+- fail closed on provider, parse, budget, or loop errors.

package/skills/aicf-provider-conformance/references/schema-compatibility.md

@@ -0,0 +1,8 @@
+# Schema Compatibility
+
+Provider schema exports may use provider-compatible subsets, but AICF input schemas
+remain canonical for validation.
+
+Reject or diagnose non-object roots, unsupported composition, ambiguous nullable
+handling, and provider features that would weaken validation. Clone schemas before
+normalization.

package/skills/aicf-provider-conformance/references/tool-call-mapping.md

@@ -0,0 +1,8 @@
+# Tool Call Mapping
+
+- Generate provider-safe names deterministically.
+- Preserve provider call IDs when available.
+- Resolve provider tool names through the binding map.
+- Reject unknown names and calls outside the routed slice.
+- Validate args against the original AICF input schema.
+- Return model-safe envelopes for validation errors and denials.