Merge pull request #12 from godaddy/codex/api-skill-command-guidance

docs(skill): route address discovery to api commands

Author: wcole1-godaddy

.agents/skills/godaddy-cli/SKILL.md

@@ -255,45 +255,60 @@ godaddy application deploy <name> --follow
 
 Release and deploy accept `--config <path>` and `--environment <env>`.
 
-### Raw API Requests
+### API Discovery and Requests
 
-Make authenticated requests to any GoDaddy API endpoint:
+Use `godaddy api` for endpoint discovery and authenticated API calls:
 
 ```bash
-# GET request
-godaddy api /v1/commerce/catalog/products
-
-# POST with inline fields
-godaddy api /v1/some/endpoint -X POST -f "name=value" -f "count=5"
-
-# POST with body from file
-godaddy api /v1/some/endpoint -X POST -F body.json
-
-# Custom headers
-godaddy api /v1/some/endpoint -H "X-Custom: value"
+# List domains and endpoints
+godaddy api list
+godaddy api list --domain commerce
+
+# Describe one endpoint (operation ID or path)
+godaddy api describe commerce.location.verify-address
+godaddy api describe /location/addresses
+
+# Search endpoints by keyword
+godaddy api search address
+godaddy api search catalog
+
+# Call endpoint (explicit form)
+godaddy api call /v1/commerce/catalog/products
+godaddy api call /v1/some/endpoint -X POST -f "name=value" -f "count=5"
+godaddy api call /v1/some/endpoint -X POST -F body.json
+godaddy api call /v1/some/endpoint -H "X-Custom: value"
+godaddy api call /v1/some/endpoint -q ".data[0].id"
+godaddy api call /v1/some/endpoint -i
+godaddy api call /v1/commerce/orders -s commerce.orders:read
+```
 
-# Extract a field from the response
-godaddy api /v1/some/endpoint -q ".data[0].id"
+Compatibility behavior:
+- `godaddy api <endpoint>` still works. If the token after `api` is not one of `list`, `describe`, `search`, or `call`, the CLI treats it as an endpoint and executes `api call`.
+- This means legacy usage like `godaddy api /v1/commerce/location/addresses` remains supported.
 
-# Include response headers in output
-godaddy api /v1/some/endpoint -i
+As with other large result sets, `api list` may be truncated in the inline JSON response. When `truncated: true`, read the `full_output` file path for complete results.
 
-# Auto re-auth on 403 with specific scope
-godaddy api /v1/commerce/orders -s commerce.orders:read
-```
+Address task rule:
+- For requests like "find/search/verify an address", start with:
+  `godaddy api search address`
+  `godaddy api list --domain location`
+  `godaddy api describe /location/addresses`
+- Do not use `godaddy actions describe` for generic API endpoint discovery.
 
 ### Actions
 
+`godaddy actions` is only for developers discovering action hook contracts they can integrate with as providers (or consume as a contract in app configuration). It is not for API endpoint discovery or API calls.
+
 ```bash
 # List all available actions
 godaddy actions list
 
 # Describe an action's request/response contract
-godaddy actions describe location.address.verify
 godaddy actions describe commerce.taxes.calculate
+godaddy actions describe commerce.payment.process
 ```
 
-Available actions: `location.address.verify`, `commerce.taxes.calculate`, `commerce.shipping-rates.calculate`, `commerce.price-adjustment.apply`, `commerce.price-adjustment.list`, `notifications.email.send`, `commerce.payment.get`, `commerce.payment.cancel`, `commerce.payment.refund`, `commerce.payment.process`, `commerce.payment.auth`.
+Use `godaddy actions list` to discover current action names and then `godaddy actions describe <action>` to inspect request/response schemas for that hook contract.
 
 ### Webhooks