gh-jgardner04-skills-jgardner04-skills/skills/skill-creator/reference/platform-differences.md

Platform-Specific Guidance for Claude Skills

Understanding the differences between Claude surfaces to create skills that work everywhere.

Overview

Claude skills can run on three different surfaces:

1. Claude.ai - Web interface and mobile apps
2. Claude API - Programmatic access for developers
3. Claude Code - CLI tool for development workflows

Each platform has different capabilities, constraints, and runtime environments. This guide helps you create skills that work effectively across all platforms or target specific ones.

Quick Comparison

Feature	Claude.ai	Claude API	Claude Code
Skill Scope	User-specific	Workspace-wide	Project or user
Network Access	Variable (admin settings)	No (by default)	Yes (full access)
File System	Limited (uploads only)	Limited	Full access
Package Installation	No	No	Yes (with permissions)
Bash Commands	No	Limited (sandboxed)	Yes (full shell)
Best For	Personal productivity	Programmatic workflows	Development tasks

Claude.ai

Overview

Web-based interface with mobile app support. Skills help individual users with their work.

Characteristics

Skill Scope: User-specific only

• Each user uploads their own skills
• Skills are not shared across workspace
• No way to distribute org-wide skills
• Good for personal productivity

Network Access: Variable

• Depends on user settings
• Depends on admin/organization policies
• Can be restricted by IT
• Skills should handle network unavailability gracefully

File System Access: Upload-based

• Users upload files through the UI
• Skills can read uploaded files
• Skills can generate downloadable files
• No direct file system access

Tool Availability:

• ✅ Read (uploaded files)
• ✅ Write (generate downloads)
• ⚠️ WebFetch (if network allowed)
• ⚠️ WebSearch (if network allowed)
• ❌ Bash (no shell access)
• ❌ Git operations

Best Practices for Claude.ai

Make Network Access Optional

## Using the API (Optional)

If you have network access enabled, this skill can fetch live data.
Otherwise, you can upload data files directly.

Provide Upload Instructions

## Setup

1. Download the template from [link]
2. Fill in your data
3. Upload the file to Claude
4. Use this skill to process it

Handle Missing Dependencies

## Note

This skill works best with network access. If network is disabled,
you can still use the basic features by providing data manually.

Use Read/Write Effectively

• Generate files users can download
• Process uploaded CSV, JSON, Markdown
• Create reports, summaries, visualizations (as text/markdown)

Example: Claude.ai-Friendly Skill

---
name: meeting-notes-formatter
description: Format raw meeting notes into structured summaries with action items. Works with uploaded text files or pasted content.
tools: Read, Write
---

# Meeting Notes Formatter

Formats meeting notes into professional summaries.

## How to Use

**Option 1: Upload a file**
1. Save your meeting notes as a .txt or .md file
2. Upload to Claude
3. Ask me to format it: "Format the meeting notes"

**Option 2: Paste directly**
1. Copy your meeting notes
2. Paste into the chat
3. Ask me to format it

## What You'll Get

- Executive summary
- Key discussion points
- Action items with owners
- Decisions made
- Follow-up topics

No network access required!

Claude API

Overview

Programmatic access for developers to integrate Claude into applications and workflows.

Characteristics

Skill Scope: Workspace-wide

• Skills are available to all workspace members
• Configured at the organization level
• Shared across all API calls in the workspace
• Centralized management

Network Access: None by default

• No outbound network requests
• No API calls to external services
• Skills must work offline
• Security-focused design

Dependency Management: Pre-configured only

• No dynamic package installation
• Dependencies must be pre-installed in the runtime
• Limited to standard library + pre-approved packages
• Skills cannot require new dependencies

Execution Environment: Sandboxed

• Controlled execution environment
• Limited file system access
• Security restrictions
• Predictable, reproducible behavior

Tool Availability:

• ✅ Read (from provided context)
• ✅ Write (to return data)
• ⚠️ Bash (sandboxed, limited commands)
• ❌ WebFetch (no network)
• ❌ WebSearch (no network)
• ❌ Package installation

Best Practices for Claude API

Design for Offline Operation

# ❌ Bad: Requires network
def fetch_user_data(user_id):
    response = requests.get(f"https://api.example.com/users/{user_id}")
    return response.json()

