@aicf/agent-skills 1.0.0-rc.4

package/skills/aicf-action-lifecycle/references/approval-patterns.md

@@ -0,0 +1,9 @@
+# Approval Patterns
+
+- Store a prepared action before requesting approval.
+- Present only a safe summary to the approver.
+- Record requester, decider, reason, timestamp, and decision status as redacted refs or
+  summaries.
+- Deny commits when approval is missing, rejected, expired, mismatched, or unrelated to
+  the prepared action.
+- Approval UI and identity remain host responsibilities.

package/skills/aicf-action-lifecycle/references/idempotency-and-audit.md

@@ -0,0 +1,8 @@
+# Idempotency And Audit
+
+- Scope idempotency keys by tenant/account/action context.
+- Reserve before commit and complete with a safe result ref.
+- Return the previous safe result for duplicate keys in the same scope.
+- Write audit events for prepare, approval, commit started, commit succeeded, commit
+  failed, and denial.
+- Do not audit raw tool args when hashes or summaries are enough.

package/skills/aicf-action-lifecycle/references/verification-patterns.md

@@ -0,0 +1,7 @@
+# Verification Patterns
+
+Verification checks whether a prepared or committed action still matches expected host
+state.
+
+Use verification for review flows, reconciliation, and post-commit checks. Verification
+should return a safe envelope, never stack traces or private diagnostics.

package/skills/aicf-capability-authoring/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: aicf-capability-authoring
+description:
+  Author or modify AICF capability/entity manifests, schemas, model-facing slices, and
+  starter evals. Use when creating an AI tool, exposing app functionality to models, or
+  converting an operation into a governed AICF capability.
+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: "capability-authoring"
+  aicf.skill.scope: "builder"
+  aicf.skill.strictness: "fail-closed-runtime"
+---
+
+# AICF Capability Authoring
+
+## Purpose
+
+Guide creation or modification of AICF capability and entity manifests so
+model-accessible application operations are precise, governable, testable, and safe to
+route.
+
+## Use this skill when
+
+- Creating a new AICF capability manifest for read, prepare, commit, send, or workflow
+  operations.
+- Turning an application operation into a governed model-facing tool.
+- Adding entity manifests, input/output schemas, model-facing descriptions, or starter
+  evals.
+- Reviewing an existing manifest for safety, lifecycle, routing, and schema quality.
+
+## Do not use this skill when
+
+- Implementing runtime handlers, provider loops, storage adapters, approval UIs, or
+  model calls.
+- Writing general app APIs that are not being exposed through AICF.
+- Creating broad raw backend endpoints instead of capability-sized operations.
+
+## Inputs to inspect first
+
+- `AGENTS.md` and public repository rules.
+- Existing `schemas/`, `examples/`, `docs/start-here.md`, and nearby capability/entity
+  manifests.
+- A target application operation, intended user, lifecycle operation, side effects, and
+  risk tier.
+- Reference guides: [checklist](references/checklist.md),
+  [decision tree](references/manifest-decision-tree.md),
+  [field guide](references/field-guide.md), and [examples](references/examples.md).
+
+## Workflow
+
+1. Identify the smallest useful operation and reject broad generic APIs.
+2. Choose capability type, lifecycle operation, risk tier, side-effect metadata, and
+   required auth/account/tenant context.
+3. Draft or update the entity manifest when the capability acts on a domain entity.
+4. Write strict object input schemas and output schemas; prefer explicit required fields
+   and enums.
+5. Add model-facing descriptions that say what the capability does, when to use it, and
+   what it will not do.
+6. Add starter eval coverage for selection, valid input, invalid input, and forbidden
+   commit exposure.
+7. Validate the manifests and keep examples synthetic.
+
+Use [capability template](assets/capability.manifest.yaml),
+[entity template](assets/entity.manifest.yaml), and
+[eval template](assets/eval-case.yaml) as starting points.
+
+## Required outputs
+
+- Capability and, when needed, entity manifests with strict schemas and public-safe
+  descriptions.
+- A short explanation of lifecycle, risk, side effects, approval/idempotency/audit
+  needs, and routing expectations.
+- Starter eval cases or a concrete note explaining why no eval was added.
+
+## Validation
+
+- Run the repo manifest validation command.
+- Run generated-type checks if schemas changed.
+- Confirm the model-facing slice excludes commit capabilities unless a host-only path
+  intentionally handles them.
+- Confirm examples contain only synthetic identifiers and `example.com` URLs when URLs
+  are needed.
+
+## Hard rules
+
+- Do not expose a broad application API as one capability.
+- Do not weaken AICF validation to satisfy a provider schema.
+- Do not add runtime execution, storage, provider SDK calls, model calls, or approval
+  workflows from this skill.
+- Do not copy private notes into public manifests or docs.
+
+## Handoff format
+
+Report changed manifests, created evals, validation commands run, safety decisions, and
+any remaining gaps or follow-up work.

