Freeplay Skills

Skills for the Freeplay Plugin that teach Claude Code and Cursor to onboard to Freeplay, analyze logs, iterate on prompts and agents, and run experiments in Freeplay, the ops platform for AI engineering teams.

⚠️ EXPERIMENTAL

These skills are experimental and will change. Use at your own risk.

When used with the Freeplay MCP server, these skills instruct agents that have access to your Freeplay API key. A compromised agent could extract the key and perform actions against your Freeplay account outside the scope of these skills. Only use with agents you fully trust.

---

Installation

Using OpenSkills

Install directly from GitHub using OpenSkills:

npx openskills install https://github.com/freeplayai/freeplay-skills.git

Manual Installation

Clone this repository into your skills directory:

For Claude Code:

git clone https://github.com/freeplayai/freeplay-skills.git ~/.config/claude-code/skills/freeplay-skills

For Cursor (project-level):

git clone https://github.com/freeplayai/freeplay-skills.git .cursor/skills/freeplay-skills

For Cursor (global):

git clone https://github.com/freeplayai/freeplay-skills.git ~/.cursor/skills/freeplay-skills

Required Environment Variables

The following environment variables must be set:

Variable	Description
FREEPLAY_API_KEY	Your Freeplay API key (required)
FREEPLAY_API_BASE	Freeplay API base URL (required)

Security Note: API keys are handled securely and should never be logged or printed. The SecretString wrapper ensures keys are displayed as [REDACTED] if accidentally printed.

Project ID

Project ID can come from:

• User specification
• MCP list_projects() tool to discover available projects
• --project-id CLI arg (for scripts)

Skills

Skill	Purpose
freeplay-onboarding	Orchestrator — guides complete onboarding flow with checkpoints
freeplay-plan	Analyzes a codebase to map LLM usage patterns and build a migration plan
prompt-migration	Migrates prompts into Freeplay for version control and management
record-to-freeplay	Integrates Freeplay logging, tracing, and observability
dataset-management	Create and manage prompt and agent datasets
health-check	Assess project health across the data flywheel
run-test	Execute Freeplay test runs
test-run-analysis	Analyze test run results and surface recommendations

Usage with Claude Code

These skills are auto-invoked by Claude based on context when using the Freeplay plugin. They capture workflows and best practices for working with Freeplay's connected data flywheel: observability, prompt management, datasets, evaluations, and testing. Skills are included as a git submodule in the main plugin repository.

Usage with Cursor

These skills can also be used with Cursor through its Agent Skills system. When installed to .claude/skills/ (via OpenSkills) or .cursor/skills/ (via manual installation), Cursor automatically discovers and invokes them based on context.

Skills are separate from Cursor Rules (stored in .cursor/rules/) which provide persistent behavioral guidelines. Skills and rules work together — rules define how the AI should behave, while skills provide specialized workflows that are auto-invoked when relevant.

Shared Resources

The scripts/ directory contains shared Python utilities used across multiple skills:

• api.py - A small subset of API calls that can be used.
• secrets.py - Secure handling of API keys with SecretString wrapper

Skills should symlink to these shared modules rather than duplicating code. See scripts/README.md for details.

The _shared/ directory contains reference materials used by the onboarding skills (API reference, framework detection guides, environment config).

Adding a New Skill

Create a directory with a SKILL.md file:

skills/
└── my-skill/
    └── SKILL.md

The SKILL.md file should include frontmatter:

---
name: my-skill
description: When Claude should auto-invoke this skill
---

Instructions for the skill.

Support

• Docs: https://docs.freeplay.ai
• Issues: https://github.com/freeplayai/freeplay-skills/issues
• Security: security@freeplay.ai