Skip to content
Get packs

Guide · Agent skill

How to use the Headshot agent skill: setup, prompts and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

The Headshot skill is an add-on for an AI agent that generates professional headshot images of you from a few real photos you approve. This guide is for people who have not used agent skills before, and it explains what the skill does, how to install it, how to ask for a headshot in plain language, and what it needs to run. By the end you will know how to set it up, what it will and will not do, and how to review its output.

Headshot Generatordanielmiessler/LifeOS · MIT

Quick start

  1. 1Download and unzip. Download the Headshot ZIP from this page and unzip it. Place the Headshot folder in ~/.claude/skills/ or in a project's .claude/skills/ folder.
  2. 2Set your Google API key. Set GOOGLE_API_KEY to a key with access to the Gemini image model. The skill reads it from your env file.
  3. 3Prepare approved reference photos. Choose real photos of yourself, tag each with a sentiment, and list them in your Config.md file.
  4. 4Run the check. Run the check command. If it exits with an error, follow the instructions it prints and the Setup.md guidance.
  5. 5Ask for a headshot. Make a plain request such as generate a headshot for my LinkedIn profile, adding any ratio or lighting you need.
  6. 6Review the output. Look at the critiqued result in Downloads, and check the original in the generated-headshots folder. Choose a variant before anything goes public.

What is an agent skill, and what does Headshot make the agent do?

An agent skill is a folder of instructions and tools that an AI agent can load when a request matches the skill's purpose. Headshot tells the agent how to produce professional AI headshots of the principal, meaning you, using the Gemini image model through Google's API.

Generation is anchored to reference photos you approve in a personal config file, so the face in the result stays recognizable. The skill sizes outputs for uses such as LinkedIn or profile pictures, and it can make variants in different lighting or attire so you can choose one. Results are saved to your personal data folder, not inside the skill folder, and the skill runs a quality review before you see anything.

  • Generates headshots from 1 to 3 reference images you supply
  • Defaults to 2K resolution and a 1:1 square; 3:4 for portrait
  • Stages output in Downloads for review
  • Nothing is published publicly until you pick one

Install the Headshot skill

Download the Headshot ZIP from this page and unzip it. Put the Headshot folder in your personal skills directory at ~/.claude/skills/, or in a project's .claude/skills/ folder if you want the skill only for that project.

If you use the Claude apps instead, you can upload the ZIP under Settings → Capabilities → Skills.

  • Personal install: ~/.claude/skills/Headshot/
  • Project install: .claude/skills/Headshot/ inside the project
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP
bun ~/.claude/skills/Headshot/Tools/Headshot.ts check

Set up your API key, reference photos and config

Headshot needs a Google API key set as GOOGLE_API_KEY, with access to the Gemini image model. The skill reads it from your env file. It also needs the Bun runtime to run its TypeScript command-line tool, the @google/genai npm package, and the LifeOS framework files TOOLS/models.ts and TOOLS/Paths.ts.

Your subject details live in a Config.md file under your USER customizations for the skill. That file lists a folder of approved reference photos, each tagged with a sentiment such as neutral, positive or casual, plus your default look (attire, backdrop and mood). Only photos of yourself or of people who agreed to their likeness being used belong there.

Run the check command before any generation. If it exits with an error, it tells you what is missing, and the skill's Setup.md file explains the fix.

  • GOOGLE_API_KEY is set, with Gemini image model access
  • Bun runtime is installed
  • @google/genai npm package is available
  • LifeOS files TOOLS/models.ts and TOOLS/Paths.ts are present
  • Config.md lists photos that exist on disk
bun ~/.claude/skills/Headshot/Tools/Headshot.ts references --sentiment positive

How to trigger the skill with natural requests

You do not need special syntax. The skill activates on requests that mention a headshot, profile picture, avatar, LinkedIn photo, profile image, portrait, professional photo or casual headshot. Plain requests work well, and you can add details such as ratio or lighting.

The skill is not the right tool for everything. It does not cover general art or diagrams, which belong to the Art skill, non-headshot images of you, which the skill directs to Art with reference images, video avatars, which belong to HyperFrames, or headshots of anyone else.

  • Generate a headshot for my LinkedIn profile
  • Make me a new profile picture for the site
  • I need a headshot with professional lighting, 3:4 ratio
  • Update my profile pic with a casual look
  • Not for: a headshot of my colleague (needs their consent and a different workflow)

What you get back and how review works

The skill routes each result through a quality review before it reaches you. For new or large work it also runs a direction step, and it iterates on defects the review finds. For public uses it can make two to four variants and a labeled pick sheet, so you choose one before anything changes.

Generated headshots are written to the generated-headshots folder in your USER customizations, and a copy reaches your Downloads folder only after the review passes. The skill also says the original stays in the generated-headshots folder.

  • Originals are kept under the skill's generated-headshots folder in your USER data
  • Delivered copies go to Downloads after a passing critique
  • Public-facing variants come as a pick sheet; nothing ships until you choose

Safety notes and tips for better results

Headshot runs scripts and makes network calls to Google's API, because generation happens remotely. Review the skill files before installing if that matters for your setup. Use only photos of yourself or of people who agreed to their likeness being used.

Reference quality matters more than prompt wording. If an output looks flat, the usual fix is a reference photo whose mood matches what you want. For video thumbnails or posters, check likeness against the real footage rather than trusting your eye.

  • Edits keep the mood of the base image; add a reference with the energy you want instead of rewording the prompt
  • Pair a face reference with a real background plate for studio-style scenes
  • Check video-based likeness against actual frames before publishing

What people use it for

  • Refreshing a LinkedIn or professional networking profile photo without a new photoshoot
  • Creating several headshot variants in different lighting or attire to choose from
  • Producing a company bio or publication portrait at a 3:4 portrait ratio
  • Building a repeatable headshot workflow inside an existing LifeOS setup

Frequently asked questions

Do I need to be a developer to install the Headshot skill?

Not necessarily, since you can upload the ZIP in the Claude apps under Settings → Capabilities → Skills. Generation still needs a Google API key, the Bun runtime, and a config file listing your approved reference photos.

Is the Headshot skill free?

This page does not state pricing or licence fees for Google's API, so check Google's terms for usage costs. The skill itself is listed under the MIT licence.

What do I need to run the Headshot skill?

You need the Bun runtime, a GOOGLE_API_KEY with Gemini image model access, the @google/genai npm package, LifeOS framework files, and a personal Config.md with approved reference photos. The ArtDirection skill is also used for critique and delivery.

Can I use the Headshot skill to make a headshot of someone else?

No. The skill's rules require consent from anyone whose likeness is used, and it is designed for headshots of you. Generating from another person's photo without their consent raises likeness and privacy problems.

Why does the skill need reference photos?

Reference photos anchor the face so the output stays recognizable as you. Generic AI image tools tend to drift away from the real face, and the skill is built to avoid that.

What should I do if the check command fails?

Read the output, which points at the missing setting or file. Then follow the Setup.md file in the skill, and confirm GOOGLE_API_KEY is set and the listed photos exist.

How does Headshot compare with other AI headshot tools?

Headshot is built for people who run the LifeOS framework and want a repeatable workflow anchored to their own approved photos. Generic tools may not keep the face as consistent, and this page does not benchmark them against each other.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Headshot is a good fit if you want repeatable, recognizable AI headshots anchored to your own approved photos, and you are comfortable with a Google API key and a config file. If you need headshots of other people, illustrations, diagrams or video avatars, pick the Art skill or another tool instead.

Download the skill