--- name: write-integration-skill description: Guide for creating agent skills that integrate with external SaaS tools and services. Use when asked to write a new integration skill, create an integration, or make a repeatable workflow for talking to an API, CLI, or external service. metadata: team: product --- # Writing Integration Skills **Do not jump straight to writing a SKILL.md.** Follow this three-step workflow — it will save you from writing a skill that doesn't actually work: 1. **Research the integration path** — figure out how to talk to the service (API, CLI, MCP, data warehouse, browser, etc.). Don't write anything yet. 2. **Actually do the thing** — use that path to solve the user's real problem. Fight through the auth quirks, pagination, and gotchas. 3. **Now write the skill** — capture what worked as a SKILL.md so any agent can repeat it. Only write code/script/python if absolutely necessary or requested by the user. ## Step 1: Research the integration path Before writing anything, figure out how to programmatically talk to the target service. Research the following options. **Pick whichever is easiest, not "most sophisticated":** - **API** — Does the service have a REST/GraphQL API? Does it expose the information and actions you need? If so, you can use the Bash tool to call `curl` its way to success. Read the public docs to understand the auth mechanism. If it needs an API key, get one. If the API requires OAuth, consider a CLI or MCP option first — OAuth is a pain. - **CLI** — Does the service have a command-line tool? CLIs are great because they handle auth complexity for you. Use `npx` or `uvx` to run CLIs without managing installs or virtual envs. Example: GitHub's `gh` CLI handles HTTPS vs SSH auth automatically, and `gh api` gives you a full API passthrough with built-in auth. - **MCP server** — Does the service have an MCP server? Skills can wrap MCP servers with workflows. This is Anthropic's recommended approach for combining skills and MCP. You can also use `npx` or `uvx` to run an mcp server on demand locally. - **Data warehouse** — If your data is already available in your data warehouse, you can query what you already have access to using the CLI for snowflake or bigquery. This is a great path when you don't have direct access to the tool. For example: Your PM team may not have Zendesk access but can query Zendesk ticket history in your data warehouse to analyze user feedback. - **Browser** — Worst case, just use the Chrome to access the thing. Claude's built-in browser can reuse existing sessions (you'll need to run claude code `claude --chrome` with access). - **Get creative** — Desktop app? Try AppleScript. Android app? Try ADB. If you as a human can access it, you can likely find a path. **Important:** You may try one path and realize you need to switch to another. That's fine. You might even need a combination. But do not move to step 2 until you have a path that seems viable. ## Step 2: Actually do the thing Still don't write the skill. Instead, use whatever integration path you picked in step 1 to **actually solve the user's problem**. Do the thing they asked for — query the data, read the records, trigger the action. Fight through issues along the way: auth quirks, pagination, weird response formats, rate limits. That's the point. Figure out the gotchas now so they go into the skill. **Do not move to step 3 until you've successfully completed the task at least once.** ## Step 3: Now write the skill You've done it manually. You know what works. Now write a SKILL.md that captures what you learned so any agent can repeat it. ### Skill format Create `skills//SKILL.md` with this structure: ```yaml --- name: # lowercase, hyphens only description: <1-2 sentences> # when to use this skill — be specific --- ``` The description is critical for discoverability. Write it so the skill triggers on both explicit invocation (`/skill-name`) and implicit matching from the user's prompt. ### Content guidelines - **Concise and actionable.** Skills are instructions, not documentation. Write them like a recipe. - **Prerequisites first.** Auth setup, CLI installs, required access. - **Include the exact commands that worked** in step 2. Don't generalize — keep the specific flags, formats, and workarounds you discovered. - **Document the gotchas** you hit. These save the most time on future runs. - **Add a troubleshooting section** if the integration has common failure modes. - **Keep it portable** across Codex, Claude Code, and Cursor. - **No secrets.** Never put API keys, tokens, passwords, or PII in the skill. Reference environment variables or auth commands instead. ## Evolving the skill Skills are living documents. Next time you use the skill and hit a new issue or discover a new use case, edit the SKILL.md to add it. This is the simplest way to build something reusable over time. ## References - [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) - [The Complete Guide to Building Skills for Claude (PDF)](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) - [Generate skills afterwards](https://www.seangoedecke.com/generate-skills-afterwards/) — skills are much easier to write once you've figured out how to do it