# ✅ Good: Works with provided data
def process_user_data(user_data: dict) -> dict:
    """Process user data provided by the caller."""
    return {
        "summary": generate_summary(user_data),
        "insights": extract_insights(user_data),
    }

Use Only Standard Library

# ✅ Good: Standard library only
import json
import re
from datetime import datetime
from pathlib import Path
from typing import Dict, List

# ❌ Bad: External dependency
import pandas as pd  # Not available unless pre-installed

Document Data Requirements

## API Integration

This skill requires the following data to be provided:

### Input Format
```json
{
  "users": [...],
  "events": [...],
  "config": {...}
}

Output Format

{
  "report": "...",
  "metrics": {...},
  "recommendations": [...]
}

#### Provide Clear Error Messages
```python
def validate_input(data: dict) -> tuple[bool, str]:
    """Validate input data structure."""
    if "users" not in data:
        return False, "Missing required field: 'users'"
    if not isinstance(data["users"], list):
        return False, "Field 'users' must be a list"
    return True, ""

Example: API-Optimized Skill

---
name: data-transformer
description: Transform and validate JSON data structures. Requires data to be provided via API call. Works entirely offline with no external dependencies.
tools: Read, Write
model: haiku
---

# Data Transformer

Transforms JSON data according to specified rules.

## API Usage

```python
import anthropic

client = anthropic.Anthropic()

# Provide data in the API call
message = client.messages.create(
    model="claude-3-sonnet-20240229",
    messages=[{
        "role": "user",
        "content": f"Transform this data: {json.dumps(data)}"
    }]
)

Input Requirements

The skill expects JSON data in this format:

{
  "data": [...],
  "rules": {...}
}

Output

Returns transformed data:

{
  "transformed": [...],
  "errors": [],
  "stats": {...}
}

No Dependencies

Uses only Python standard library - no external packages required.

## Claude Code

### Overview
CLI tool for development workflows with full system access.

### Characteristics

**Skill Scope**: Flexible
- Project-level: `.claude/skills/` (shared with team via git)
- User-level: `~/.claude/agents/` (personal)
- Plugin-level: `.claude-plugin/` (distributable)

**Network Access**: Full
- Unrestricted outbound requests
- Can call APIs
- Can fetch web pages
- Can download resources

**File System Access**: Full
- Read any accessible file
- Write to any writable location
- Execute commands
- Full git integration

**Package Installation**: Available
- Can install Python packages (pip)
- Can install npm packages
- Can use system package managers
- Can compile code

**Tool Availability**:
- ✅ All tools available
- ✅ Bash (full shell access)
- ✅ WebFetch
- ✅ WebSearch
- ✅ Git operations
- ✅ Read/Write/Edit
- ✅ Task (subagents)

### Best Practices for Claude Code

#### Leverage Full Capabilities
```yaml
---
name: api-tester
description: Test REST APIs with automatic request generation and validation. Use when developing or debugging API endpoints.
tools: Bash, Read, Write, WebFetch
---

# API Tester

Tests REST APIs with comprehensive validation.

## Features

- Automatic request generation
- Response validation
- Performance metrics
- Error handling tests
- OpenAPI spec generation

## Requirements

```bash
pip install requests pyyaml jsonschema

Usage

Just tell me the API endpoint to test!

#### Use Project Configuration
```markdown
## Setup

Add to `.claude/settings.json`:

```json
{
  "env": {
    "API_KEY": "${YOUR_API_KEY}",
    "API_URL": "https://api.example.com"
  }
}

The skill will read these values automatically.

#### Integrate with Development Tools
```bash
# Run linters
black your_script.py
pylint your_script.py

# Run tests
pytest tests/

# Build project
npm run build

Create Complex Workflows

## Workflow

1. Fetch latest data from API
2. Validate against schema
3. Transform and process
4. Update local files
5. Generate report
6. Commit changes to git

Example: Claude Code-Optimized Skill

---
name: github-issue-helper
description: Manage GitHub issues - create, update, search, and analyze issues using gh CLI. Use when working with GitHub repositories in development.
tools: Bash, Read, Write, Edit, Grep
---

# GitHub Issue Helper

Comprehensive GitHub issue management using gh CLI.

## Requirements