package/skills/aicf-capability-authoring/assets/capability.manifest.yaml

@@ -0,0 +1,31 @@
+id: example.entity.action
+version: "1.0.0"
+status: draft
+description: "Describe the narrow capability and when a model should select it."
+capability_type: read
+lifecycle:
+  operation: read
+risk:
+  tier: low
+input_schema:
+  type: object
+  additionalProperties: false
+  properties:
+    entity_id:
+      type: string
+  required:
+    - entity_id
+output_schema:
+  type: object
+  additionalProperties: false
+  properties:
+    entity_id:
+      type: string
+    summary:
+      type: string
+  required:
+    - entity_id
+    - summary
+policy:
+  requires_user: true
+  requires_tenant: true

package/skills/aicf-capability-authoring/assets/entity.manifest.yaml

@@ -0,0 +1,12 @@
+id: example.entity
+version: "1.0.0"
+description: "Synthetic entity used by an example capability."
+fields:
+  entity_id:
+    type: string
+    description: "Synthetic public-safe entity identifier."
+  summary:
+    type: string
+    description: "Short public-safe summary."
+allowed_actions:
+  - read

package/skills/aicf-capability-authoring/assets/eval-case.yaml

@@ -0,0 +1,12 @@
+id: example.entity.action.selects
+description: "Model should select the narrow example capability for a matching request."
+capability_under_test: example.entity.action
+input:
+  user_message: "Show the summary for example entity EX-100."
+expected:
+  selected_capabilities:
+    - example.entity.action
+  forbidden_tool_calls: []
+scorers:
+  - selected_capability_exact
+  - no_forbidden_tool_call

package/skills/aicf-capability-authoring/references/checklist.md

@@ -0,0 +1,13 @@
+# Capability Authoring Checklist
+
+- Operation is one narrow application action, not a generic API wrapper.
+- Capability ID is stable, domain-scoped, and readable.
+- Capability type and lifecycle operation match the host behavior.
+- Input schema is an object schema with clear required fields.
+- Output schema is explicit enough for evals and consumers.
+- Entity references point to public entity manifests where applicable.
+- Risk tier, side effects, auth, tenant/account requirements, audit, approval, and
+  idempotency are consistent.
+- Model-facing description says what the capability does and does not do.
+- Restricted or destructive behavior is not model-exposed as commit.
+- Starter evals cover selection, valid input, invalid input, and forbidden action paths.

package/skills/aicf-capability-authoring/references/examples.md

@@ -0,0 +1,12 @@
+# Public-Safe Examples
+
+Use synthetic names and simple domains:
+
+- `support.ticket.get`: read a support ticket by ID.
+- `support.refund.prepare_case`: prepare a refund request for host approval.
+- `support.refund.commit_case`: host-controlled commit for an approved prepared refund.
+- `scheduling.invite.prepare`: prepare an invite message.
+- `scheduling.invite.send`: host-controlled send path.
+
+Avoid customer-like identifiers, real endpoints, tenant names, transcripts, or provider
+transport details.

package/skills/aicf-capability-authoring/references/field-guide.md

