Faces

Use this skill when the user wants to create, compile, or chat through a Face (a persona compiled from source material), compose personas with boolean formul...

Security Scan

The skill's instructions mostly match its stated purpose (managing and compiling personas via the Faces CLI), but there are several mismatches and privacy-sensitive behaviors you should understand before installing or using it.

Purpose & Capability

The name/description map directly to the CLI commands and workflows in SKILL.md (face creation, compile, chat, boolean composition, imports, billing). Required binaries and network access referenced are appropriate for a CLI client of a hosted API.

Instruction Scope

The SKILL.md instructs the agent/user to run many faces CLI commands that read/write ~/.faces/config.json and ~/.faces/catalog/ (local storage of credentials and catalog). It also references environment variables (FACES_TOKEN, FACES_API_KEY, FACES_BASE_URL) and example use of jq, but the skill manifest declared no required config paths or env vars. That mismatch (manifest says none, docs say CLI will read/write these files and env vars) is an incoherence worth calling out. Also the ATTRIBUTES list includes extremely sensitive PII fields (social_security_number, tax_id, full addresses), which encourages storing highly sensitive personal data in the platform and in local catalog files.

Install Mechanism

The skill is instruction-only (no install spec). SKILL.md tells users to install the CLI via 'npm install -g faces-cli' if missing. Installing a global npm CLI is normal but requires trust in the npm package and publisher; SKILL.md asserts the package is on npm and published by 'sybileak' (and points to a repo), but the registry metadata provided with the skill does not itself verify that provenance. There is no direct download URL in the skill bundle to validate the package origin.

Credentials

The skill does not declare required env vars in the manifest, yet documentation and examples rely on FACES_TOKEN, FACES_API_KEY, and FACES_BASE_URL. Those variables are relevant to a CLI client, but the mismatch between declared requirements (none) and the documented env vars is an inconsistency. More importantly, the ATTRIBUTES reference list includes highly sensitive fields (e.g., social_security_number, tax_id, exact addresses). While such fields might be needed for certain persona reconstructions, asking users (or examples) to supply them is disproportionate from a privacy perspective and increases risk of sensitive-data exposure or retention on the remote platform and in local ~/.faces files.

Persistence & Privilege

The skill does not request always:true and is not persistent in the registry sense. However, the CLI stores credentials (JWT/API keys) and maintains a local catalog at ~/.faces/catalog/ and a config at ~/.faces/config.json. That local persistence is expected for a CLI, but the skill manifest reported 'no required config paths' while the instructions explicitly document these paths — a mismatch a user should be aware of. The skill also supports linking a user's ChatGPT subscription and creating API keys, both of which grant persistent capabilities that should be scoped carefully (use budgeted, limited API keys where possible).

What to consider before installing

This skill is an instruction-only wrapper around a third-party CLI (faces-cli) and a hosted service (api.faces.sh). The functionality described (persona creation, compilation, chat, imports, billing) matches the documented commands, but note these important points before you proceed: - Trust & provenance: installing the CLI requires 'npm install -g faces-cli'. Only install if you trust the npm package and its publisher; verify the package on npmjs and the upstream repository before running a global npm install. - Local files & credentials: the CLI will store credentials (JWT or API keys) in ~/.faces/config.json and maintain a local catalog at ~/.faces/catalog/. If you use this skill, expect these files to be created and to hold metadata and tokens — review and protect them. The manifest claimed 'no required config paths' even though the docs describe these files; treat that as an inconsistency. - Sensitive data: the ATTRIBUTES list includes very sensitive fields (social_security_number, tax_id, full addresses). Avoid uploading or entering SSNs, tax IDs, or other unnecessary PII into the platform or into the local catalog unless you have a clear, consented reason and you trust the service's data handling and retention policies. - Credentials & OAuth: the skill supports JWTs, API keys, and linking your ChatGPT account (OAuth). Prefer scoped API keys with budgets/expiry for automated use, and be cautious when linking accounts or sharing tokens. The registration flow requires a payment step (Stripe checkout) — a human must complete it. - Tooling: examples use jq and recommend '--json' output parsing. Ensure you have jq (or equivalent) if you replicate example pipelines. - No code in skill bundle: because this is instruction-only, the skill itself does not contain executable code, but it instructs you to run networked CLI commands. The security posture depends entirely on the CLI and the Faces service; verify their trustworthiness separately. If you decide to proceed: verify the npm package and repo, prefer limited API keys with budgets/expiry, avoid uploading unnecessary PII, and inspect or backup ~/.faces/config.json and ~/.faces/catalog/ so you control local copies of sensitive material.

