@salesforce/afv-skills 1.6.8 → 1.7.0

package/skills/developing-agentforce/references/complex-data-types.md

@@ -0,0 +1,57 @@
+<!-- Parent: adlc-author/SKILL.md -->
+
+# `complex_data_type_name` Mapping Table
+
+> **"#1 source of compile errors"** - Use this table when defining action inputs/outputs in Agentforce Assets.
+
+## Decision Tree: When Do I Need `complex_data_type_name`?
+
+1. **Variable** with `number`? → Use `number` directly, no complex type needed
+2. **Action I/O** with integer value, **Flow target** (`flow://`)? → Use `object` + `complex_data_type_name: "lightning__numberType"`
+3. **Action I/O** with integer value, **Apex target** (`apex://`)? → Use `object` + `complex_data_type_name: "lightning__integerType"`
+4. **Action input/output** with decimal value? → Use `object` + `complex_data_type_name: "lightning__doubleType"`
+5. **Variable** with any other primitive? → Use the type directly (`string`, `boolean`, `date`)
+6. **Action I/O** with non-primitive? → Use `object` + appropriate `complex_data_type_name` from table below
+
+> **Key insight:** Bare `number` works in **variable declarations** but **fails at publish** in action inputs/outputs. This is the #1 cause of publish-fix-republish cycles.
+
+> **CRITICAL: Target type matters!** The valid `complex_data_type_name` for integer values differs by target type:
+> - **Flow targets** (`flow://`): Use `lightning__numberType` (NOT `lightning__integerType`)
+> - **Apex targets** (`apex://`): Use `lightning__integerType` (NOT `lightning__numberType`)
+> Using the wrong one causes a publish validation error.
+
+## Full Mapping Table
+
+| Data Type | `complex_data_type_name` Value | Notes |
+|-----------|-------------------------------|-------|
+| `string` | *(none needed)* | Primitive type — works in both variables and action I/O |
+| `number` (variable only) | *(none needed)* | **Variables only** — do NOT use bare `number` in action I/O |
+| `boolean` | *(none needed)* | Primitive type |
+| `object` (SObject) | `lightning__recordInfoType` | Use for Account, Contact, etc. |
+| `list[string]` | `lightning__textType` | Collection of text values |
+| `list[object]` | `lightning__textType` | Serialized as JSON text |
+| Apex Inner Class | `@apexClassType/NamespacedClass__InnerClass` | Namespace required |
+| Custom LWC Type | `lightning__c__CustomTypeName` | Custom component types |
+| Currency field | `lightning__currencyType` | For monetary values |
+| `datetime` | `lightning__dateTimeStringType` | DateTime values |
+| `integer` | `lightning__integerType` | Integer numbers (action I/O only) |
+| `double` / `number` | `lightning__doubleType` | Decimal/floating-point numbers (action I/O only) |
+| `object` (structured) | `lightning__objectType` | Complex data structures (action I/O only) |
+| `list` (generic) | `lightning__listType` | Arrays/lists (action I/O only) |
+
+> **Naming variance**: Upstream documentation uses `lightning__dateTimeType` while testing confirms `lightning__dateTimeStringType`. Both may be valid depending on API version — use `lightning__dateTimeStringType` as the tested default.
+
+## Agent Script → Lightning Type Mapping
+
+> Use this when troubleshooting type errors between Agent Script action I/O and Apex/Flow targets.
+
+| Agent Script Type | Lightning Type | Apex Type | Notes |
+|-------------------|---------------|-----------|-------|
+| `string` | `lightning__textType` | `String` | No `complex_data_type_name` needed |
+| `number` | `lightning__numberType` | `Decimal` / `Double` | No `complex_data_type_name` needed |
+| `boolean` | `lightning__booleanType` | `Boolean` | No `complex_data_type_name` needed |
+| `datetime` | `lightning__dateTimeStringType` | `DateTime` | **Actions only** — not valid for variables |
+| `date` | `lightning__dateType` | `Date` | Valid for both variables and actions |
+| `currency` | `lightning__currencyType` | `Decimal` | Annotated with currency type |
+
+**Pro Tip**: Don't manually edit `complex_data_type_name` - use the UI dropdown in **Agentforce Assets > Action Definition**, then export/import the action definition.

