female-portrait-director: a Codex Skill that turns portrait notes into directed prompts

The problem: portrait prompts drift when you write them by hand

Most people writing portrait prompts start from a short list of wishes: a scene, an outfit, a mood, an aspect ratio. What comes back from a generic prompt collection is usually a pile of style keywords that contradict each other, or a mechanical restatement of the input with no photographic intent behind it. The README frames the project against exactly that: "This is not a generic prompt collection." The Skill's stated job is to lock explicit requirements, choose one visual route, and direct subject, action, clothing, scene, camera, lighting and finish as a single photographable moment.

The audience is narrow and specific. You need an agent host that can load a Skill, and you need to care about consistency across a series of portraits rather than one throwaway image. The README lists twenty supported styles, from clean lifestyle and urban fashion through gufeng fantasy, retro Hong Kong, French relaxed, new Chinese oriental, e-commerce clothing model images and several CCD-flavoured curve directions. That spread matters: it is a menu for people producing portrait sets, not a single-look toy.

One boundary is stated up front and is worth taking literally. Subjects are fictional, clearly adult women unless an authorized adult reference is provided. The repository also ships a DISCLAIMER.md at the top level, alongside SECURITY.md and NOTICE.md. If your use case involves real people, the authorized-reference path is the only one the project describes.

How the Skill routes a request through one style file

The mechanism described in the README is routing plus module expansion. Each request goes through one on-demand style file rather than blending every style keyword the user typed, which is the design choice that prevents the conflicting-keyword problem. The Skill then parses face, body, outfit, scene, camera and pose, lighting, and filter as separate modules.

Expansion is the second half. Short parameters get filled out into a coherent photographed moment instead of being repeated back. The README's own example takes a gufeng xianxia request with a courtyard corridor, a moon-white Tang-inspired wide-sleeve robe, a pibo scarf, a silver embroidered waist sash, cool ethereal mood and a 9:16 ratio, and produces locked parameters, module analysis, a final prompt and negative constraints. That four-part output shape is documented under Output Format, and the skill/help.md guide covers route-plus-overlay combination rules plus a complete parameter-to-five-paragraph-prompt example.

The distribution is not a single file. The README describes a 62-file distribution package containing SKILL.md and every referenced route, tool, safety file and example. The repository layout matches that: agents/, assets/, docs/, examples/, skill/ and skills/ directories sit alongside SKILL.md, with example files such as examples/gufeng_fantasy_examples.md and examples/ecommerce_tryon_examples.md. If you were expecting a one-file prompt template, this is heavier than that, and the weight is the point.

Installing female-portrait-director and running a first portrait

The README requires Node.js for the one-command installer and points at the open-source skills CLI. The install command targets the skill subdirectory on main, not the repository root, and the -g flag installs it globally.

npx skills add https://github.com/liyue-aigc/female-portrait-director/tree/main/skills/female-portrait-director -g

After that, start a new agent session. The README's 60-second example pastes a parameter block and asks for an image directly.

Use $female-portrait-director to generate an image directly:
Style: clean lifestyle portrait
Scene: quiet cafe window seat in the afternoon
Outfit: ivory knitted cardigan + light inner top
Mood: gentle, natural, clearly adult
Aspect ratio: 3:4

The README states that removing "generate an image directly" switches the Skill to returning a copy-ready prompt instead of an image, along with locked parameters and negative constraints. That distinction is the one to internalize before your first run, because the two modes have different dependencies.

If you prefer not to use the CLI, the README documents a manual Git install into the Codex skills directory. On macOS or Linux the target is ${CODEX_HOME:-$HOME/.codex}/skills/female-portrait-director; on Windows PowerShell it is $env:USERPROFILE\.codex\skills\female-portrait-director. Restart Codex or open a new conversation afterwards, then invoke $female-portrait-director. The README says a parameter-free first invocation displays the V1.6 tutorial with all 20 implemented styles, basic and advanced templates, style-plus-mood combination guidance and a detailed prompt example. To update an installed copy, the README gives:

npx skills@latest update female-portrait-director -g -y

The compatibility table is narrower than the badge row suggests

This is where the README is unusually honest and where most readers should slow down. The compatibility table lists Codex, Claude Code, Cursor, GitHub Copilot and Gemini CLI. All five are marked Verified for the install package and Agent Skills compatible for the prompt workflow. But the direct image workflow column reads "Supported when image generation is available" for Codex and "Depends on the connected image tool" for the other four.

