How to Build a Claude Code Skill That Calls Any API (Step-by-Step Tutorial)

Quick Answer

A Claude Code skill is a reusable markdown file that tells Claude exactly how to perform a task, like calling an external API. You'll create one by dropping a .md file into your project's .claude/skills folder with plain-language instructions that describe the API call, headers, and expected response. When you invoke the skill inside Claude Code, it handles the rest.

Why bother? Because once the skill exists, anyone on your team can generate carousels (or hit any other endpoint) just by typing a natural-language prompt. No Postman, no curl cheat-sheets, no context-switching. If you've been looking for a way to work with APIs without writing traditional code, this is the most practical starting point.

What Are Claude Code Skills?

Skills are custom commands that extend what Claude Code can do. They live as markdown files inside a .claude/skills directory in your project. Each file contains natural-language instructions that Claude follows when you trigger the skill.

Think of them like lightweight plugins. You describe the task, the inputs Claude should expect, and the steps it should take. Claude reads the file and executes accordingly. There's no SDK to install and no build step. Just a text file and a clear set of instructions.

Skills can do all sorts of things: scaffold files, run shell commands, transform data, or, as we'll do here, call an external REST API and process the response.

Prerequisites

Before you start, make sure you have:

• Claude Code installed and working in your terminal. If you haven't set it up yet, follow Anthropic's official installation guide.
• A Carousel Studio account with an API key. You can grab a free key from the API docs page.
• A basic understanding of JSON. You'll need to read simple request and response objects. Nothing advanced.

That's it. You don't need Node.js, Python, or any other runtime. Claude Code handles execution directly.

Step 1: Get Your API Key from the Carousel Studio Dashboard

Log in to Carousel Studio and head to your dashboard. Click API Settings in the sidebar, then hit Generate New Key.

Copy the key and store it as an environment variable. Open your terminal and run:

export CAROUSEL_STUDIO_API_KEY="cs_live_your_key_here"

For persistence, add that line to your ~/.bashrc, ~/.zshrc, or .env file in your project root. If you use a .env file, make sure it's listed in your .gitignore so you don't accidentally commit your key.

Step 2: Create the Skill File Structure

Claude Code looks for skills in a .claude/skills directory relative to your project root. Create the folder if it doesn't exist:

mkdir -p .claude/skills

Now create a new file for your skill:

touch .claude/skills/generate-carousel.md

That's the entire structure. One folder, one file. Claude Code will automatically detect it the next time you start a session in this project.

Step 3: Write the Skill That Calls the Carousel Studio API

Open .claude/skills/generate-carousel.md in your editor and add the following:

# Generate Carousel

## Description
Generate a social-media carousel from a text prompt using the Carousel Studio API.

## Instructions

When the user asks you to generate a carousel, follow these steps:

1. Ask the user for their topic or paste text if they haven't provided it.
2. Use the Bash tool to make a POST request to the Carousel Studio API:

```bash
curl -s -X POST https://api.carouselstudio.app/v1/carousels/generate \
  -H "Authorization: Bearer $CAROUSEL_STUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "THE_USER_TEXT_HERE",
    "platform": "linkedin",
    "slideCount": 7,
    "style": "professional"
  }'
```

3. Parse the JSON response and present the carousel slides
   to the user in a readable format.
4. If the response contains a `downloadUrl`, share it with the user.
5. If the API returns an error, read the `message` field and
   explain the issue in plain language.

Notice how the instructions are just plain English. You're telling Claude what to do in the same way you'd explain the process to a colleague. The $CAROUSEL_STUDIO_API_KEY variable gets resolved from your environment at runtime, so the key never appears in the file itself.

If you want to learn more about turning plain text into visual content, check out our guide on turning text into a carousel.

Step 4: Test the Skill with a Sample Prompt

Open Claude Code in your project directory:

claude

Then type a prompt like:

Generate a carousel about 5 tips for better LinkedIn engagement

Claude will recognize the skill, call the Carousel Studio API, and return the generated slides. You should see a structured response with each slide's headline and body text, plus a download link if your plan includes image export.

If something goes wrong, Claude will surface the API error message directly. Common first-run issues are covered in the troubleshooting section below.

Step 5: Customize and Extend

The basic skill works, but you'll probably want more flexibility. Here are a few parameters you can make dynamic:

• Platform: Let the user specify linkedin, instagram, tiktok, or twitter so the output dimensions and tone adjust automatically.
• Slide count: Allow anything from 3 to 15 slides. Different platforms have different sweet spots.
• Style: Offer options like professional, casual, bold, or minimal to control the visual treatment.

Update your skill's instructions to extract these from the user's prompt:

## Instructions (updated)

When the user asks you to generate a carousel:

1. Identify the topic text from their message.
2. Check if they specified a platform (default: linkedin).
3. Check if they specified a slide count (default: 7).
4. Check if they specified a style (default: professional).
5. Make the API call with those parameters:

```bash
curl -s -X POST https://api.carouselstudio.app/v1/carousels/generate \
  -H "Authorization: Bearer $CAROUSEL_STUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "USER_TOPIC",
    "platform": "PLATFORM",
    "slideCount": SLIDE_COUNT,
    "style": "STYLE"
  }'
```

Now a prompt like "Generate a bold 10-slide Instagram carousel about morning routines" will just work. This kind of flexibility is what makes skills genuinely useful for automating your social media content with AI.

Troubleshooting Common Issues

401 Unauthorized

Your API key isn't being picked up. Double-check that CAROUSEL_STUDIO_API_KEY is exported in your current shell session. Run echo $CAROUSEL_STUDIO_API_KEY to verify it prints your key.

Claude doesn't find the skill

Make sure the .claude/skills directory is in your project root (the directory where you launch claude). The file must have a .md extension.

API returns a 400 Bad Request

This usually means the JSON body is malformed. Check that slideCount is a number (not a quoted string) and that platform is one of the supported values. See the full parameter list in the API docs.

Slow response times

Carousel generation involves image rendering, so responses can take 5-15 seconds depending on slide count. This is normal. If it takes longer than 30 seconds, check your network connection or the Carousel Studio status page.

Skill runs but output looks wrong

Refine the instructions in your .md file. Be more specific about how Claude should format the output. For example, tell it to display each slide as a numbered list with the headline in bold.

FAQ

What exactly is a Claude Code skill?

A Claude Code skill is a reusable set of instructions stored as a markdown file in your project's .claude/skills directory. When you invoke it, Claude follows those instructions to complete a specific task, like calling an API, generating files, or running a workflow. Think of it as a custom command you teach Claude.

Do I need to know a programming language to build a skill?

Not really. Skills are written in plain markdown with natural-language instructions. You do need a basic understanding of JSON (for API request and response bodies) and be comfortable using a terminal, but you won't be writing traditional code in Python or JavaScript.

Can I use this same approach with APIs other than Carousel Studio?

Absolutely. The pattern shown in this tutorial works with any REST API. You swap out the endpoint URL, headers, and request body to match whichever service you're integrating. The skill structure stays the same.

Is my API key safe inside a Claude Code skill?

Claude Code reads environment variables at runtime, so your key never has to be hardcoded in the skill file. Store it in a .env file (and add .env to your .gitignore) or export it in your shell profile. Claude will pick it up from the environment when the skill runs.