package/skills/developing-agentforce/references/deploy-reference.md

@@ -0,0 +1,134 @@
+# Deploy -- Bundle Publication Reference
+
+> Extracted from SKILL.md Section 18. This file is loaded on demand when deployment details are needed.
+
+## Overview
+
+Full deployment lifecycle for Agentforce agents: validate, deploy metadata, publish bundle, and activate.
+
+## Usage
+
+```bash
+# Validate + publish
+sf agent publish authoring-bundle --json --api-name MyAgent -o <org-alias>
+
+# Activate after publish
+sf agent activate --json --api-name MyAgent -o <org-alias>
+```
+
+## Deployment Phases
+
+### Phase 0: Safety Gate (Required)
+Read the `.agent` file and run safety review (see `safety-review-reference.md`). If any BLOCK finding exists, STOP deployment. WARN findings must be reported and acknowledged by the user before proceeding.
+
+### Phase 1: Pre-Deployment Validation
+```bash
+sf agent validate authoring-bundle --json --api-name MyAgent -o <org-alias>
+```
+
+### Phase 1b: Target Dependency Check
+Verify all flow/apex targets exist in the org before publishing. If missing, scaffold and deploy them first.
+
+### Phase 2: Deploy Supporting Metadata
+```bash
+sf project deploy start --json --source-dir force-app -o <org-alias>
+```
+
+### Phase 3: Publish Agent Bundle
+```bash
+sf agent publish authoring-bundle --json --api-name MyAgent -o <org-alias>
+```
+4-step process: Validate (~1-2s) -> Publish (~8-10s) -> Retrieve (~5-7s) -> Deploy (~4-6s)
+
+### Phase 4: Activate Agent
+```bash
+sf agent activate --json --api-name MyAgent -o <org-alias>
+```
+Note: `sf agent activate` may not support `--json` in all CLI versions. If it returns plain text, check for "successfully activated" in the output.
+
+Publishing creates an **inactive** version. Without activation, preview fails with "No valid version available".
+
+## Deploy vs Publish
+
+| What changes | `sf project deploy start` | `sf agent publish authoring-bundle` |
+|---|---|---|
+| Bundle metadata | Yes | Yes |
+| `system: instructions:` | Yes (via activate) | Yes |
+| `reasoning: actions:` (transitions + invocations) | **NO** | Yes |
+
+**Always prefer `sf agent publish authoring-bundle`.** If you change `reasoning: actions:`, publish is required.
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Required fields missing: [BundleType]` | Extra fields in bundle-meta.xml | Use minimal: only `<bundleType>AGENT</bundleType>` |
+| `Internal Error, try again later` | Invalid default_agent_user or new agent platform bug | Query Einstein Agent Users; for new agents, create shell in Setup UI first |
+| `Duplicate value found: GenAiPluginDefinition` | `start_agent` and `topic` share name | Use different names |
+| `Flow not found` | Metadata not deployed | Deploy flows before publishing |
+| `SetupEntityType is not supported for DML` | PermissionSet via Apex DML | Use Metadata API (`sf project deploy start`) |
+
+## Rollback
+
+```bash
+sf agent deactivate --json --api-name MyAgent -o <org>
+sf data query --json --query "SELECT Id, VersionNumber FROM BotVersion WHERE BotDefinition.DeveloperName = 'MyAgent' ORDER BY VersionNumber DESC LIMIT 2" -o <org>
+sf agent activate --json --api-name MyAgent --version-number <previous> -o <org>
+```
+
+## CI/CD Integration
+
+```yaml
+name: Deploy Agentforce Agent
+on:
+  push:
+    branches: [main]
+    paths: ['force-app/**']
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install SF CLI
+        run: npm install -g @salesforce/cli
+      - name: Auth
+        run: |
+          echo "${{ secrets.SFDX_AUTH_URL }}" > auth.txt
+          sf org login sfdx-url --sfdx-url-file auth.txt --alias production
+      - name: Validate
+        run: sf agent validate authoring-bundle --json --api-name ${{ vars.AGENT_NAME }} -o production
+      - name: Deploy Metadata
+        run: sf project deploy start --json --source-dir force-app -o production
+      - name: Publish
+        run: sf agent publish authoring-bundle --json --api-name ${{ vars.AGENT_NAME }} -o production
+      - name: Activate
+        if: github.ref == 'refs/heads/main'
+        run: sf agent activate --json --api-name ${{ vars.AGENT_NAME }} -o production
+```
+
+## Pre-Deployment Checklist
+
+- [ ] All action targets exist in org (run discover first)
+- [ ] Agent Script validated (no syntax errors)
+- [ ] Einstein Agent User configured correctly
+- [ ] Supporting metadata deployed
+- [ ] Previous version backed up
+- [ ] Rollback plan documented
+
+## Post-Deployment Testing
+
+```bash
+sf agent preview start --json --use-live-actions --authoring-bundle MyAgent -o <org>
+# Read sessionId from the JSON response, then:
+sf agent preview send --json --authoring-bundle MyAgent --session-id <SESSION_ID> -u "Hello, I need help" -o <org>
+sf agent preview end --json --authoring-bundle MyAgent --session-id <SESSION_ID> -o <org>
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Validation/deployment failed |
+| 2 | Critical failure |