The README then states the limit plainly: only Codex was runtime-executed in this release environment, and the other rows are packaging and specification compatibility claims, not claims that every host provides an image model. "Installer-verified" is defined as the CLI copying SKILL.md and every referenced route, tool, safety file and example into the target skill package. That is a file-copy guarantee, not a behaviour guarantee.

So the practical failure mode is a successful install followed by a prompt-only experience on a host with no image tool attached. Nothing in the README says the Skill detects that and warns you. If direct image output is your reason for installing, Codex is the only target the project claims to have actually run, and even there the README conditions it on image generation being available. Treat the other four rows as "the files will land correctly," which is a real but smaller promise.

Where a prompt director is the wrong tool

If you want deterministic, reproducible images from a fixed seed, this is the wrong layer. The Skill produces locked parameters and a directed prompt; the rendering still belongs to whatever image model you connect. The README makes no claim about seed control, model selection or output reproducibility, and those are the things you would need for a batch pipeline where image 47 must match image 46.

It is also the wrong tool if you dislike long prompts. The documented output is a five-paragraph prompt in the help guide's worked example, plus module analysis and negative constraints. That is a lot of text to hand to a model, and if your workflow already depends on short tag-style prompts for a specific checkpoint, the director's expansion will fight that style rather than help it.

Finally, the style menu is opinionated and bounded. Twenty styles are listed, and routing deliberately picks one style file to avoid conflicting keywords. That is a constraint, not a bug: if your portrait concept sits between two of the listed routes, the README's answer is the route-plus-overlay combination rules in skill/help.md, not free-form style mixing. Read that file before assuming your look is covered.

How it differs from a plain prompt library or a bare image model

A generic prompt collection, which the README explicitly positions against, hands you text to copy. A bare image model takes whatever text you give it and renders. Female Portrait Director sits between them: it is a director that locks parameters, picks one visual route, expands modules and emits negative constraints before any rendering happens.

The concrete difference shows up in the output contract. Locked parameters, module analysis, a final prompt, negative constraints. A prompt library has none of those stages; a raw model has no notion of locking your inputs at all. The README's phrasing is that the Skill preserves requested parameters and fills in missing visual details, which is a narrower and more defensible claim than "improves your prompts."

There is also a reference-image path that a text-only prompt library cannot offer. The README describes preserving authorized selfie identity or product core visuals for direct reference-image generation, and preserving clothing-display priority for e-commerce images. That is a different capability class from prompt text, and it is the reason examples/ecommerce_tryon_examples.md exists as a separate file rather than a paragraph in the main guide. If your work is flat-lay or on-model clothing rather than character portraiture, that example file is the one to open first.

Maintenance, licence and the cost of upgrading

The repository is not archived. The last push was on 2026-07-15, which is recent enough that the project is not stale, though the README does not describe a release cadence or a support commitment. Two releases appear in the record: v1.3.0 on 2026-05-30 and v1.4.0 on 2026-05-31, one day apart. The README's first-use tutorial is labelled V1.6, which is a version marker the release list does not account for. If you need to know exactly what changed between the version you installed and the one on main, the CHANGELOG.md at the repository root is the file to read, since the README does not document rollback or a downgrade path.

Upgrade cost is low and documented. The update command is a single npx invocation with -g and -y, and the Git install path is a clone into the skills directory, so a re-clone or pull covers manual setups. The 62-file package is the thing to keep in mind: because the Skill references route files, tool files, safety files and examples, a partial or interrupted copy is the realistic failure to check for after an upgrade, and the README's definition of installer-verified is precisely that every referenced file landed.

The licence is MIT, stated in the README badge and present as LICENSE at the top level. MIT is permissive, but the repository also ships NOTICE.md, DISCLAIMER.md and SECURITY.md, and the README sets an explicit boundary that subjects are fictional, clearly adult women unless an authorized adult reference is provided. Those files carry terms the licence badge does not summarize. Read them yourself; this is not legal advice, and the authorized-reference requirement is a usage condition rather than a licensing question.

Editorial conclusion

Adopt female-portrait-director if you already run Codex and want repeatable, parameter-locked portrait prompts across the 20 documented styles, particularly for gufeng, urban fashion or e-commerce clothing work. Skip it if your host is not Codex and you need direct image output, since the README states only Codex was runtime-executed and the other agents depend on a connected image tool. Before committing, read skill/help.md for the style-plus-overlay combination rules, and check whether your target host supplies an image model at all.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. liyue-aigc/female-portrait-director on GitHub
4. README
5. Releases