Modernize integration skills to support both Secrets and OAuth MCP servers

[jpelletier1]

Problem

Our current integration skills (github, linear, gitlab, bitbucket, azure-devops, etc.) are highly prescriptive about authentication mechanisms, explicitly instructing agents to use environment variables like GITHUB_TOKEN, LINEAR_API_KEY, GITLAB_TOKEN, etc.

With the rise and adoption of OAuth MCP servers in Canvas, this approach is too rigid. These skills should instead adopt a generic, layered approach that checks for available authentication methods in order of preference:

1. Check for OAuth MCP server connections
2. Fall back to environment variable Secrets (e.g., GITHUB_TOKEN)
3. Prompt the user if neither is available

Affected Skills

The following skills need to be updated:

• github - Currently prescribes GITHUB_TOKEN
• linear - Currently prescribes LINEAR_API_KEY
• gitlab - Currently prescribes GITLAB_TOKEN
• bitbucket / bitbucket-cloud / bitbucket-data-center - Currently prescribe BITBUCKET_TOKEN / BITBUCKET_DATA_CENTER_TOKEN
• azure-devops - Currently prescribes AZURE_DEVOPS_TOKEN
• Any other integration skills that rely on service-specific tokens

Proposed Solution

Each skill should:

1. Check for MCP server availability first

   • If an OAuth MCP server for the service is connected (e.g., GitHub MCP), use it
   • MCP servers provide richer, session-based OAuth authentication

2. Fall back to Secret environment variables

   • Check if the relevant token (e.g., GITHUB_TOKEN) is set
   • Use the existing token-based authentication flow

3. Prompt the user if neither exists

   • Ask the user to either connect an MCP server or provide a token
   • Provide clear instructions for both options

Example Pattern

Instead of:

You have access to an environment variable, `GITHUB_TOKEN`, which allows you to interact with the GitHub API.

Use:

You can interact with GitHub using one of the following methods:

1. **OAuth MCP Server** (preferred): If a GitHub MCP server is connected, use it for authenticated operations
2. **Secret Token**: If `GITHUB_TOKEN` environment variable is set, use it with the GitHub API
3. **No authentication**: If neither is available, inform the user and ask them to either:
   - Connect a GitHub OAuth MCP server in Canvas, OR
   - Provide a `GITHUB_TOKEN` as a Secret

Benefits

• Future-proof: Supports modern OAuth MCP workflows
• Backward compatible: Existing Secret-based auth still works
• User choice: Users can choose their preferred authentication method
• Better UX in Canvas: OAuth MCP servers provide seamless, session-based auth without manual token management

Implementation Notes

• Skills should be updated to include detection logic or instructions for checking both methods
• The agent should prioritize MCP servers when available (better security, scoped permissions)
• Documentation should reflect both authentication paths
• Consider creating a shared authentication skill/pattern that other skills can reference

---

Context: This issue was created to align our skills with the evolving Canvas ecosystem and OAuth MCP server adoption.

---

OpenHands AI triage

The following comments and acceptance criteria were added by the OpenHands AI agent.

Triage

This is a documentation/instruction change to integration skills, not a code change. The repository already owns an authoritative precedent for the requested behavior: skills/notion/SKILL.md states "If authenticated Notion MCP tools are available in the environment, use them first" and directs the token/REST path to be used "only when MCP is unavailable". That resolves the ordering question from the related issue (#673: prefer MCP when both are available) and the detection question (detect by presence of authenticated MCP tools, not by an environment variable, server name, or naming convention). No new mechanism is introduced.

Bounded scope: apply the MCP-first / token-fallback guidance, plus a fallback prompt to the user when neither is available, to the skills named in the issue: skills/github, skills/linear, skills/gitlab, skills/bitbucket and its bitbucket-cloud / bitbucket-data-center sub-skills, and skills/azure-devops. Each skill's human-facing README.md and the generated skills/index.js are updated in the same change.

Explicit non-goals:

• Do not remove or alter the existing token-based instructions; token-only environments must behave exactly as before.
• Do not add, bundle, or configure MCP servers, and do not implement OAuth flows.
• Do not extend this change to other token-using skills (notion already follows MCP-first; datadog, discord, github-actions, github-pr-review, slack-channel-monitor, and the automation skills are out of scope).
• Do not create a new shared authentication skill or extract the pattern into a referenced common file. The repository precedent is inline, per-skill guidance (skills/notion), and a shared skill would also require a marketplace entry. That consolidation can be evaluated separately if the inline pattern proves repetitive.
• Do not change the Python entrypoints shipped with automation skills (skills/*/scripts/main.py), the automations catalog, or marketplace entries.

Acceptance Criteria

• Each in-scope skill (github, linear, gitlab, bitbucket, bitbucket-cloud, bitbucket-data-center, azure-devops) instructs the agent to use the service's authenticated MCP tools first when those tools are available, and to use that skill's documented token/direct-API flow only when they are not (or when raw API/curl access is explicitly needed).
• Detection is described generically as the availability of authenticated MCP tools for the service; no specific MCP server name, tool name, or environment variable is required to detect it.
• When neither an MCP connection nor the token is available, each in-scope skill instructs the agent to ask the user and presents both options: connect the service's MCP server, or provide the token as a Secret.
• The existing token-based instructions (including the IMPORTANT token/API blocks and remote-URL guidance) remain present and behaviorally unchanged, so a token-only environment is unaffected.
• MCP-first guidance does not change the existing push/PR safety rules or the create_pr / create_mr / create_bitbucket_pr tool guidance.
• skills/bitbucket still routes to bitbucket-cloud vs bitbucket-data-center with its existing detection logic, and both sub-skills carry the MCP-first / token-fallback guidance.
• Each in-scope skill's README.md reflects the same authentication guidance as its SKILL.md.
• skills/index.js is regenerated with npm run build:skills so its embedded skill content matches the updated SKILL.md files.
• Updated content uses plain hyphens, not em dashes, per repository conventions.
• python scripts/sync_extensions.py --check passes and the test suite (uv run pytest -q) passes, including the skills README and catalog coverage checks.
• No new skills or marketplace entries are added.