@@ -0,0 +1,13 @@
+# Field Guide
+
+- `id`: stable capability identifier, usually `domain.entity.action`.
+- `description`: model-facing summary, written for safe selection.
+- `status`: current manifest availability, not governance lifecycle by itself.
+- `input_schema`: canonical AICF validation contract for tool arguments.
+- `output_schema`: expected handler result shape.
+- `risk`: declared risk; never declare lower than inferred side effects require.
+- `side_effects`: machine-readable summary of writes, sends, deletes, money movement, or
+  external effects.
+- `lifecycle`: read, prepare, commit, verify, or related lifecycle metadata.
+- `policy`: requirements the host policy broker must enforce.
+- `extensions`: public-safe metadata for governance, security packs, or provider hints.

package/skills/aicf-capability-authoring/references/manifest-decision-tree.md

@@ -0,0 +1,10 @@
+# Manifest Decision Tree
+
+1. If the operation only retrieves data, model it as read/select behavior.
+2. If the operation stages a future side effect, model it as prepare and link the
+   host-controlled commit path.
+3. If the operation performs a side effect, keep commit host-controlled and require
+   policy, audit, and idempotency.
+4. If the operation sends messages, moves money, changes permissions, deletes records,
+   or affects tenants, treat it as high scrutiny.
+5. If the operation cannot be described precisely, split it before writing a manifest.

package/skills/aicf-control-plane-ui/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: aicf-control-plane-ui
+description:
+  Build or audit the optional AICF governance control-plane UI/API for capability
+  catalogue, lifecycle, policy decisions, approvals, eval status, traces, controls, and
+  evidence export.
+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: "control-plane-ui"
+  aicf.skill.scope: "builder"
+  aicf.skill.strictness: "fail-closed-runtime"
+---
+
+# AICF Control Plane UI
+
+## Purpose
+
+Guide optional AICF governance control-plane UI/API work so capability, lifecycle,
+approval, eval, trace, control, and evidence views stay dense, safe, and operational.
+
+## Use this skill when
+
+- Building or auditing a docs-only mock, API, self-hosted UI, sample app, or production
+  integration for AICF governance.
+- Creating capability catalogue, lifecycle, policy decision, approval, eval, trace,
+  controls, or evidence export views.
+- Testing safe API response shapes and important UI states.
+
+## Do not use this skill when
+
+- Building a generic analytics dashboard.
+- Adding production auth, storage, workflow engines, or hosted SaaS behavior.
+- Returning private raw data through UI/API responses.
+
+## Inputs to inspect first
+
+- Control-plane contracts, existing example app, UI framework, design system, public
+  docs, API tests, and evidence export behavior.
+- References: [screens](references/control-plane-screens.md),
+  [approval console](references/approval-console.md),
+  [operational UX](references/operational-ux.md), and
+  [API contracts](references/api-contracts.md).
+
+## Workflow
+
+1. Identify target surface: docs mock, API, self-hosted UI, sample app, or production
+   integration.
+2. Build dense views for capability catalogue, lifecycle state, risk tier, policy
+   decisions, approvals, eval/security status, traces/replay, kill switches, and
+   evidence export.
+3. Use the project UI framework and design system.
+4. Return only safe summaries, hashes, redacted refs, statuses, counts, and reasons.
+5. Add loading, empty, error, denied, approval-required, and disabled states.
+6. Add accessibility labels and keyboard paths where practical.
+7. Add tests for API contracts and critical UI states.
+
+Use [wireframe](assets/control-plane-wireframe.md) and
+[UI checklist](assets/ui-acceptance-checklist.md) templates.
+
+## Required outputs
+
+- UI/API implementation or audit notes.
+- Tests for safe response shapes, approval paths, controls, evidence export, and UI
+  states.
+- Public-safety summary for data shown in the control plane.
+
+## Validation
+
+- Run API, UI, package, docs, and public-safety checks relevant to the change.
+- Use browser or screenshot verification for user-visible UI changes when practical.
+- Confirm private data is not rendered or returned.
+
+## Hard rules
+
+- Host apps own production auth, tenant enforcement, approval identity, storage, and
+  retention.
+- Do not expose private prompts, transcripts, provider transport bodies, secrets,
+  account IDs, tenant IDs, or stack traces.
+- Do not model-expose commit paths through the control plane.
+- Do not create a hosted product or workflow engine.
+
+## Handoff format
+
+Report surfaces changed, safe data model, tests run, UI verification, and remaining host
+deployment obligations.

