Story Picture

An open-source Agent Skill that generates article-ready images from a content description and a style selected by the user. Users describe the theme, idea, or scene the image should communicate; the Skill helps them choose a visual direction and then generates the image without requiring a hand-written art prompt.

简体中文

1. Describe the content: State the theme, idea, relationship, or scene the image should communicate.
2. Choose a style: Select one of ten styles presented by the Skill, or request a comparison across several styles.
3. Generate the image: The Skill combines the description with the selected style DNA, invokes the host image generator, and checks the result.

Users may include a style in the initial request to generate in one pass.

• Converts a natural-language description into a clear subject, composition, and visual metaphor
• 10 focused illustration styles for article headers, inline artwork, and explainers
• User-controlled style selection instead of an implicit visual direction
• Reference images, stable IDs, structured recipes, and distilled prompts for every style
• A prompt framework built around article messages and visual metaphors
• Provider-independent instructions that use the host agent's image generator
• A zero-dependency catalog search CLI and repository tests

Each images/<style-id>/ directory stores visual references only. All style definitions live in references/styles.json, including the core DNA, complete prompt template, quality rule, and exclusions. This keeps a single source of truth.

First, the user describes what the image should communicate:

Create a 16:9 article header showing that people provide judgment and direction
while AI executes repetitive work. Do not include visible text.

The Skill interprets the request and presents the available styles. The user then selects:

Use blue-orange-hand-drawn-infographic.

The Skill chooses an appropriate visual metaphor, combines the content with the selected style DNA, invokes the image generator, checks the result, and returns the generated image.

Story Picture follows the Agent Skills open standard. The installation unit is the complete skill directory, not SKILL.md alone. The minimum runtime package is:

story-picture/
├── SKILL.md
├── references/
│   ├── styles.json
│   └── prompt-framework.md
├── images/
└── scripts/

SKILL.md is the standard entry point, references/styles.json contains the complete style DNA and generation prompts, and images/ contains the visual references. Copying only SKILL.md leaves the Skill without its required style data.

Clone this repository and record its absolute path. .agents/skills is the broadest shared location across Codex, Cursor, Gemini CLI, and GitHub Copilot:

export STORY_PICTURE_DIR="/absolute/path/to/story-picture"
mkdir -p ~/.agents/skills
ln -s "$STORY_PICTURE_DIR" ~/.agents/skills/story-picture

For a project-local installation, run this from the target project root:

mkdir -p .agents/skills
ln -s "$STORY_PICTURE_DIR" .agents/skills/story-picture

A symlink keeps the installed Skill current. To create an independent copy instead:

mkdir -p ~/.agents/skills/story-picture
cp "$STORY_PICTURE_DIR/SKILL.md" ~/.agents/skills/story-picture/
cp -R "$STORY_PICTURE_DIR/references" \
  "$STORY_PICTURE_DIR/images" \
  "$STORY_PICTURE_DIR/scripts" \
  ~/.agents/skills/story-picture/

Alternatively, paste the following instruction into your current Agent:

Install the Story Picture Skill for me.
Repository: https://github.com/songxiaopeng529/story-picture.git

Requirements:
1. Follow the official Agent Skills directory convention for your current host and choose the correct project-level location.
2. Install the complete story-picture directory, not SKILL.md alone.
3. Preserve the relative structure of SKILL.md, references/, images/, and scripts/.
4. Use project scope unless I explicitly request a global installation.
5. Verify that the Agent discovers the story-picture Skill and can read references/styles.json.
6. Do not modify Skill files. If the destination already exists, report it and propose an update strategy before changing it.

An Agent Skills-compatible host should select its own supported skills directory. The Skill content does not need host-specific changes for Codex, Claude Code, Cursor, Gemini CLI, Copilot, or TRAE.

List all styles:

python3 scripts/style_catalog.py list

Search by article topic, medium, family, or visual trait:

python3 scripts/style_catalog.py search "business article"
python3 scripts/style_catalog.py search "thread fabric"

Inspect one complete recipe:

python3 scripts/style_catalog.py show paper-quilling

See examples/requests.md for request patterns and references/prompt-framework.md for the prompt contract.

Add one object to references/styles.json with a unique kebab-case ID, searchable metadata, and the complete generation fields:

{
  "id": "example-style",
  "label": "Example Style",
  "name_zh": "示例风格",
  "family": "illustration",
  "best_for": ["subject one", "subject two"],
  "recipe": "Observable medium, shape, texture, and composition traits",
  "palette": "Specific color behavior",
  "lighting": "Specific light behavior",
  "core_dna": [
    "Trait 1: observable behavior",
    "Traits 2-7: six more observable behaviors"
  ],
  "prompt_template": "A directly usable prompt with {placeholders}.",
  "quality_rule": "The decisive pass/fail condition.",
  "avoid": ["likely failure one", "likely failure two"]
}

Add at least one real reference image to images/<style-id>/, then run:

python3 -m unittest discover -s tests -v

• Describe observable visual traits, not vague quality labels.
• Make each image communicate one clear article idea.
• Preserve subject identity, count, and relationships across variations.
• Prefer real medium behavior over superficial texture filters.
• Do not bind the Skill to a single image provider.
• Treat craft traditions with specificity and context.

See CONTRIBUTING.md. By participating, you agree to follow CODE_OF_CONDUCT.md.

MIT