YouCam Skills

Turn YouCam AI into drop-in Agent Skills.

YouCam Skills packages Perfect Corp's YouCam AI capabilities as installable skills for agent environments. That means users can trigger real YouCam APIs with natural language:

"How does my skin look?"
"Try this hairstyle on me."
"Let me try on this jacket in a video."

Behind the scenes, each skill handles API calls, task creation, polling, cost checks, and result reporting. Every skill can also run directly from the CLI for testing, automation, or non-agent workflows.

Skills

YouCam Skills repo: https://github.com/YouCam-API/skills

Installing

If your agent host supports the Skills CLI, install straight from GitHub:

npx skills add YouCam-API/skills

This lists the six skills in this repo and lets you pick which ones to add, then which of your installed agents (Claude Code, Cursor, etc.) to add them to. To skip the prompts, add specific skills and/or a specific agent directly:

npx skills add YouCam-API/skills --skill skin-analysis-expert -a claude-code

or install everything, to every detected agent:

npx skills add YouCam-API/skills --all

This repo exposes 6 AI-powered beauty, grooming, hair, skin, and fashion try-on experiences as modular Agent Skills:

Skill	Use Case
Skin Analysis Expert	Analyze 16 skin concerns plus skin type from one selfie. Choose HD/SD detail and overlay or mask visualization.
Facial Consultant	Read facial colors and proportions, including skin tone, eye color, brow color, lip color, hair color, feature shapes, and golden-ratio measurements.
Beauty Advisor	Recommend makeup looks based on face shape and skin tone, then render the result onto a photo using curated or custom beauty effects.
Hair Color & Style Advisor	Suggest hairstyles and colors from facial features, then preview them with templates, reference photos, color presets, or custom palettes.
Hair Diagnostics	Assess hair density, type, frizziness, and length, then combine the findings into one report.
Clothes Try-on Studio	Virtual outfit try-on on user photos, with optional background replacement and short motion videos like turns, runway walks, or poses.

Why It Matters

For developers:

Natural-language entry points for YouCam APIs
Installable skill structure for agent environments
CLI-first testing with youcam_core.py
Automatic upload → task creation → polling flow
Credit-aware execution before paid API calls
Simple extension model for adding or customizing skills

For product and marketing use:

AI beauty, skincare, haircare, and fashion try-on experiences
Personalized recommendations powered by user photos
Visual previews that users can understand instantly
Clear pre-run cost communication
Built-in responsible-use messaging around AI-generated results

How It Works

Each skill follows the same workflow:

The user describes a request in plain English.
The agent selects the appropriate YouCam Skill.
The skill asks for required inputs, such as a photo or target action.
The skill checks or estimates credit cost before running.
The bundled script uploads media and creates an API task.
The task is polled until complete.
Results are returned as structured JSON and summarized clearly.

Setup

Requirements:

Python 3
pip
YouCam API key
requests
PyYAML

From inside a skill folder, run:

python scripts/youcam_core.py setup

This creates a local virtual environment and installs dependencies.

Alternatively:

pip install -r scripts/requirements.txt

Get an API key from:

https://yce.makeupar.com/api-console/

API Key Configuration

youcam_core.py looks for credentials in this order:

Environment variable:

YOUCAM_API_KEY=your_key_here

Local credentials.json file inside the skill folder:

{
  "api_key": "your_key_here"
}

Because each skill has its own folder, credentials are configured per skill.

Validate your key and check balance without spending credits:

python scripts/youcam_core.py validate-key

Cost Checks Before Execution

Before making paid API calls, users or agents can run free preflight checks:

python scripts/youcam_core.py cost --feature skin-analysis
python scripts/youcam_core.py credits

Both commands are free and return pricing or balance information.

This makes it easier to build credit-aware workflows where the user confirms before spending.

CLI Quickstart

Run a skill directly:

python scripts/youcam_core.py run \
  --feature skin-analysis \
  --src_file selfie.jpg \
  --param format=json \
  --param dst_actions='["hd_pore","hd_skin_type"]'

This will:

upload the source image
create an API task
poll for completion
print structured JSON output

Useful flags:

Flag	Purpose
`--feature`	Selects the target YouCam feature.
`--src_file`	Local path or URL to the primary input image/video.
`--ref_file`	Optional second input, such as a garment photo.
`--param`	Repeated key-value API parameters.
`--version`	Overrides the default API version if needed.

Supported media formats are usually JPG, JPEG, or PNG. Video features may accept MP4. The tool does not convert files automatically.

If a task is still running after polling stops:

python scripts/youcam_core.py status \
  --feature skin-analysis \
  --task_id <task_id>

Agent Experience

When used inside an agent environment that supports Skills, users do not need to know API names or parameters. They can simply ask for outcomes:

"Analyze my skin."
"Recommend a hairstyle for me."
"Put this outfit on me and make it move."
"Check my hair health from this photo."

The agent chooses the right skill, collects required inputs, confirms costs, executes the API workflow, and returns an understandable result.

Important Notes

All outputs are AI-generated and intended for reference only. They are not medical, dermatological, cosmetic, or professional styling advice.

Result quality depends on:

photo resolution
lighting
face angle
image clarity
subject visibility
supported input formats

Some API fields may occasionally be unavailable. Skills are designed to omit missing data rather than invent values.