float - SKILL.md Agent Skill

name: float description: >- Plan and manage team allocations on Float.com using the Float API. Use when the user wants to plan someone on a project, check who is planned where, view allocations, create or update allocations, look up people or projects, or anything related to Float resource planning. Triggers on phrases like "plan", "allocate", "schedule someone on a project", "who is working on", "Float", or any reference to team resource planning. license: MIT metadata: author: spatie version: "0.1.0"

Float Resource Planning

Interact with Float.com to plan team members on projects via the Float API v3.

Prerequisites

The Float API key must be set as an environment variable. Check:

echo $FLOAT_API_KEY

If not set, the Account Owner can find the API key in Float under Team Settings > Integrations. Ask the user to set it:

export FLOAT_API_KEY="your-api-key-here"

Or add it to their shell profile for persistence.

API Basics

Base URL: https://api.float.com/v3
Auth: Bearer token via Authorization: Bearer $FLOAT_API_KEY
Format: JSON (Accept: application/json)
Dates: YYYY-MM-DD format
Pagination: page (default 1), per-page (default 50, max 200)

All requests use curl with these headers:

curl -s "https://api.float.com/v3/ENDPOINT" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

Core Workflow: Planning Someone on a Project

When the user says something like "Plan Alex on Project X for 3 days" or "Allocate Sarah to Website Redesign for 4 hours/day next week", follow these steps:

Step 1: Find the person

curl -s "https://api.float.com/v3/people" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json"

Search through the results to find the person by name (case-insensitive partial match). The key field is people_id.

Step 2: Find the project

curl -s "https://api.float.com/v3/projects" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json"

Search through results to find the project by name (case-insensitive partial match). The key field is project_id.

Step 3: Create the allocation

curl -s -X POST "https://api.float.com/v3/tasks" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "people_id": PEOPLE_ID,
    "project_id": PROJECT_ID,
    "start_date": "YYYY-MM-DD",
    "end_date": "YYYY-MM-DD",
    "hours": HOURS_PER_DAY
  }'

Interpreting user requests

"for 3 days" means set start_date to the next working day and end_date 3 working days later (skip weekends). Use a reasonable hours value like 8 (full day).
"for 4 hours/day next week" means start_date = next Monday, end_date = next Friday, hours = 4.
"this week" means start_date = today (or next working day), end_date = Friday of this week.
"next week" means start_date = next Monday, end_date = next Friday.
"for 2 weeks" means start_date = next Monday, end_date = Friday two weeks later.
"half days" means hours = 4.
"full days" or no hours specified means hours = 8.
Always confirm the interpreted dates and hours with the user before creating the allocation.

Endpoints Reference

People

# List all people (paginated)
curl -s "https://api.float.com/v3/people?per-page=200" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json"

# Filter by active status
curl -s "https://api.float.com/v3/people?active=1" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json"

# Get a specific person
curl -s "https://api.float.com/v3/people/PEOPLE_ID" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json"

Key response fields: people_id, name, email, job_title, role_id, department, active, employee_type, work_days_hours, tags

Projects

# List all projects
curl -s "https://api.float.com/v3/projects?per-page=200" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json"

# Filter by active projects
curl -s "https://api.float.com/v3/projects?active=1" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json"

# Get a specific project
curl -s "https://api.float.com/v3/projects/PROJECT_ID" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json"

Key response fields: project_id, name, client_id, color, status, active, budget_type, budget_total, start_date, end_date, tags, notes

Allocations (called "tasks" in the API)

# List allocations with filters
curl -s "https://api.float.com/v3/tasks?people_id=ID&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json"

# Get a specific allocation
curl -s "https://api.float.com/v3/tasks/TASK_ID" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json"

# Create an allocation
curl -s -X POST "https://api.float.com/v3/tasks" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "people_id": 123,
    "project_id": 456,
    "start_date": "2026-03-16",
    "end_date": "2026-03-20",
    "hours": 8
  }'

# Update an allocation
curl -s -X PATCH "https://api.float.com/v3/tasks/TASK_ID" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "hours": 4,
    "end_date": "2026-03-25"
  }'

# Delete an allocation
curl -s -X DELETE "https://api.float.com/v3/tasks/TASK_ID" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json"

Create/Update fields:

Field	Type	Required	Description
`people_id`	integer	Yes (or people_ids)	Person to allocate
`people_ids`	array of int	Yes (or people_id)	Multiple people at once
`project_id`	integer	Yes	Project to allocate to
`start_date`	string	Yes	Start date (YYYY-MM-DD)
`end_date`	string	Yes	End date (YYYY-MM-DD)
`hours`	number	Yes	Hours per day
`start_time`	string	No	Start time (24h format)
`phase_id`	integer	No	Phase within project
`status`	integer	No	0=Draft, 1=Tentative, 2=Confirmed, 3=Complete, 4=Canceled
`name`	string	No	Task name
`task_meta_id`	integer	No	Project task ID (overrides name)
`notes`	string	No	Notes on the allocation
`repeat_state`	integer	No	Repeat frequency (0=none)
`repeat_end_date`	string	No	When repeating ends (YYYY-MM-DD)

Time Off

# List time off entries
curl -s "https://api.float.com/v3/timeoffs?people_id=ID&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json"

Common Queries

"Who is planned this week?"

Fetch allocations for the current week across all people:

curl -s "https://api.float.com/v3/tasks?start_date=MONDAY&end_date=FRIDAY&per-page=200" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json"

Then cross-reference people_id and project_id with cached people/projects data. Present as a table grouped by person.

"What is Alex working on?"

Find Alex's people_id from the people list
Fetch their allocations:

curl -s "https://api.float.com/v3/tasks?people_id=ALEX_ID&start_date=TODAY&end_date=FAR_FUTURE&per-page=200" \
  -H "Authorization: Bearer $FLOAT_API_KEY" \
  -H "Accept: application/json"

"Who is available next week?"

Get all active people
Get all allocations for next week
Compare: people without allocations (or with < 8h/day) are available

Output Guidelines

Present allocation data as clean tables when listing multiple items
Always show: person name, project name, dates, hours/day
When creating allocations, confirm the details before executing
After creating/updating, show a summary of what was done
Use relative date descriptions ("next Monday" not just "2026-03-23") alongside the actual dates