Faces Skill

You have access to the faces CLI. Use it to fulfill any Faces Platform request.

Always use --json when you need to extract values from command output.

Current config

!faces config:show 2>/dev/null || echo "(no config saved)"

Setup

Verify credentials: faces auth:whoami. If no credentials exist, see references/AUTH.md for registration (requires human payment step) and login.

Install (if faces command not found): npm install -g faces-cli

faces auth:* and faces keys:* require JWT. Everything else accepts JWT or API key.

Plans

Two plans: Free ($5 minimum initial spend, pay-per-token with 5% markup on all usage including compilation) and Connect ($17/month, 100k compile tokens/month, free passthrough to OpenAI Codex for users with a ChatGPT subscription). See references/AUTH.md for details.

Core workflow

1. Create a Face with basic facts and a default model: faces face:create --name "Name" --username slug --default-model gpt-5-nano --attr gender=male --attr age=34 --attr location="Portland, OR" --attr occupation="nurse practitioner"
2. Compile source material in one step: faces compile:doc slug --file document.txt
   • This creates the document, runs LLM extraction with real-time chunk progress, and syncs automatically
   • Repeat for each source document
3. Chat through the Face: faces chat:chat slug -m "message" (auto-routes to the correct API based on model provider)
4. Compare Faces: faces face:diff or faces face:neighbors
5. Compose new Faces from boolean formulas: faces face:create --formula "a | b"

Note: compile:doc handles the full create → compile pipeline. For an already-created document, use compile:doc:make <doc_id>. Threads use a separate workflow: compile:thread:make (same fire-and-forget pattern as documents).

Boolean operators: | (union), & (intersection), - (difference), ^ (symmetric difference). Parentheses supported: (a | b) - c.

Common tasks

Create a face with attributes

When creating a Face, set basic demographic facts with --attr KEY=VALUE (repeatable). Common keys: gender, age, location, occupation, education_level, religion, ethnicity, nationality, marital_status. Unrecognized keys are silently ignored — see references/ATTRIBUTES.md for the complete list of accepted keys.

faces face:create --name "Marcus Rivera" --username marcus \
  --default-model gpt-5-nano \
  --attr gender=male --attr age=34 \
  --attr location="Portland, OR" \
  --attr occupation="nurse practitioner" \
  --attr education_level="master's degree" \
  --attr marital_status=married

You can also add or update attributes and set the default model on an existing Face:

faces face:update marcus --attr religion=Catholic --attr ethnicity="Mexican American"
faces face:update marcus --default-model claude-sonnet-4-6

Compile a document into a face

# Recommended: one-step compile with progress
faces compile:doc <face_id> --file notes.txt --label "Notes"

# Alternative: create then compile separately
DOC_ID=$(faces compile:doc:create <face_id> --label "Notes" --file notes.txt --json | jq -r '.document_id')
faces compile:doc:make "$DOC_ID"

Upload a file (PDF, audio, video, text)

# Upload as document — then compile
DOC_ID=$(faces face:upload <face_id> --file report.pdf --kind document --json | jq -r '.document_id // .id')
faces compile:doc:make "$DOC_ID"

# Upload as thread — compile with make
THREAD_ID=$(faces face:upload <face_id> --file transcript.txt --kind thread --face-speaker "Troy" --json | jq -r '.thread_id // .id')
faces compile:thread:make "$THREAD_ID"

Thread transcript format

Text files uploaded as threads must use Speaker Name: message format, one turn per line:

Interviewer: Tell me about yourself.
Troy: I'm an inventor living in the Parisian countryside.
Interviewer: What drives your work?
Troy: The conviction that technology should serve human flourishing.

Use --face-speaker to specify which speaker IS the face (maps to role=user). All other speakers become role=assistant. If omitted, the first speaker is assumed to be the face.

Audio/video files with --kind thread are transcribed with speaker diarization — speaker labels are assigned automatically (Speaker A, Speaker B, etc.). Use --face-speaker A to map the correct speaker to the face.

Import a YouTube video

# Solo talk / monologue → document
IMPORT=$(faces compile:import <face_id> \
  --url "https://www.youtube.com/watch?v=VIDEO_ID" \
  --type document --perspective first-person --json)
DOC_ID=$(echo "$IMPORT" | jq -r '.document_id // .doc_id // .id')
faces compile:doc:make "$DOC_ID"

# Multi-speaker → thread
IMPORT=$(faces compile:import <face_id> \
  --url "https://youtu.be/VIDEO_ID" \
  --type thread --face-speaker A --json)
THREAD_ID=$(echo "$IMPORT" | jq -r '.thread_id // .id')
faces compile:thread:make "$THREAD_ID"

If --type thread fails with a 422, retry with --type document.

Create a composite face

faces face:create --name "The Realist" --username the-realist \
  --formula "the-optimist | the-pessimist"

# Chat through it like any other face
faces chat:chat the-realist -m "How do you approach risk?"

Composite faces are live: sync new knowledge into any component and the composite updates automatically. Components must be concrete (compiled) faces you own.

Compare faces

faces face:diff --face aria --face marco --face jin
faces face:neighbors aria --k 3
faces face:neighbors aria --component beta --direction furthest --k 5

Chat

chat:chat auto-routes to the correct API endpoint based on model provider (Anthropic → /v1/messages, OpenAI/others → /v1/chat/completions). If the face has a default_model set, no --llm flag is needed.

# Uses face's default model (no --llm needed if default_model is set)
faces chat:chat slug -m "message"

# Override with a specific model
faces chat:chat slug --llm claude-sonnet-4-6 -m "message"
faces chat:chat slug --llm gpt-4o-mini -m "message"

# Use OpenAI Responses API explicitly
faces chat:chat slug --llm gpt-4o -m "message" --responses

Face templates

Use ${face-username} in any message to reference another face's profile inline. The token is replaced with the face's display name and the profile is injected as context. A bare model name (no face prefix) skips the persona and lets you reference all faces via templates.

faces chat:chat alice --llm gpt-4o-mini -m 'You are debating ${bob}. Argue your position.'
faces chat:chat gpt-4o-mini -m 'Compare the worldviews of ${alice} and ${bob}.'

See references/TEMPLATES.md for full details and rules.

Billing and API keys

faces billing:balance --json
faces billing:subscription --json
faces keys:create --name "Partner key" --face slug --budget 10.00 --expires-days 30

Common errors

• faces: command not found — Run npm install -g faces-cli.
• 401 Unauthorized — Credentials missing or expired. Run faces auth:login or check FACES_API_KEY.
• compile:doc:make returns "preparing" — Compilation is async. Poll with faces compile:doc:get <doc_id> --json | jq -r '.prepare_status' until status is synced.
• 422 on thread import — No speaker segments detected. Retry with --type document.
• face:diff or face:neighbors returns null components — The face hasn't been compiled yet. Run faces compile:doc <face_id> --file ... first.

References

• See references/QUICKSTART.md for the end-to-end guide: install → register → create → compile → chat.
• See references/REFERENCE.md for the full command reference, global flags, and environment variables.
• See references/AUTH.md for registration, login, API keys, and credential management.
• See references/CONCEPTS.md for a detailed explanation of what Faces is, how it works, and example use cases.
• See references/OAUTH.md for connecting a ChatGPT account (connect plan only).
• See references/TEMPLATES.md for face template syntax (${face-username}) and bare model usage.
• See references/ATTRIBUTES.md for the complete list of accepted --attr keys (unrecognized keys are silently ignored).
• See references/SCOPE.md for instruction scope and security boundaries.