package/skills/aicf-control-plane-ui/assets/control-plane-wireframe.md

@@ -0,0 +1,29 @@
+# Control Plane Wireframe
+
+## Header
+
+- project and environment
+- active controls summary
+
+## Navigation
+
+- capabilities
+- approvals
+- evals
+- traces
+- controls
+- evidence
+
+## Main panel
+
+- dense table or detail view
+- filters
+- status badges
+- safe action buttons
+
+## Detail panel
+
+- summary
+- reasons
+- linked evidence
+- safe metadata

package/skills/aicf-control-plane-ui/assets/ui-acceptance-checklist.md

@@ -0,0 +1,11 @@
+# UI Acceptance Checklist
+
+- Capability catalogue is scannable.
+- Detail view includes lifecycle, risk, policy, eval, conformance, and evidence
+  summaries.
+- Approval required state is clear.
+- Disabled and denied states are clear.
+- Safe errors omit stack traces.
+- Keyboard path reaches primary controls.
+- Mobile and desktop layouts do not overlap.
+- No private raw data is rendered.

package/skills/aicf-control-plane-ui/references/api-contracts.md

@@ -0,0 +1,14 @@
+# API Contracts
+
+Control-plane APIs should return JSON-serializable safe responses:
+
+- status.
+- IDs or redacted refs.
+- summaries.
+- counts.
+- reason codes.
+- coverage metadata.
+- safe errors.
+
+Do not return raw transcripts, provider transport details, stack traces, secrets, or
+unredacted tenant/account/user IDs.

package/skills/aicf-control-plane-ui/references/approval-console.md

@@ -0,0 +1,12 @@
+# Approval Console
+
+Approval views should show:
+
+- prepared action safe summary.
+- requester and account refs as redacted refs.
+- risk tier and approval reason.
+- approve and reject actions.
+- status history.
+- expiry state.
+
+Never show raw args or sensitive output by default.

package/skills/aicf-control-plane-ui/references/control-plane-screens.md

@@ -0,0 +1,14 @@
+# Control Plane Screens
+
+Useful screens:
+
+- capability catalogue.
+- capability detail.
+- lifecycle and risk status.
+- policy decision ledger.
+- approval queue.
+- eval and security-pack status.
+- conformance status.
+- trace and replay index.
+- controls and budgets.
+- evidence export.

package/skills/aicf-control-plane-ui/references/operational-ux.md

@@ -0,0 +1,7 @@
+# Operational UX
+
+Operational UIs should be dense, scannable, and predictable.
+
+Include clear states for loading, empty, error, denied, approval required, disabled,
+expired, and failed. Use tables and filters for repeated records. Keep decorative UI
+minimal.