```bash
# Install GitHub CLI
brew install gh  # macOS
# OR
apt install gh   # Linux

# Authenticate
gh auth login

Features

• Create issues: From templates or scratch
• Search issues: By label, state, author
• Bulk operations: Close, label, assign multiple issues
• Analysis: Generate reports, find patterns
• Integration: Link to commits, PRs, projects

Commands

• "Create an issue for the bug in API endpoint"
• "Find all P0 issues assigned to me"
• "Close all issues labeled 'wontfix'"
• "Generate a weekly issue summary"

Setup

No additional setup required if gh CLI is authenticated.

## Cross-Platform Skills

### Design Principles

To create skills that work across all platforms:

#### 1. Progressive Enhancement

Start with core functionality that works everywhere, add platform-specific features as available.

```markdown
## Core Features (All Platforms)
- Process uploaded/provided data
- Generate formatted output
- Validate inputs

## Enhanced Features (Claude Code Only)
- Fetch live data from APIs
- Update local files automatically
- Integrate with git workflow

2. Graceful Degradation

Handle missing capabilities elegantly:

## Setup

### Claude.ai / API
Upload your data file (CSV, JSON, or TXT)

### Claude Code
I can fetch data directly from your database or API.
Tell me the connection details.

3. Platform Detection

Guide users based on their platform:

## Platform Notes

**Claude.ai**: Upload files via the interface
**Claude API**: Provide data in the API request body
**Claude Code**: I can read files directly from your project

4. Minimal Dependencies

Use standard library when possible:

# ✅ Works everywhere
import json
from pathlib import Path

# ⚠️  Works in Claude Code only
import requests
import pandas

Example: Universal Skill

---
name: json-validator
description: Validate and format JSON data against schemas. Works with uploaded files, pasted data, or local files depending on platform.
tools: Read, Write
---

# JSON Validator

Validates JSON against schemas with detailed error reports.

## How to Use

**Claude.ai**:
1. Upload your JSON file
2. Upload your schema file (optional)
3. Ask: "Validate the JSON"

**Claude API**:
```python
message = client.messages.create(
    messages=[{
        "role": "user",
        "content": f"Validate this JSON:\n{json_data}\n\nSchema:\n{schema}"
    }]
)

Claude Code:

Validate JSON files in ./data/

Features

• ✅ Schema validation (all platforms)
• ✅ Format checking (all platforms)
• ✅ Error highlighting (all platforms)
• ⚠️ Auto-fix suggestions (Claude Code only)
• ⚠️ Batch processing (Claude Code only)

No external dependencies required!

## Testing Across Platforms

### Test Checklist

- [ ] Test on Claude.ai (web interface)
- [ ] Test via Claude API (programmatic access)
- [ ] Test in Claude Code (CLI)
- [ ] Test with network disabled (API mode)
- [ ] Test with file uploads (Claude.ai mode)
- [ ] Test with local files (Claude Code mode)
- [ ] Verify error messages are clear on all platforms
- [ ] Check that platform-specific features degrade gracefully

### Platform-Specific Test Cases

**Claude.ai**:
- Upload various file formats
- Test with network restrictions
- Verify download generation works
- Test on mobile if applicable

**Claude API**:
- Test with no network access
- Verify offline operation
- Test with standard library only
- Check API response format

**Claude Code**:
- Test with project files
- Test bash commands
- Test package installation instructions
- Verify git integration

## Summary

### Choose Your Target

**Claude.ai**: Best for personal productivity skills that process documents
**Claude API**: Best for deterministic, offline data processing
**Claude Code**: Best for development workflows with full system access

### Design Patterns

**Single Platform**: Optimize for that platform's strengths
**Multi-Platform**: Use progressive enhancement and graceful degradation
**Universal**: Stick to core capabilities, document platform differences

### Key Takeaways

1. **Know your constraints**: Each platform has different capabilities
2. **Design accordingly**: Match skill design to platform capabilities
3. **Document clearly**: Tell users what works where
4. **Test thoroughly**: Verify on all target platforms
5. **Handle gracefully**: Degrade features when capabilities are missing

## Resources

- **Claude.ai**: https://claude.ai/skills
- **Claude API**: https://docs.anthropic.com/claude/docs/
- **Claude Code**: https://docs.claude.com/en/docs/claude-code/overview