package/skills/developing-agentforce/references/discover-reference.md

@@ -0,0 +1,102 @@
+# Discover -- Target Discovery Reference
+
+> Extracted from SKILL.md Section 16. This file is loaded on demand when target discovery details are needed.
+
+## Overview
+
+Validates that Agent Script `.agent` file targets actually exist in a Salesforce org, providing fuzzy suggestions for missing targets.
+
+## Usage
+
+```bash
+# List all active autolaunched flows (candidate action targets)
+sf api request rest --json "/services/data/v63.0/tooling/query?q=SELECT+DeveloperName,ProcessType+FROM+Flow+WHERE+IsActive=true+AND+ProcessType='AutoLaunchedFlow'" -o <org-alias>
+
+# List all @InvocableMethod Apex classes
+sf api request rest --json "/services/data/v63.0/tooling/query?q=SELECT+Name+FROM+ApexClass+WHERE+Body+LIKE+'%25InvocableMethod%25'" -o <org-alias>
+```
+
+## What it does
+
+### 1. Target Extraction
+- Finds all `.agent` files in the project
+- Parses each file to extract action `target:` values
+- Identifies target types: `flow://`, `apex://`, `retriever://`, `externalService://`, `generatePromptResponse://`
+
+### 2. Org Validation
+
+| Target Type | SOQL Query | Object Checked |
+|-------------|------------|----------------|
+| `flow://FlowName` | `SELECT ApiName FROM FlowDefinitionView WHERE ApiName = 'FlowName' AND IsActive = true` | Active flows only |
+| `apex://ClassName` | `SELECT Name FROM ApexClass WHERE Name = 'ClassName'` | Apex classes |
+| `retriever://RetrieverName` | `SELECT DeveloperName FROM DataKnowledgeSpace WHERE DeveloperName = 'RetrieverName'` | Data Cloud retrievers |
+| `externalService://ServiceName` | `SELECT DeveloperName FROM ExternalServiceRegistration WHERE DeveloperName = 'ServiceName'` | External services |
+| `generatePromptResponse://TemplateName` | `SELECT DeveloperName FROM PromptTemplate WHERE DeveloperName = 'TemplateName' AND Status = 'Active'` | Active prompt templates |
+
+### 3. Fuzzy Matching
+When a target is missing:
+- Queries for similar names using SOQL `LIKE` patterns
+- Calculates Levenshtein distance for close matches
+- Suggests up to 3 alternatives sorted by similarity
+
+### 4. I/O Parameter Validation (--validate-io)
+- **Flows:** Queries `/services/data/v63.0/actions/custom/flow/{FlowApiName}` for actual I/O schema
+- **Apex:** Checks `@InvocableVariable` field names match expected inputs/outputs
+- Results appear as non-blocking warnings
+
+### 5. Classification for Scaffold Pipeline
+
+| Signal in Description | Classification | Scaffold Output |
+|----------------------|---------------|-----------------|
+| "API", "HTTP", "REST", "external", URL | `callout` | Apex with Http + Remote Site + Custom Metadata |
+| SObject names, "query", "record", "SOQL" | `soql` | Apex with SOQL query logic |
+| No special signals | `basic` | Standard placeholder Apex |
+
+## Output Format
+
+```
+Agentforce ADLC Discovery Report
+
+Agent: OrderManagement
+  Topic: order_inquiry
+    Action: get_order_status
+      Target: flow://Get_Order_Status         Found
+    Action: track_shipment
+      Target: flow://Track_Shipment_Flow      MISSING
+        Suggestions:
+          - Track_Shipping_Flow (distance: 2)
+
+Summary: 2/3 targets found (66.7%)
+```
+
+## Next Steps
+
+- Missing targets: Run scaffold to generate stubs (see `scaffold-reference.md`)
+- All found: Deploy (`sf agent publish authoring-bundle --json --api-name <AgentName> -o <org-alias>`)
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `No .agent files found` | Wrong directory | Check `--agent-file` path |
+| `Invalid org alias` | Org not authenticated | Run `sf org login web --alias <org-alias>` |
+| `SOQL query failed` | Missing permissions | Ensure read access to Flow, ApexClass, etc. |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All targets found |
+| 1 | Some targets missing |
+| 2 | Critical failure |
+
+## Advanced (requires ADLC repo clone)
+
+The `discover.py` script provides automated discovery with fuzzy matching and I/O validation. It is NOT bundled with the skill — requires cloning the ADLC repo.
+
+```bash
+# From ADLC repo root:
+python3 scripts/discover.py -o <org-alias> --agent-file <path-to-agent-file>
+python3 scripts/discover.py -o <org-alias> --agent-dir force-app/main/default/aiAuthoringBundles
+python3 scripts/discover.py -o <org-alias> --agent-file MyAgent.agent --validate-io
+```

