Creating Custom Skills for Financial Modeling with Claude: A Complete Developer Guide

Claude Skills enable developers to package domain-specific instructions, executable scripts, and Excel templates into modular capabilities that Claude discovers and invokes on demand to automate complex financial modeling workflows through the Anthropic API.

Claude Skills provide a structured way to extend Claude's capabilities for financial modeling automation by bundling metadata, Python logic, and resource files into version-controlled modules. According to the anthropics/claude-cookbooks repository, these custom skills integrate with the code execution tool to generate professional DCF valuations, ratio analyses, and sensitivity tables in Excel format. This guide demonstrates how to architect, upload, and invoke a custom financial modeling skill using the official Skills beta API.

Understanding Claude Skills Architecture

A Claude Skill is a self-contained directory that packages instructions, reusable scripts, and supporting assets into a single module. For financial modeling applications, this architecture enables you to bundle domain-specific valuation logic, template workbooks, and calculation validators into one uploadable unit.

The required file structure follows this convention:

• SKILL.md (Required): Contains YAML front-matter with metadata (name, description) and high-level instructions. Must remain under 5,000 tokens to keep discovery efficient.
• scripts/ (Optional): Executable Python or JavaScript files that Claude calls via the code execution tool for deterministic calculations.
• resources/ (Optional): Static assets such as Excel templates, PowerPoint decks, or benchmark data files fetched only when needed.

As implemented in skills/notebooks/03_skills_custom_development.ipynb, Claude loads only the lightweight SKILL.md front-matter during initial discovery. The full instruction set and ancillary files are fetched lazily when the user requests specific financial calculations, minimizing token usage while delivering fully-featured modeling capabilities.

Setting Up the Skills Beta Client

To create and manage custom skills, initialize the Anthropic client with the Skills beta header. This configuration is demonstrated in the "Initialize the client" cell (lines 71-85) of the custom development notebook.

from anthropic import Anthropic
from dotenv import load_dotenv
import os
from pathlib import Path

load_dotenv(Path.cwd().parent / ".env")
client = Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY"),
    default_headers={"anthropic-beta": "skills-2025-10-02"},
)

The skills-2025-10-02 beta flag enables access to the client.beta.skills namespace for upload and version management operations.

Creating and Uploading a Financial Modeling Skill

Define a helper utility to package your skill directory and upload it to Claude's infrastructure. The create_skill function referenced in the notebook (lines 48-66) handles directory traversal and API submission.

def create_skill(client, skill_path, display_title):
    # Assumes files_from_dir() helper collects all files in skill_path

    skill = client.beta.skills.create(
        display_title=display_title, 
        files=files_from_dir(skill_path)
    )
    return {"skill_id": skill.id, "version": skill.latest_version}

# Upload the Financial Modeling Suite

modeling_path = Path("custom_skills/creating-financial-models")
result = create_skill(client, str(modeling_path), "Financial Modeling Suite")
modeling_skill_id = result["skill_id"]

This operation corresponds to the "Upload the Financial Modeling Suite skill" cell (lines 99-107) in 03_skills_custom_development.ipynb. Upon successful creation, the API returns a unique skill_id and initial version number required for subsequent invocations.

Invoking Custom Skills via the Messages API

Once uploaded, invoke your financial modeling skill by referencing it in the container parameter of the Messages API, alongside built-in Anthropic skills like xlsx for Excel generation.

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "custom", "skill_id": modeling_skill_id, "version": "latest"},
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
        ]
    },
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    messages=[{"role": "user", "content": dcf_prompt}],
    betas=["code-execution-2025-08-25", "files-api-2025-04-14", "skills-2025-10-02"],
)

The container.skills array tells Claude which capabilities to load for this specific request. The code_execution tool runs Python scripts contained in your skill's scripts/ directory, while the files-api-2025-04-14 beta enables downloadable output files. As shown in the "Test the Financial Modeling Suite with DCF valuation" cell (lines 71-86), the response contains both textual analysis and file IDs for generated Excel models.

Versioning and Updating Skills

Skills are immutable once created. To iterate on your financial modeling logic—such as adding healthcare sector benchmarks or updating valuation formulas—you must create a new version rather than modifying the existing skill.

def create_skill_version(client, skill_id, skill_path):
    version = client.beta.skills.versions.create(
        skill_id=skill_id, 
        files=files_from_dir(skill_path)
    )
    return {"new_version": version.version}

# Example: Enhance the Financial Ratio Analyzer with new benchmarks

create_skill_version(client, modeling_skill_id, "custom_skills/creating-financial-models")

This versioning strategy, detailed in the "Create a new version" cell (lines 84-92), enables Git-like lifecycle management where each change is a distinct version, supporting rollbacks and A/B testing of financial model templates.