package/skills/aicf-controls-and-budgets/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: aicf-controls-and-budgets
+description:
+  Implement or audit AICF capability-level kill switches, circuit breakers, budgets, max
+  loops, rate controls, and fail-safe read-only modes without replacing a model gateway.
+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: "controls-budgets"
+  aicf.skill.scope: "builder"
+  aicf.skill.strictness: "fail-closed-runtime"
+---
+
+# AICF Controls And Budgets
+
+## Purpose
+
+Guide AICF operational controls so capability exposure, execution, provider loops, and
+side effects can be denied, downgraded, budgeted, or forced through approval.
+
+## Use this skill when
+
+- Adding or auditing kill switches, circuit breakers, budgets, max loops, rate controls,
+  or read-only modes.
+- Blocking provider/model/capability usage before runtime execution.
+- Testing that controls fail closed without creating a model gateway.
+
+## Do not use this skill when
+
+- Adding provider runtimes, production storage, UI dashboards, or cloud resources.
+- Silently falling back to another provider after a control denial.
+- Exposing commit tools to models.
+
+## Inputs to inspect first
+
+- Controls schemas, runtime router/executor/lifecycle code, provider loops, governance
+  gate, policy broker, and tests.
+- References: [control types](references/control-types.md),
+  [budget policy](references/budget-policy.md), and
+  [circuit breakers](references/circuit-breakers.md).
+
+## Workflow
+
+1. Identify control scopes: global, provider, model, capability, domain, tenant,
+   autonomy, risk, and environment.
+2. Add kill switches for deny, force approval, and read-only behavior.
+3. Add circuit breakers for validation failures, policy denials, approval rejections,
+   provider errors, cost spikes, latency spikes, loop limits, or suspected cross-tenant
+   issues.
+4. Add budgets for max tool calls, provider calls, runtime duration, retries, tokens,
+   cost, tenant/account, capability, and provider fallback.
+5. Wire controls into routing, tool execution, lifecycle commit/verify, and provider
+   loops.
+6. Return safe denied envelopes or safe provider errors when controls block a path.
+7. Add tests for disabled capability, forced approval, read-only mode, max loop, and
+   budget exceeded.
+
+Use [controls policy](assets/controls-policy.yaml) and
+[budget fixture](assets/budget-fixture.json) as examples.
+
+## Required outputs
+
+- Controls implementation or audit notes with scopes and reason codes.
+- Tests proving route/export/execution/provider loops fail closed.
+- Handoff explaining host-owned storage and operational responsibilities.
+
+## Validation
+
+- Run controls, runtime, provider mock, governance gate, or package checks relevant to
+  the change.
+- Confirm denied controls prevent handler/provider calls before side effects.
+- Confirm controls are optional unless configured.
+
+## Hard rules
+
+- Do not create a general model gateway.
+- Do not hide control failure with silent fallback.
+- Do not execute prepare or commit when read-only controls apply.
+- Do not require live credentials or cloud resources for tests.
+
+## Handoff format
+
+Report controls added, scopes, decisions, runtime/provider seams touched, tests run, and
+remaining host operations work.

package/skills/aicf-controls-and-budgets/assets/budget-fixture.json

@@ -0,0 +1,15 @@
+{
+  "runId": "run_example_001",
+  "provider": "openai",
+  "model": "example-model",
+  "usage": {
+    "toolCalls": 4,
+    "providerCalls": 2,
+    "runtimeMs": 1200,
+    "retries": 0
+  },
+  "decision": {
+    "allowed": true,
+    "reasons": ["within_budget"]
+  }
+}

package/skills/aicf-controls-and-budgets/assets/controls-policy.yaml

@@ -0,0 +1,14 @@
+schemaVersion: "1.0"
+killSwitches:
+  - id: example-readonly-high-impact
+    mode: read_only
+    scope:
+      riskTier: high
+    reason: "Synthetic read-only control for high-impact actions."
+budgets:
+  - id: example-run-budget
+    scope:
+      provider: openai
+    maxToolCallsPerRun: 8
+    maxProviderCallsPerRun: 8
+    maxRuntimeMsPerRun: 60000

package/skills/aicf-controls-and-budgets/references/budget-policy.md

@@ -0,0 +1,12 @@
+# Budget Policy
+
+Common budget limits:
+
+- max tool calls per run.
+- max provider calls per run.
+- max runtime duration.
+- max retries.
+- optional token and cost limits.
+- tenant/account or capability hooks.
+
+When a hard limit is exceeded, fail closed with a safe reason.

package/skills/aicf-controls-and-budgets/references/circuit-breakers.md

@@ -0,0 +1,13 @@
+# Circuit Breakers
+
+Useful breaker metrics:
+
+- validation failure rate.
+- policy denial spike.
+- provider error spike.
+- approval rejection spike.
+- latency or cost spike.
+- loop limit exceeded.
+- security-test failure.
+
+Breaker state should be deterministic and visible through safe summaries.

package/skills/aicf-controls-and-budgets/references/control-types.md

@@ -0,0 +1,10 @@
+# Control Types
+
+Control modes:
+
+- deny: block export, routing, execution, or provider call.
+- force approval: permit prepare but require approval before commit.
+- read only: permit read/select and block side-effect paths.
+
+Scopes may include global, provider, model, capability, domain, tenant, autonomy, risk,
+and environment.