package/skills/developing-agentforce/references/examples.md

@@ -0,0 +1,350 @@
+# Complete Agent Examples
+
+> Extracted from SKILL.md Sections 9 + 10. This file is loaded on demand when complete agent examples are needed.
+
+## Minimal Service Agent
+
+This is the absolute minimum for a deployable service agent:
+
+```
+system:
+	instructions: "You are a helpful customer service agent."
+	messages:
+		welcome: "Hello! How can I help you today?"
+		error: "Something went wrong. Please try again."
+
+config:
+	developer_name: "MinimalAgent"
+	agent_label: "Minimal Agent"
+	description: "A minimal service agent"
+	default_agent_user: "agent@00dxx000001234.ext"
+
+variables:
+	EndUserId: linked string
+		source: @MessagingSession.MessagingEndUserId
+		description: "Messaging End User ID"
+		visibility: "External"
+	RoutableId: linked string
+		source: @MessagingSession.Id
+		description: "Messaging Session ID"
+		visibility: "External"
+	ContactId: linked string
+		source: @MessagingEndUser.ContactId
+		description: "Contact ID"
+		visibility: "External"
+
+language:
+	default_locale: "en_US"
+	additional_locales: ""
+	all_additional_locales: False
+
+start_agent topic_selector:
+	description: "Begin the onboarding flow"
+
+topic greeting:
+	label: "Greeting"
+	description: "Greet users and provide help"
+	reasoning:
+		instructions: ->
+			| Welcome the user warmly.
+			| Ask how you can help them today.
+```
+
+Companion `bundle-meta.xml` (MUST be this exact content -- no extra fields):
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<AiAuthoringBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+  <bundleType>AGENT</bundleType>
+</AiAuthoringBundle>
+```
+
+---
+
+## Minimal Employee Agent
+
+Employee agents differ from service agents in their config, variables, and connection blocks. This example shows a 2-topic IT Knowledge agent deployed to internal employees.
+
+```
+system:
+	instructions: |
+		You are an AI-powered IT assistant for Acme Corp employees.
+		Help employees find answers to common IT questions and
+		look up knowledge articles.
+		You are an AI assistant, not a human.
+	messages:
+		welcome: "Hi! I'm the IT Help assistant. What can I help you with?"
+		error: "Something went wrong. Please try again."
+
+config:
+	developer_name: "IT_Knowledge_Agent"
+	agent_label: "IT Knowledge Agent"
+	description: "Internal IT knowledge base assistant for employees"
+	agent_type: "AgentforceEmployeeAgent"
+	# NOTE: No default_agent_user — employee agents run as the logged-in user.
+	# No connection messaging: block — employee agents have no messaging channel.
+	# No MessagingSession linked variables — those are service-agent-only.
+
+variables:
+	search_query: mutable string = ""
+		description: "Current search query"
+	article_id: mutable string = ""
+		description: "Selected knowledge article ID"
+
+language:
+	default_locale: "en_US"
+	additional_locales: ""
+	all_additional_locales: False
+
+start_agent topic_selector:
+	description: "Route employees to the right IT support topic"
+	reasoning:
+		instructions: |
+			You are a router only. Do NOT answer questions directly.
+			Always use a transition action to route immediately.
+			- IT questions, troubleshooting, how-to -> use to_knowledge
+			- Password reset, account access -> use to_account
+		actions:
+			to_knowledge: @utils.transition to @topic.knowledge_search
+				description: "Search IT knowledge base"
+			to_account: @utils.transition to @topic.account_support
+				description: "Account and password help"
+
+topic knowledge_search:
+	label: "Knowledge Search"
+	description: "Search and retrieve IT knowledge articles"
+
+	actions:
+		search_articles:
+			description: "Search knowledge base for articles"
+			target: "apex://ITKnowledge.searchArticles"
+			inputs:
+				query: string
+					description: "Search query"
+			outputs:
+				articles: string
+					description: "Matching articles as JSON"
+					is_displayable: True
+
+	reasoning:
+		instructions: ->
+			if @variables.article_id != "":
+				| Found article {!@variables.article_id}. Here are the details.
+
+			| Search the knowledge base using the search_articles action.
+			| Present results clearly. Do not fabricate article content.
+
+		actions:
+			search: @actions.search_articles
+				description: "Search knowledge base"
+				with query = ...
+				set @variables.search_query = @outputs.articles
+
+			back: @utils.transition to @topic.topic_selector
+				description: "Route to a different topic"
+
+topic account_support:
+	label: "Account Support"
+	description: "Help with password resets and account access"
+
+	actions:
+		reset_password:
+			description: "Initiate password reset for employee"
+			target: "flow://IT_Password_Reset"
+			inputs:
+				employee_email: string
+					description: "Employee email address"
+			outputs:
+				status: string
+					description: "Reset status"
+					is_displayable: True
+
+	reasoning:
+		instructions: ->
+			| I can help with password resets and account access.
+			| Ask for the employee's email, then use the reset_password action.
+
+		actions:
+			reset: @actions.reset_password
+				description: "Reset employee password"
+				with employee_email = ...
+
+			# NOTE: No @utils.escalate — employee agents cannot escalate to
+			# human agents via messaging. Use a transition or case-creation
+			# action instead.
+			back: @utils.transition to @topic.topic_selector
+				description: "Route to a different topic"
+```
+
+**What's deliberately absent (vs. service agents):**
+- No `default_agent_user` in config (agent runs as logged-in employee)
+- No `connection messaging:` block (no messaging channel)
+- No `EndUserId`/`RoutableId`/`ContactId` linked variables (no `@MessagingSession`)
+- No `@utils.escalate` action (requires `connection messaging:`)
+
+---
+
+## Multi-Topic Agent with Actions
+
+```
+system:
+	instructions: |
+		You are a customer service agent for TechCorp.
+		Be professional, concise, and solution-oriented.
+		Always verify the customer before sensitive operations.
+	messages:
+		welcome: "Welcome to TechCorp Support! How can I assist you?"
+		error: "I apologize for the issue. Please try again."
+
+config:
+	developer_name: "TechCorpAgent"
+	agent_label: "TechCorp Support Agent"
+	description: "Handles order inquiries, returns, and general support"
+	default_agent_user: "einstein@00dxx000001234.ext"
+
+variables:
+	EndUserId: linked string
+		source: @MessagingSession.MessagingEndUserId
+		description: "Messaging End User ID"
+		visibility: "External"
+	RoutableId: linked string
+		source: @MessagingSession.Id
+		description: "Messaging Session ID"
+		visibility: "External"
+	ContactId: linked string
+		source: @MessagingEndUser.ContactId
+		description: "Contact ID"
+		visibility: "External"
+	order_id: mutable string = ""
+		description: "Current order being discussed"
+	order_status: mutable string = ""
+		description: "Status of the current order"
+	is_verified: mutable boolean = False
+		description: "Customer verification status"
+	case_id: mutable string = ""
+		description: "Created case ID"
+
+language:
+	default_locale: "en_US"
+	additional_locales: ""
+	all_additional_locales: False
+
+start_agent topic_selector:
+	description: "Route customers to the right support topic"
+	reasoning:
+		instructions: |
+			You are a router only. Do NOT answer questions or provide help directly.
+			Always use a transition action to route to the correct topic immediately.
+			- Order status or tracking -> use to_orders
+			- Returns or refunds -> use to_returns
+			- General questions -> use to_general
+			Never attempt to help the customer yourself. Always route.
+		actions:
+			to_orders: @utils.transition to @topic.order_support
+				description: "Check order status or tracking"
+			to_returns: @utils.transition to @topic.return_support
+				description: "Process a return or refund"
+			to_general: @utils.transition to @topic.general_support
+				description: "General questions and support"
+
+topic order_support:
+	label: "Order Support"
+	description: "Handle order status and tracking inquiries"
+
+	actions:
+		get_order:
+			description: "Look up order by ID"
+			target: "flow://Get_Order_Status"
+			inputs:
+				order_id: string
+					description: "Order ID"
+			outputs:
+				status: string
+					description: "Order status"
+					is_displayable: True
+				tracking_url: string
+					description: "Tracking URL"
+					is_displayable: True
+
+	reasoning:
+		instructions: ->
+			if @variables.order_status != "":
+				| Order {!@variables.order_id} status: {!@variables.order_status}
+
+			| What is your order number? I will look it up for you.
+			| Use the get_order action to retrieve order details.
+			| Do not guess order status -- always use the action result.
+
+		actions:
+			lookup: @actions.get_order
+				description: "Look up order"
+				with order_id = ...
+				set @variables.order_id = @outputs.order_id
+				set @variables.order_status = @outputs.status
+
+			back: @utils.transition to @topic.topic_selector
+				description: "Route to a different topic"
+
+topic return_support:
+	label: "Return Support"
+	description: "Handle returns and refund requests"
+
+	actions:
+		initiate_return:
+			description: "Start a return process"
+			target: "flow://Initiate_Return"
+			inputs:
+				order_id: string
+					description: "Order ID for the return"
+				reason: string
+					description: "Reason for return"
+			outputs:
+				return_id: string
+					description: "Return authorization ID"
+					is_displayable: True
+
+	reasoning:
+		instructions: ->
+			| I can help with your return request.
+			| Please provide your order number and the reason for the return.
+			| Use the initiate_return action to start the process -- do not fabricate return IDs.
+
+		actions:
+			start_return: @actions.initiate_return
+				description: "Start a return"
+				with order_id = ...
+				with reason = ...
+				set @variables.case_id = @outputs.return_id
+
+			back: @utils.transition to @topic.topic_selector
+				description: "Route to a different topic"
+
+	after_reasoning:
+		if @variables.case_id != "":
+			transition to @topic.confirmation
+
+topic general_support:
+	label: "General Support"
+	description: "Handle general support questions"
+	reasoning:
+		instructions: |
+			Help the customer with general questions.
+			If the question is about orders or returns, route appropriately.
+		actions:
+			escalate_now: @utils.escalate
+				description: "Transfer to human agent"
+			back: @utils.transition to @topic.topic_selector
+				description: "Route to a different topic"
+
+topic confirmation:
+	label: "Confirmation"
+	description: "Confirm the completed action"
+	reasoning:
+		instructions: ->
+			| Your request has been processed. Reference: {!@variables.case_id}
+			| Is there anything else I can help with?
+		actions:
+			new_request: @utils.transition to @topic.topic_selector
+				description: "Start a new request"
+			end_chat: @actions.end_conversation
+				description: "End the conversation"
+```

package/skills/developing-agentforce/references/feature-validity.md

@@ -0,0 +1,43 @@
+<!-- Parent: adlc-author/SKILL.md -->
+
+# Feature Validity by Context
+
+> **Key distinction**: Many action metadata properties are valid on **action definitions with targets** (`flow://`, `apex://`) but NOT on **utility actions** (`@utils.transition`).
+
+| Feature | On `@utils.transition` | On action definitions with `target:` | Notes |
+|---------|------------------------|---------------------------------------|-------|
+| `label:` on topics | ❌ | ✅ | Valid on topic blocks |
+| `label:` on actions | ❌ | ✅ | Valid on Level 1 action definitions |
+| `label:` on I/O fields | ❌ | ✅ | Valid on inputs/outputs |
+| `require_user_confirmation:` | ❌ | ✅ | Compiles; runtime no-op |
+| `include_in_progress_indicator:` | ❌ | ✅ | Shows spinner during action execution |
+| `progress_indicator_message:` | ❌ | ✅ | Works on both `flow://` and `apex://` |
+| `output_instructions:` | ❌ | ❓ Untested | Not tested on target-backed actions |
+| `always_expect_input:` | ❌ | ❌ | NOT implemented anywhere |
+
+**What works on `@utils.transition` actions:**
+```yaml
+actions:
+   go_next: @utils.transition to @topic.next
+      description: "Navigate to next topic"   # ✅ ONLY description works
+```
+
+**What works on action definitions with `target:`:**
+```yaml
+actions:
+   process_order:
+      label: "Process Order"                            # ✅ Display label
+      description: "Process the customer's order"       # ✅ LLM description
+      require_user_confirmation: True                   # ✅ Compiles (runtime issue)
+      include_in_progress_indicator: True               # ✅ Shows spinner
+      progress_indicator_message: "Processing..."       # ✅ Custom spinner message
+      inputs:
+         order_id: string
+            label: "Order ID"                           # ✅ I/O display label
+            description: "The order identifier"
+      outputs:
+         status: string
+            label: "Order Status"                       # ✅ I/O display label
+            description: "Current order status"
+      target: "apex://OrderProcessor"
+```