Simple Agent Demo

A minimal demonstration of an agent using the Claude Agent SDK with SKILL.md files, deployable to DigitalOcean.

What Are Agent Skills?

An agent skill is a markdown file (SKILL.md) that teaches an agent how to perform a specific task — entirely through natural language instructions. The agent follows those instructions when the skill is relevant.

Each skill lives in its own directory under .claude/skills/ and is automatically discovered at startup. When a user sends a message like "roll 3d6+4", the agent recognizes that the dice-roller skill is relevant, reads its instructions, and follows them to produce a result. Users can also invoke skills explicitly with slash commands (e.g., /calculator add 15 27).

Why use skills?

• Modular by design. Each skill is a self-contained file. Add a new capability by dropping in a new folder. Remove one by deleting it. Skills don't depend on each other or on application code.
• Context management. Context windows have expanded a lot, but as of the time of this writing they are still finite. Since skills are only invoked when needed, they help keep systems prompts small and manage system complexity. That way you can keep compute costs low and scale agent capabilities without linearly growing your base prompt size.
• Automatic invocation. The agent reads each skill's description field and decides on its own when to use it. You don't need to write routing logic or intent classifiers.

Features

• Web-based chat interface - Interactive UI to chat with the agent
• Simple HTTP API server
• Four example skills using the official SKILL.md format:
  • calculator - Perform arithmetic operations
  • dice-roller - Roll dice (1d20, 3d6+4, etc.)
  • unit-converter - Convert units (temperature, distance, weight, volume)
  • joke-generator - Tell jokes from various categories
• Health check endpoint
• Docker containerization
• DigitalOcean App Platform configuration

Prerequisites

• Node.js 18+
• Anthropic API key
• DigitalOcean account (for deployment)

Local Development

1. Install dependencies:

npm install

2. Copy environment file:

cp .env.example .env

3. Add your Anthropic API key to .env:

ANTHROPIC_API_KEY=sk-ant-...
PORT=3000

4. Start the server:

npm start

Or use watch mode for development:

npm run dev

5. Open your browser:

http://localhost:3000

You'll see a chat interface where you can interact with the agent using natural language.

Using the Web Interface

The web interface at http://localhost:3000 provides a clean chat UI to interact with the agent. Simply type your message and press Enter or click Send.

Try these example messages:

• "Tell me a programming joke"
• "What's 42 times 13?"
• "Roll 3d6+4 for me"
• "Convert 100 celsius to fahrenheit" The agent will automatically invoke the appropriate skill based on your request.

API Endpoints

GET /health

Health check endpoint.

Response:

{
  "status": "healthy",
  "timestamp": "2026-01-13T..."
}

GET /skills

List available skills.

Response:

{
  "skills": [
    {
      "name": "calculator",
      "description": "Perform basic arithmetic operations"
    },
    {
      "name": "dice-roller",
      "description": "Roll virtual dice in various combinations"
    },
    {
      "name": "unit-converter",
      "description": "Convert between different units of measurement"
    },
    {
      "name": "joke-generator",
      "description": "Generate jokes from various categories"
    }
  ]
}

POST /agent

Interact with the agent using natural language.

Request:

{
  "message": "Can you roll 3d6 for me?"
}

Request:

{
  "message": "What's 125 divided by 5?"
}

Request:

{
  "message": "Convert 100 celsius to fahrenheit"
}

Request:

{
  "message": "Tell me a programming joke"
}

Usage Examples

Using curl

# Health check
curl http://localhost:3000/health

# List skills
curl http://localhost:3000/skills

# Ask the agent to use a skill
curl -X POST http://localhost:3000/agent \
  -H "Content-Type: application/json" \
  -d '{"message":"What is 7 times 6?"}'

# Roll dice
curl -X POST http://localhost:3000/agent \
  -H "Content-Type: application/json" \
  -d '{"message":"Roll 2d20+5 for me"}'

# Convert units
curl -X POST http://localhost:3000/agent \
  -H "Content-Type: application/json" \
  -d '{"message":"Convert 5 miles to kilometers"}'

# Get a joke
curl -X POST http://localhost:3000/agent \
  -H "Content-Type: application/json" \
  -d '{"message":"Tell me a dad joke"}'

Deploy to DigitalOcean

Method 1: Using doctl CLI

1. Install doctl:

# macOS
brew install doctl

# Or download from https://docs.digitalocean.com/reference/doctl/how-to/install/

2. Authenticate:

doctl auth init

3. Create the app:

doctl apps create --spec .do/app.yaml

4. Set your API key as a secret:

doctl apps create-deployment YOUR_APP_ID --app-spec .do/app.yaml

Then add the secret via the DigitalOcean dashboard:

• Go to your app settings
• Navigate to "Environment Variables"
• Add ANTHROPIC_API_KEY with your API key value

Method 2: Using GitHub + DigitalOcean Dashboard

1. Push this code to a GitHub repository:

git init
git add .
git commit -m "Initial commit"
git remote add origin YOUR_REPO_URL
git push -u origin main

2. Go to DigitalOcean App Platform

3. Click "Create App"

4. Connect your GitHub repository

5. Configure the app:

   • Set the Dockerfile path: Dockerfile
   • Set HTTP port: 3000
   • Add environment variable: ANTHROPIC_API_KEY (as secret)

6. Click "Next" and then "Create Resources"

Method 3: Using Docker Hub

1. Build and push the Docker image:

docker build -t your-username/simple-agent-demo .
docker push your-username/simple-agent-demo

2. In DigitalOcean, create an app using the Docker Hub image

3. Set environment variables in the DigitalOcean dashboard

Testing the Deployed App

Once deployed, DigitalOcean will provide you with a URL (e.g., https://your-app.ondigitalocean.app).

Web Interface: Simply open the URL in your browser to use the chat interface.

API Testing:

# Replace with your actual URL
export APP_URL=https://your-app.ondigitalocean.app

# Health check
curl $APP_URL/health

# Test agent endpoint
curl -X POST $APP_URL/agent \
  -H "Content-Type: application/json" \
  -d '{"message":"What is 15 plus 27?"}'

Project Structure

simple-agent-demo/
├── public/
│   └── index.html        # Web chat interface
├── .claude/
│   └── skills/           # Skills directory (Claude Code format)
│       ├── calculator/
│       │   └── SKILL.md
│       ├── dice-roller/
│       │   └── SKILL.md
│       ├── unit-converter/
│       │   └── SKILL.md
│       └── joke-generator/
│           └── SKILL.md
├── .do/
│   └── app.yaml          # DigitalOcean App Platform config
├── src/
│   └── index.js          # Main application
├── .env.example          # Environment template
├── .gitignore
├── Dockerfile            # Docker configuration
├── package.json
└── README.md

Adding New Skills

Skills use the official Claude Code SKILL.md format. Create a new directory in .claude/skills/ with a SKILL.md file:

---
name: my-skill
description: Brief description of what this skill does and when to use it. Claude uses this to decide when to apply the skill automatically.
argument-hint: <arg1> <arg2>
---

When this skill is invoked with $ARGUMENTS:

1. Parse the arguments
2. Perform the operation
3. Return the result in a clear format

## Examples

\```
User: /my-skill hello
Result: Processed 'hello'
\```

YAML Frontmatter Fields

• name - The skill name (becomes the /slash-command)
• description - What the skill does and when to use it (helps Claude decide when to auto-invoke)
• argument-hint - Hint for expected arguments (e.g., <filename> or [optional-arg])
• disable-model-invocation - Set to true to prevent auto-invocation
• user-invocable - Set to false to hide from the / menu

String Substitutions

• $ARGUMENTS - All arguments passed when invoking the skill
• ${CLAUDE_SESSION_ID} - The current session ID

The skill will be automatically discovered by Claude Code when the agent starts.

For more information on the SKILL.md format, see: https://code.claude.com/docs/en/skills

Cost Estimation

DigitalOcean App Platform pricing:

• Basic XXS: $5/month (512 MB RAM, 1 vCPU)
• Includes 100 GB bandwidth

Note: You'll also incur Anthropic API usage costs based on your usage.

License

MIT