Agent Skills with Claude Code SKILL.md

What is SKILL.md

A SKILL.md file is how Claude Code understands and executes a skill. It lives in .claude/skills/<skill-name>/ and combines YAML metadata in the frontmatter with procedural markdown instructions.

Note

Important difference from Python/ADK: In Python and ADK, skills are Layer 2 — architectural constraints. In Claude Code they are Layer 1 — instructions that guide reasoning. Claude can ignore them, although in practice it doesn’t when instructions are clear.

Folder structure

• Directory.claude/

  • Directoryskills/

    • Directorydns-management/

      • SKILL.md
      • Directoryreferences/

        • cloudflare-api-guide.md
      • Directoryscripts/

        • validate_record.py

• SKILL.md — skill definition: frontmatter + instructions
• references/ — supporting documentation that Claude reads as context
• scripts/ — auxiliary scripts that Claude can execute with Bash

SKILL.md frontmatter

---
name: dns-management
description: "Manages DNS records via Cloudflare API for the configured domain"
allowed-tools: Bash(curl *) Bash(python *) Read
---

Field	Description
name	Unique skill identifier
description	What it does — Claude uses this to decide when to invoke the skill
allowed-tools	Claude Code tools the skill can use

allowed-tools restricts what Claude can execute when using this skill. In this case it can only run curl or Python scripts — it cannot use Write, Edit or other filesystem operations.

SKILL.md content

The body of the file is procedural markdown instructions:

## Required environment variables

- CLOUDFLARE_API_TOKEN
- CLOUDFLARE_ZONE_ID
- CLOUDFLARE_DOMAIN

## Recommended flow

Before creating or modifying a record, always:
1. List existing records to check for duplicates
2. Execute the operation
3. Validate that the record resolves correctly

## Allowed record types

Only: A, CNAME, MX, TXT
Do not create: NS, SOA, SRV — they can break the DNS zone

## Available operations

- **List:** GET /zones/{zone_id}/dns_records
- **Create:** POST /zones/{zone_id}/dns_records
- **Find:** GET with filter ?name=&type=
- **Update:** PUT /zones/{zone_id}/dns_records/{record_id}
- **Validate:** python scripts/validate_record.py <domain> <expected_ip>

Auxiliary script: validate_record.py

Validates that a DNS record resolves to the expected value. Claude invokes it with Bash:

#!/usr/bin/env python3
"""Validates that a DNS record resolves to the expected value."""

def validate(domain: str, expected_ip: str) -> bool:
    import socket
    resolved = socket.gethostbyname(domain)
    return resolved == expected_ip

# Claude runs this internally
python .claude/skills/dns-management/scripts/validate_record.py \
  api.yourdomain.com 203.0.113.50

Reference: cloudflare-api-guide.md

Quick reference for Cloudflare endpoints that Claude reads as context when working with the skill:

## Authentication
Authorization: Bearer {CLOUDFLARE_API_TOKEN}

## Main endpoints
GET  /zones/{zone_id}/dns_records
POST /zones/{zone_id}/dns_records
PUT  /zones/{zone_id}/dns_records/{record_id}

## Response format
{ "result": [{ "id": "...", "type": "A", "name": "api", "content": "1.2.3.4" }] }

How to use it in Claude Code

1. Copy the folder to the project where you want to use it:

   cp -r .claude/ /your/project/.claude/

2. Open Claude Code in that directory. Claude will automatically detect the skills in .claude/skills/.

3. Invoke the skill with natural language:

   > Create the subdomain staging.yourdomain.com pointing to 10.0.0.5
   > List all current DNS records
   > Migrate mail.yourdomain.com to IP 5.6.7.8

Difference from Python/ADK

	Python / ADK	Claude Code (SKILL.md)
Constraint type	Layer 2 — architectural	Layer 1 — instructions
delete impossible?	Yes — the function doesn’t exist	No — Claude could run curl DELETE if it wanted
Requires Python code	Yes	No — Claude runs curl directly
Best for	Production, critical systems	Development, infrastructure tasks with supervision