End-to-End Example: Automated DCF Valuation

The following implementation combines upload, prompting, and file extraction into a complete workflow for generating a discounted cash flow model. This example adapts code from the notebook's "Sample End-to-End Workflow" section (lines 30-38, 71-86, and 140-162 references).

# 1. Upload the skill

modeling_result = create_skill(
    client, 
    "custom_skills/creating-financial-models",
    "Financial Modeling Suite"
)
modeling_id = modeling_result["skill_id"]

# 2. Build a DCF valuation prompt

dcf_prompt = """
Perform a DCF valuation for TechCorp using the following data:
- Revenue: $500M, $600M, $750M (last 3 years)
- EBITDA margin: 25%, 27%, 30%
- CapEx: $50M, $55M, $60M
- Working-capital %: 15% of revenue
- Forecast revenue growth: 20% Y1-Y3, then 5% by Y5
- Terminal growth: 3%
- WACC: 10%

Generate an Excel workbook with revenue projections, free-cash-flow calculations,
terminal value, and a sensitivity table for WACC & terminal growth.
"""

# 3. Invoke Claude with the skill container

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "custom", "skill_id": modeling_id, "version": "latest"},
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
        ]
    },
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    messages=[{"role": "user", "content": dcf_prompt}],
    betas=["code-execution-2025-08-25", "files-api-2025-04-14", "skills-2025-10-02"],
)

# 4. Extract and download the generated Excel file

# Assumes download_all_files utility from tool_use/memory_demo/*.py

file_ids = [c.id for c in response.content if c.type == "tool_use"]
download_all_files(client, response, output_dir="outputs", prefix="dcf_")

This workflow produces a complete financial model with calculated projections and sensitivity analysis, downloadable as an .xlsx file via the Files API.

Best Practices for Production Financial Modeling

When deploying custom Claude skills for financial applications, adhere to these guidelines derived from the "Best Practices & Production Tips" section (lines 140-162) of the notebook:

• Limit SKILL.md to ≤ 5k tokens to minimize discovery costs and latency.
• Separate heavy assets (large Excel templates, historical datasets) into resources/ rather than embedding them in instructions.
• Unit-test scripts locally before upload—validate calculation accuracy in scripts/valuation.py outside of Claude first.
• Never embed API keys or PII in skill files; rely on workspace environment variables passed to the execution environment.
• Use code_execution for deterministic math rather than LLM-only reasoning to ensure precise financial calculations.
• Version control with Git before creating new skill versions to maintain audit trails of financial methodology changes.

Summary

Creating custom Claude skills for financial modeling involves packaging domain logic into a structured directory with SKILL.md, uploading via the client.beta.skills.create API, and invoking through the Messages API container system. Key takeaways include:

• Claude Skills use a lazy-loading architecture where only metadata is fetched initially, keeping token usage low until specific financial calculations are requested.
• The skills-2025-10-02 beta header enables the client.beta.skills namespace for upload and version management.
• Skills are immutable; use client.beta.skills.versions.create to iterate on valuation methodologies without breaking existing integrations.
• Integration with the xlsx built-in skill and code_execution tool enables automated generation of professional Excel financial models.
• Maintain strict separation of sensitive credentials from skill files, using environment variables for API keys and financial data sources.

Frequently Asked Questions

What files are required to create a custom Claude skill?

The only mandatory file is SKILL.md, which contains YAML front-matter (name and description) and high-level instructions. Optional directories include scripts/ for executable Python code, resources/ for Excel templates or data files, and additional .md files for documentation. All optional files are loaded only when referenced by the skill's instructions.

How do I update a financial modeling skill after uploading it?

Skills are immutable once created. To update valuation logic or add new industry benchmarks, use client.beta.skills.versions.create() with the existing skill_id and updated directory contents. This creates a new version number while preserving the old one, enabling you to test changes before switching downstream applications to the latest version.

What are the token limits for Claude Skills?

The SKILL.md file must stay under 5,000 tokens to ensure efficient discovery. This limit applies only to the metadata and instructions file; scripts and resources in other directories do not count toward this limit as they are fetched lazily only when explicitly invoked by the user or skill logic.

Can Claude skills generate downloadable Excel files for financial models?

Yes. By combining a custom skill with the built-in xlsx skill ({"type": "anthropic", "skill_id": "xlsx", "version": "latest"}) and enabling the files-api-2025-04-14 beta, Claude can generate Excel workbooks with formulas, sensitivity tables, and charts. The response includes file IDs that you can download using the Files API or helper utilities from the tool_use/memory_demo directory in the anthropics/claude-cookbooks repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}