feat: update readme and skills (#1418)

* feat: update readme and skills

* Update plugins/context-matic/README.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

plugins/context-matic/README.md

@@ -53,8 +53,8 @@ This list is growing. [Suggest a new API](#contributing) to request support for
 Once installed, the plugin exposes seven tools to the agent. Each tool is mapped to a specific stage of the integration workflow:
 
 | Tool              | Developer task it enables                                                                                                                                                                                                                                                                                                                                 |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fetch_api`       | Lists all available APIs with their name, key, and description. The agent calls this first to discover which APIs are available for your project's language.                                                                                                                  |
+| `fetch_api`       | Provides an exact API match or lists all available APIs for the provided `language`, including each API's name, key, and description. Pass your project's language and an API `key` for an exact-match lookup (returns only that API). The full API catalog for that `language` is returned if no exact match is found. The agent calls this first to discover which APIs are available. |
 | `ask`             | Chat with API Copilot for step-by-step integration guidance and general API questions: authentication setup, client initialization, feature behavior, framework-specific patterns (e.g. "How do I initialize the Twilio client in Laravel?"), and idiomatic SDK code samples.                                                                             |
 | `endpoint_search` | Returns an SDK endpoint method's description, input parameters, and response shape by method name.                                                                                                                                                                                                                                                        |
 | `model_search`    | Returns an SDK model's full definition and its typed properties by name. Call this before writing code that constructs request bodies or reads response objects.                                                                                                                                                                     |
@@ -76,7 +76,7 @@ The seven tools are designed to chain together in a natural integration workflow
 | ---- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 1    | `add_guidelines` (`language=typescript`)                                          | Adds project guideline files the agent can follow for security, testing, and implementation workflow before starting the API integration.                                 |
 | 2    | `add_skills` (`language=typescript`)                                              | Adds reusable language-specific skills such as conventions guidance so the project setup matches future integration work.                                                 |
-| 3    | `fetch_api` (`language=typescript`)                                               | Discovers Twilio is available; returns its `key`                                                                                                                          |
+| 3    | `fetch_api` (`language=typescript`, `key="twilio"`)                               | Exact match found — returns Twilio's entry with its name, key, and description                                                                                            |
 | 4    | `ask` (`key=twilio`, query=_"How do I initialize the Twilio TypeScript client?"_) | Returns exact SDK setup code with auth configuration                                                                                                                      |
 | 5    | `update_activity` (`milestone=auth_configured`)                                   | After the returned SDK/auth configuration has been added to the app, records that credentials are wired into the app and the integration is ready for the first live call |
 | 6    | `endpoint_search` (`query=createMessage`)                                         | Returns the method signature, required parameters, and auth requirements for the SMS send endpoint                                                                        |

skills/integrate-context-matic/SKILL.md

@@ -51,8 +51,10 @@ Check whether guidelines and skills have already been added for this project by
 
 Call **fetch_api** to find available APIs — always start here.
 
-- Provide the `language` parameter using the language detected in step 1a.
+- Always provide the `language` parameter using the language detected in step 1a.
-- The response returns available APIs with their names, descriptions, and `key` values.
+- Always provide the `key` parameter: pass the API name/key from the user's request (e.g. `"paypal"`, `"twilio"`).
+- If the user did not provide an API name/key, ask them which API they want to integrate, then call `fetch_api` with that value.
+- The tool returns only the matching API on an exact match, or the full API catalog (name, description, and `key`) when there is no exact match.
 - Identify the API that matches the user's request based on the name and description.
 - Extract the correct `key` for the user's requested API before proceeding. This key will be used for all subsequent tool calls related to that API.
 
@@ -94,7 +96,7 @@ Call **update_activity** (with the appropriate `milestone`) whenever one of thes
 - [ ] Project's primary language detected (step 1a)
 - [ ] `add_guidelines` called if guideline files were missing, otherwise skipped
 - [ ] `add_skills` called if `{language}-conventions` was missing, otherwise skipped
-- [ ] `fetch_api` called with correct `language` for the project
+- [ ] `fetch_api` called with correct `language` and `key` (API name)
 - [ ] Correct `key` identified for the requested API (or user informed if not found)
 - [ ] `update_activity` called only when a milestone is concretely reached in code/infrastructure — never for questions, searches, or tool lookups
 - [ ] `update_activity` called with the appropriate `milestone` at each integration milestone

skills/onboard-context-matic/SKILL.md

@@ -41,7 +41,7 @@ Use the following facts as your source, but say it conversationally — do not p
 
 > | Tool | What it does | When to use it | What you get back |
 > |---|---|---|---|
-> | `fetch_api` | Lists all APIs available on this server for a given language | "What APIs can I use?" / Starting a new project | A named list of available APIs with short descriptions |
+> | `fetch_api` | Returns an exact match for an API `key`/identifier and language, or lists all APIs for a given language. The `key` is the machine-readable identifier returned by `fetch_api` (for example, `paypal`), not the human-readable display name (for example, "PayPal Server SDK"). | "What APIs can I use?" / Starting a new project / "Do you have the PayPal SDK?" | A named list of available APIs with short descriptions (full catalog), or one exact API match when you provide its identifier/key and language |
 > | `ask` | Answers integration questions with version-accurate guidance and code samples | "How do I authenticate?", "Show me the quickstart", "What's the right way to do X?" | Step-by-step guidance and runnable code samples grounded in the actual SDK version |
 > | `model_search` | Looks up an SDK model/object definition and its typed properties | "What fields does an Order have?", "Is this property required?" | The model's name, description, and a full typed property list (required vs. optional, nested types) |
 > | `endpoint_search` | Looks up an endpoint method, its parameters, response type, and a runnable code sample | "Show me how to call createOrder", "What does getTrack return?" | Method signature, parameter types, response type, and a copy-paste-ready code sample |
@@ -76,7 +76,7 @@ Store the detected language — you will pass it to every subsequent tool call.
 Tell the user which language you detected and that you are fetching the available APIs — for
 example: *"I can see this is a TypeScript project. Let me fetch the APIs available for TypeScript."*
 
-Call **`fetch_api`** with `language` = the detected language.
+Call **`fetch_api`** with `language` = the detected language and `key` = "" so the tool returns the full list of available APIs.
 
 Display the results as a formatted list, showing each API's **name** and a one-sentence summary of
 its **description**. Do not truncate or skip any entry.
@@ -189,9 +189,9 @@ Before calling, say something like: *"Let me fetch the `[endpoint name]` endpoin
 
 Pick a **representative endpoint** for the chosen API and call **`endpoint_search`** with an explicit argument object:
 
-- `key`: the API key you are demonstrating (for example, `paypal` or `spotify`)
+- `key` = the API key you are demonstrating (for example, `paypal` or `spotify`)
-- `query`: the endpoint / SDK method name you want to look up (for example, `createOrder` or `getTrack`)
+- `query` = the endpoint / SDK method name you want to look up (for example, `createOrder` or `getTrack`)
-- `language`: the user's project language (for example, `"typescript"` or `"python"`)
+- `language` = the user's project language (for example, `"typescript"` or `"python"`)
 
 For example: