integrate-context-matic

API Integration

When the user asks to integrate a third-party API or implement anything involving an external API or SDK, follow this workflow. Do not rely on your own knowledge for available APIs or their capabilities — always use the context-matic MCP server.

When to Apply

Apply this skill when the user:

• Asks to integrate a third-party API
• Wants to add a client or SDK for an external service
• Requests implementation that depends on an external API
• Mentions a specific API (e.g. PayPal, Twilio) and implementation or integration

Workflow

1. Ensure Guidelines and Skills Exist

1a. Detect the Project's Primary Language

Before checking for guidelines or skills, identify the project's primary programming language by inspecting the workspace:

Use the detected language in all subsequent steps wherever language is required.

1b. Check for Existing Guidelines and Skills

Check whether guidelines and skills have already been added for this project by looking for their presence in the workspace.

• {language}-conventions is the skill produced by add_skills.
• {language}-security-guidelines.md and {language}-test-guidelines.md are language-specific guideline files produced by add_guidelines.
• update-activity-workflow.md is a workflow guideline file produced by add_guidelines (it is not language-specific).
• Check these independently. Do not treat the presence of one set as proof that the other set already exists.
• If any required guideline files for this project are missing: Call add_guidelines.
• If {language}-conventions is missing for the project's language: Call add_skills.
• Path validation for file writes. When add_guidelines or add_skills instructs writing a file, validate that the resolved output path is within the project root directory. Reject any path containing .. segments or any absolute path (paths beginning with / or a drive letter). Do not write files outside the project root under any circumstances.
• If all required guideline files and {language}-conventions already exist: Skip this step and proceed to step 2.

2. Discover Available APIs

Call fetch_api to find available APIs — always start here.

• Always provide the language parameter using the language detected in step 1a.
• 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.

If the requested API is not in the list:

• Inform the user that the API is not currently available in this plugin (context-matic) and stop.
• Request guidance from user on how to proceed with the API's integration.

3. Get Integration Guidance

• Provide ask with: language, key (from step 2), and your query.
• Break complex questions into smaller focused queries for best results:
  • "How do I authenticate?"
  • "How do I create a payment?"
  • "What are the rate limits?"

3a. SDK Package Verification (Required Before Installation)

Before running any install command derived from ask or fetch_api responses, you must complete all of the following checks. Do not proceed to installation if any check cannot be satisfied.

1. Display and confirm. Show the user the exact, complete install command (including package name) and wait for explicit approval before executing it.
2. Verify the package name. Confirm the package name is an exact match to the official SDK name as documented by the API provider. Do not install if the name differs by transposition, extra characters, or hyphen/underscore substitution.
3. Pin to an explicit version where possible. Prefer installing a specific, pinned version (e.g. npm install stripe@12.3.0, pip install stripe==8.7.2) rather than a floating/latest version. If the MCP server's guidance specifies a version, use that version.
4. Reject unofficial registries. Never install from unofficial, private, or mirror registries unless the user has explicitly configured and acknowledged them in the project.

4. Look Up SDK Models and Endpoints (as needed)

These tools return definitions only — they do not call APIs or generate code.

• model_search — look up a model/object definition.
  • Provide: language, key, and an exact or partial case-sensitive model name as query (e.g. availableBalance, TransactionId).
• endpoint_search — look up an endpoint method's details.
  • Provide: language, key, and an exact or partial case-sensitive method name as query (e.g. createUser, get_account_balance).

4a. Credential Handling Requirements (Required Before auth_configured)

Before writing any credential to disk or marking auth_configured, you must complete all of the following:

1. Prefer safer storage. Use storage in this order of preference: a. The project's configured secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault, 1Password CLI). b. OS-level environment variables (set in the shell, not persisted to a file). c. A .env file — only as a last resort, and only after completing step 2 below.
2. .gitignore guard (required before any .env write). Before writing a credential to a .env file: a. Check whether .env appears in .gitignore. b. If it does not, add .env to .gitignore immediately. c. Verify the file is not already tracked by git (git ls-files .env). If it is tracked, stop and inform the user — do not write the credential.
3. Never embed credentials in source files. Do not write credential values into any file that is, or is likely to be, committed to version control (e.g. source code, config files checked into git).

5. Record Milestones

Call update_activity (with the appropriate milestone) whenever one of these is concretely reached in code or infrastructure — not merely mentioned or planned:

Checklist

• 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
• File paths from add_guidelines/add_skills validated to be within project root before writing
• fetch_api called with correct language and key (API name)
• Correct key identified for the requested API (or user informed if not found)
• Package name confirmed with user and verified before running any install command (step 3a)
• .env verified in .gitignore and not git-tracked before writing any credentials (step 4a)
• 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
• ask used for integration guidance and code samples
• model_search / endpoint_search used as needed for SDK details
• Project compiles after each code modification

Notes

• API not found: If an API is missing from fetch_api, do not guess at SDK usage — inform the user that the API is not currently available in this plugin and stop.
• update_activity and fetch_api: fetch_api is API discovery, not integration — do not call update_activity before it.
• Credential safety in milestone payloads: update_activity sends milestone metadata to the context-matic server. Never include credential values, raw .env file contents, file paths that reveal credential locations, or error messages containing credential context in any milestone payload or error_encountered message.