From Claude Code Setup to Your First Agent Skill

Wilbur — Tue, 26 May 2026 09:12:46 +0000

Why Agent Skills are worth learning

Agent Skills are easy to misunderstand at first. They are not a new model, a plugin marketplace, or a magic prompt format.

In Claude Code, a Skill is a reusable capability package: a folder that contains instructions, optional scripts, optional references, and optional assets. Claude Code can discover that folder and load the right instructions when your task matches the Skill description.

That makes Skills useful for work you repeat often:

writing API docs in a specific format
reviewing pull requests against team rules
generating release notes
transforming internal notes into publishable posts
running a script-heavy workflow with the right guardrails

Instead of rewriting the same prompt every week, you turn it into a small engineering artifact.

This guide walks through a practical setup: choose an AI coding IDE, install Claude Code, optionally configure a provider switcher, verify the CLI, and create your first Skill.

The setup at a glance

Step	Tool	Purpose
1	IDE with terminal	Run commands and work with code
2	Claude Code	The agentic CLI that can use Skills
3	Provider switcher, optional	Route Claude Code through a supported provider or gateway
4	Fresh terminal session	Ensure environment changes are loaded
5	Claude Code test	Confirm the CLI can respond
6	Agent Skill	Package a repeatable workflow

The exact provider setup depends on your region, organization, and account. The Skill concept stays the same.

1. Choose an IDE with a real terminal

You can use any developer environment that gives you a terminal and access to your project files.

Good options include:

VS Code
Cursor
Trae
Google Antigravity
a plain terminal plus your preferred editor

Google describes Antigravity as an agent-first development environment, so it can be a comfortable place to run AI coding workflows. But it is not required for Skills. Claude Code works from the terminal, so the IDE is mostly there to make editing, chatting, and command execution easier.

For this workflow, keep one practical habit: after changing provider or environment settings, open a new terminal before testing claude.

2. Install Claude Code

The current Claude Code documentation lists native installers for macOS, Linux, WSL, Windows PowerShell, and Windows CMD.

For macOS, Linux, or WSL:

curl -fsSL https://claude.ai/install.sh | bash

For Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

For Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

After installation, open a new terminal and verify the CLI:

claude --version

If Windows cannot find the claude command, the most common cause is that the terminal has not picked up the updated PATH. Close the terminal, open a new one, and try again.

If it still fails, check whether Claude Code's binary directory is on your PATH.

3. Decide how Claude Code should reach the model provider

If you use Claude Code with Anthropic directly, follow the normal Claude Code authentication flow.

If your network, organization, or region requires an Anthropic-compatible gateway, a provider switcher can help you avoid manually editing environment variables and config files.

One open-source option is CC-Switch, a desktop tool that manages providers for Claude Code and other AI coding CLIs. Treat it as a third-party tool: check the current release notes, download from the official GitHub repository, and review what it changes before using it in a work environment.

A typical custom provider setup looks like this:

Provider type: Anthropic-compatible
Base URL: https://your-gateway.example.com
API key: sk-your-provider-key

If you are using ClaudeAPI as the gateway, replace the placeholder base URL and key with the values from your ClaudeAPI console. Avoid hardcoding API keys in project files.

4. Apply the provider configuration

The exact CC-Switch UI can change between releases, but the flow is usually:

Install CC-Switch from its GitHub Releases page.
Add or confirm a Claude Code provider profile.
Add your Anthropic-compatible gateway provider.
Select or enable that provider for Claude Code.
Open a new terminal in your IDE.

That last step matters. Existing terminals often keep the old environment. If you configured a provider and then reused an old terminal, Claude Code may still behave as if nothing changed.

Now start Claude Code:

claude

A successful launch should take you into the Claude Code interface. If it sends you into an unexpected login flow, the provider settings probably did not reach the terminal session. Recheck the selected provider and start a new terminal.

5. Run a tiny end-to-end test

Inside Claude Code, ask for something simple:

Write the smallest possible Python hello world.

You are not testing coding ability here. You are testing the full path:

IDE terminal -> Claude Code -> provider configuration -> model response

Once that works, you can move on to Skills.

6. Create your first Agent Skill

According to the official Claude Code Skills documentation, a Skill can live in a personal folder or inside a project.

A personal Skill is available across projects:

~/.claude/skills/<skill-name>/SKILL.md

A project Skill lives with one repository:

.claude/skills/<skill-name>/SKILL.md

A minimal Skill only needs one file: SKILL.md.

Here is a small Skill for writing API endpoint documentation.

Create the folder:

mkdir -p ~/.claude/skills/api-doc-writer

On Windows PowerShell:

New-Item -ItemType Directory -Force "$HOME\.claude\skills\api-doc-writer"

Then create SKILL.md:

---
name: api-doc-writer
description: Write clear API endpoint documentation. Use when the user asks for REST API docs, endpoint specs, request/response examples, parameter tables, or error code documentation.
---

# API Doc Writer

## Instructions

Write concise developer-facing API documentation.

Always include:

1. Endpoint summary
2. HTTP method and path
3. Authentication requirements
4. Request parameters
5. Example request
6. Example response
7. Error responses
8. Notes about edge cases or rate limits when known

Use Markdown tables for parameters and errors. Use fenced code blocks with language identifiers for JSON examples. Do not invent fields that were not provided by the user.

Now restart or refresh Claude Code if needed, then test the Skill:

/api-doc-writer Write docs for GET /users. It supports page, limit, and role query parameters. It returns id, name, email, and role.

A good result should look like structured API documentation, not a generic explanation.

What makes a Skill reliable?

The most important part of a Skill is the description. Claude Code uses it to decide when the Skill is relevant.

Weak description:

Helps with docs.

Better description:

Write clear API endpoint documentation. Use when the user asks for REST API docs, endpoint specs, request/response examples, parameter tables, or error code documentation.

Good Skills also separate concerns:

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

Use scripts/ when the workflow needs repeatable code. Use references/ for detailed rules, schemas, examples, or style guides. Use assets/ for templates, images, config examples, or files that the Skill should reuse.

Do not put everything into one giant instruction file. Keep SKILL.md focused on when to use the Skill and what workflow to follow.

Common setup issues

Symptom	Likely cause	Fix
`claude: command not found`	Terminal did not pick up `PATH`	Open a new terminal and check the install path
Claude Code asks for an unexpected login	Provider settings did not apply	Recheck provider selection and start a new terminal
API key returns 401	Wrong key or wrong provider profile	Regenerate or reselect the key
API key returns 403	Account, group, or permission issue	Check provider dashboard permissions
Skill does not activate	Description is too vague	Rewrite the description with concrete trigger phrases
Skill activates but ignores your format	Instructions are too loose	Use ordered steps and required output sections

A note on provider gateways

A gateway such as ClaudeAPI should be treated as infrastructure, not as the main point of the tutorial. The developer value comes from understanding how Claude Code and Skills work.

If you mention a provider in a public article, be precise:

say whether it is official or third-party
avoid implying affiliation with Anthropic unless documented
avoid stale model, pricing, or latency claims
link to current provider docs instead of hardcoding promises

That keeps the article useful even when provider details change.

Where to go next

Once the first Skill works, build one for a task you already repeat.

Good candidates:

a code review checklist for your stack
a bug report triage format
an API documentation generator
a changelog writer
a migration guide assistant
a blog post rewriter with publication rules

The goal is not to collect Skills. The goal is to turn repeated instructions into small, inspectable tools that make your day-to-day development work easier to repeat.

DEV Community: Wilbur