DEV Community

Cover image for From Claude Code Setup to Your First Agent Skill
Wilbur
Wilbur

Posted on

From Claude Code Setup to Your First Agent Skill

#webdev #programming #ai #devops

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
Enter fullscreen mode Exit fullscreen mode

For Windows PowerShell:

irm https://claude.ai/install.ps1 | iex
Enter fullscreen mode Exit fullscreen mode

For Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Enter fullscreen mode Exit fullscreen mode

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

claude --version
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

  1. Install CC-Switch from its GitHub Releases page.
  2. Add or confirm a Claude Code provider profile.
  3. Add your Anthropic-compatible gateway provider.
  4. Select or enable that provider for Claude Code.
  5. 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
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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

IDE terminal -> Claude Code -> provider configuration -> model response
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

A project Skill lives with one repository:

.claude/skills/<skill-name>/SKILL.md
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

On Windows PowerShell:

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

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.
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

Good Skills also separate concerns:

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)