paper-signal
Subject-aware minimal-zine image production for Agent Skills: art direction, generation, series, evidence, and real-bitmap QA.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/jiahuiqu17--paper-signal)HTML
<a href="/listings/jiahuiqu17--paper-signal"><img src="/api/listings/jiahuiqu17--paper-signal/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
npx skills add jiahuiqu17/paper-signal
**Codex Desktop: end-to-end verified · Claude Code: Skill-compatible · Agent Skills · MIT**
Then open a fresh task and ask:
Use $paper-signal-art-director to restyle this photo as a tactile minimal-zine poster. Preserve the subject, save the final prompt, and inspect the bitmap.
Works as a standard Skill in Codex, Claude Code, and other compatible clients. Final image generation depends on the image tools available in your host; see the [verified support levels](#installation-and-compatibility).
[简体中文](README.zh-CN.md) · [See how it works](#why-it-is-more-than-a-style-prompt) · [Compatibility](docs/compatibility.md) · [Contributing](.github/CONTRIBUTING.md)
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 304 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Paper Signal Studio
- **Turn photos, ideas, and research into beautiful editorial visuals with Codex or Claude Code.**
- <table>
- <tr>
- <td width="50%"><a href="examples/edinburgh-field-studies/outputs/01-study-old-town-after-rain.png"><img src="assets/gallery/01-study-old-town-after-rain.webp" alt="Old Town after rain, cyanotype panorama" /></a></td>
- <td width="50%"><a href="examples/edinburgh-field-studies/outputs/02-study-arthurs-seat-low-cloud.png"><img src="assets/gallery/02-study-arthurs-seat-low-cloud.webp" alt="Arthur's Seat in low cloud, dual frame" /></a></td>
- </tr>
- <tr>
- <td width="50%"><a href="examples/edinburgh-field-studies/outputs/03-study-leith-last-light.png"><img src="assets/gallery/03-study-leith-last-light.webp" alt="Leith at last light, vermilion photo window" /></a></td>
- <td width="50%"><a href="examples/edinburgh-field-studies/outputs/04-study-stone-light-close.png"><img src="assets/gallery/04-study-stone-light-close.webp" alt="Edinburgh stone and light, specimen plate" /></a></td>
- </tr>
- </table>
- Made with one shared paper-and-ink system and four compositions chosen for the subject. Click any image for the full result.
- ## Quick start
- ```bash
- npx skills add jiahuiqu17/paper-signal
- ```
- **Codex Desktop: end-to-end verified · Claude Code: Skill-compatible · Agent Skills · MIT**
- Then open a fresh task and ask:
- ```text
- Use $paper-signal-art-director to restyle this photo as a tactile minimal-zine
- poster. Preserve the subject, save the final prompt, and inspect the bitmap.
- ```
- Works as a standard Skill in Codex, Claude Code, and other compatible clients. Final image generation depends on the image tools available in your host; see the [verified support levels](#installation-and-compatibility).
- [](https://github.com/jiahuiqu17/paper-signal/actions/workflows/validate.yml)
- [](https://github.com/jiahuiqu17/paper-signal/releases)
- [](LICENSE)
- [简体中文](README.zh-CN.md) · [See how it works](#why-it-is-more-than-a-style-prompt) · [Compatibility](docs/compatibility.md) · [Contributing](.github/CONTRIBUTING.md)
- ## Why it is more than a style prompt
- The simple promise is better-looking editorial imagery. Underneath, Paper Signal protects the things a style prompt often loses:
- - **the subject** — identity, architecture, object shape, crop, and exact values;
- - **the visual logic** — composition follows the content instead of one template;
- - **the craft** — paper, ink, halftone, type, and colour behave as one physical system;
- - **the result** — the real bitmap is inspected, corrected, and saved with its prompt.
- Paper Signal keeps the whole production chain inspectable:
- ```text
- brief → protect the subject → route subject and composition → art direction
- → save the exact prompt → native raster generation → inspect the bitmap
- → targeted correction → validated project
- ```
- For factual posts it can also keep an evidence record and write natural caption copy. For a single photograph or idea, it stays compact and focuses on the image.
- ## What makes it different
- | Capability | Paper Signal approach |
- |---|---|
- | Subject integrity | Identity, horizon, silhouette, architecture, crop, and exact values are blocking constraints |
- | Composition | Seven adaptive modes selected after the subject route, not one template for every topic |
- | Material craft | One physical reproduction process explains grain, dot gain, ink spread, registration, and edge behaviour |
- | Colour | One meaningful chromatic signal; no palette contamination for decoration's sake |
- | Reproducibility | Every selected image keeps its brief, manifest, final prompt, output, and QA record |
- | Social series | Sequence, caption, evidence, and per-card routing are available without burdening a single poster |
- | Quality control | Automated structure checks plus full-size and phone-thumbnail visual review |
- See [`docs/comparison.md`](docs/comparison.md) for a respectful scope comparison with GC Minimal Zine Poster, `baoyu-xhs-images`, Anthropic Canvas Design, and one-off prompts.
- ## Before / after: style without losing the subject
- The four Edinburgh images remain the finished-work hero. The compact block below tests a different claim: whether a print transfer can change the material reading without replacing the person or object. Each pair shows a repository-generated fictional edit target followed by the selected Paper Signal result.
- <table>
- <tr>
- <th colspan="2">Portrait · identity preservation</th>
- </tr>
- <tr>
- <td width="50%"><a href="examples/portrait-carbon-study/refs/source-portrait.png"><img src="assets/proofs/portrait-reference.webp" alt="Fictional portrait edit target" /></a><br /><sub>Before · edit target</sub></td>
- <td width="50%"><a href="examples/portrait-carbon-study/outputs/01-poster-portrait-carbon-study.png"><img src="assets/proofs/portrait-result.webp" alt="Portrait Carbon Paper Signal result" /></a><br /><sub>After · Paper Signal</sub></td>
- </tr>
- <tr>
- <th colspan="2">Object · geometry and wear preservation</th>
- </tr>
- <tr>
- <td width="50%"><a href="examples/object-specimen-study/refs/source-moka-pot.png"><img src="assets/proofs/object-reference.webp" alt="Moka pot edit target" /></a><br /><sub>Before · edit target</sub></td>
- <td width="50%"><a href="examples/object-specimen-study/outputs/01-poster-object-specimen-study.png"><img src="assets/proofs/object-result.webp" alt="Object Specimen Paper Signal result" /></a><br /><sub>After · Paper Signal</sub></td>
- </tr>
- </table>
- The full [`portrait`](examples/portrait-carbon-study/) and [`object`](examples/object-specimen-study/) cases include the source-generation prompt, edit target, preservation record, exact transfer prompt, manifest, selected bitmap, asset hashes, and observation-based QA. The README loads only 600 × 800 WebP previews; click any image for the full PNG.
- ## Installation and compatibility
- ### Choose a host
- The Quick Start command is interactive. To target a host explicitly:
- ```bash
- npx skills add jiahuiqu17/paper-signal --agent codex
- npx skills add jiahuiqu17/paper-signal --agent claude-code
- ```
- Select the full `paper-signal` entry point or one of the three specialist skills. The repository also contains a Codex plugin manifest at `.codex-plugin/plugin.json`.
- | Host | Skill loading | Complete bitmap workflow |
- |---|---|---|
- | Codex Desktop | Verified | End-to-end reference runtime with image inspection and built-in ImageGen |
- | Codex CLI | Verified discovery and repository tooling | Depends on the image tools configured for that session |
- | Claude Code | Agent Skills-compatible; installable with the community installer | Requires an image-inspection and image-generation tool; not yet end-to-end verified here |
- | Cursor and other compatible agents | Installer- and host-dependent | Depends on the host capabilities; prompt-only fallback remains available |
- The short compatibility line near the top means the Skill format loads on those hosts—not that every host exposes the same image tools. Format compatibility, tool availability, and tested rendering are separate levels. See the maintained [`compatibility matrix`](docs/compatibility.md).
- ### Install an immutable release
- Each tagged release includes a deterministic skills-only ZIP and `SHA256SUMS`. It omits the large visual examples while retaining the four skills, schemas, license, and essential documentation.
- ```bash
- gh release download --repo jiahuiqu17/paper-signal \
- --pattern "paper-signal-skills-*.zip" --pattern SHA256SUMS
- shasum -a 256 -c SHA256SUMS
- unzip paper-signal-skills-v*.zip
- npx skills add ./paper-signal-v*
- ```
- ### Local Codex development
- Clone the repository, then link the skill folders into Codex:
- ```bash
- git clone https://github.com/jiahuiqu17/paper-signal.git
- cd paper-signal
- for skill in paper-signal paper-signal-art-director paper-signal-series paper-signal-audit; do
- ln -s "$PWD/skills/$skill" "${CODEX_HOME:-$HOME/.codex}/skills/$skill"
- done
- ```
- Inspect an existing destination before replacing it. Open a new task after installation so the skill inventory reloads.
- ### Requirements
- - an Agent Skills-compatible host;
- - image inspection for references and visual QA;
- - a runtime-native bitmap generator for rendering;
- - Python 3.10 or later only for project and repository tools.
- Paper Signal bundles no image model, API key, tracking code, or third-party runtime. In Codex it uses built-in ImageGen.
- ### Personalise without forking
- Copy the preference template into a project or user config location:
- ```bash
- mkdir -p .paper-signal
- cp skills/paper-signal/assets/PREFERENCES.example.md \
- .paper-signal/PREFERENCES.md
- ```
- You can set preferred paper processes, anchor inks, aspect ratio, text burden, caption voice, source-label policy, and banned motifs. Current-request instructions and subject-preservation rules always take precedence. See [`preferences.md`](skills/paper-signal/references/preferences.md).
- ## Included skills
- | Skill | Use it for |
- |---|---|
- | `$paper-signal` | Complete routing and production from brief to final bitmap |
- | `$paper-signal-art-director` | One poster, landscape, portrait, object, architecture image, or existing-photo restyle |
- | `$paper-signal-series` | Two to ten Xiaohongshu/Instagram cards, visual essays, travel diaries, or evidence-led explainers |
- | `$paper-signal-audit` | Diagnose generic, inaccurate, AI-looking, or materially weak outputs and write targeted corrections |
- Example requests:
- ```text
- Use $paper-signal-art-director to turn this rainy Edinburgh street into a quiet
- minimal-zine poster. Preserve the street geometry, use a panorama strip and one
- cyanotype plate, save the final prompt, and generate the bitmap.
- ```
- ```text
- Use $paper-signal-series to turn these notes and photographs into five
- Xiaohongshu images. Route each card by subject, keep one material system,
- write the caption, save every prompt, and generate the real image series.
- ```
- ```text
- Use $paper-signal-audit to explain which visible details make these images feel
- AI-generated. Rank the failures and return one targeted correction prompt per
- failed image without regenerating them.
- ```
- ## Adaptive composition
- `minimal-zine-standard` is a material kernel, not a fixed small-photo layout.
- | Composition mode | Best for | Active image area |
- |---|---|---:|
- | `airy-fragment` | poems, compact concepts, evidence fragments | 10%-24% |
- | `photo-window` | atmospheric photos, architecture, editorial covers | 24%-45% |
- | `panorama-strip` | landscape, street, coastline, weather | 18%-36% |
- | `dual-frame` | context/detail, near/far, before/after | 22%-42% |
- | `specimen-plate` | objects, food, products, plants, garments | 12%-34% |
- | `portrait-archive` | people, profiles, documentary portraits | 22%-44% |
- | `type-object` | words or numerals that truly are the subject | 12%-30% |
- The ranges are perceptual guides. Identity, horizon, silhouette, spatial geometry, and meaningful crop take priority.
- ## Project output
- A single-image project can stay small:
- ```text
- project/
- ├── brief.md
- ├── manifest.json
- ├── prompts/
- └── outputs/
- ```
- Series add `analysis.md` and `outline.md`. Factual work adds `evidence.json`; personal-sharing work can add `caption.md`; photo restyles add `preservation.md`.
- Create a project:
- ```bash
- python skills/paper-signal/scripts/init_project.py edinburgh-after-rain \
- --path ./work --cards 1 --ratio 3:5 \
- --subject landscape --composition panorama-strip \
- --preset weathered-horizon
- ```
- Validate it:
- ```bash
- python skills/paper-signal/scripts/validate_project.py \
- ./work/edinburgh-after-rain --require-prompts --require-images
- ```
- Machine-readable contracts are published in [`schemas/`](schemas/): project manifest 1.0/1.1, evidence ledger 1.0, behavioural cases 1.0, and eval-run 1.0. The runtime validator remains the source of truth for cross-file and bitmap checks that JSON Schema cannot express.
- ## Examples
- - [`edinburgh-field-studies`](examples/edinburgh-field-studies/) — four 3:4 images, four composition modes, one material identity; complete and validated.
- - [`portrait-carbon-study`](examples/portrait-carbon-study/) — source-to-result identity-preservation proof with a fictional redistributable fixture.
- - [`object-specimen-study`](examples/object-specimen-study/) — source-to-result silhouette, component, wear, and material-preservation proof.
- - [`edinburgh-after-rain`](examples/edinburgh-after-rain/) — self-contained single-landscape prompt and correction history.
- - [`three-course-field-guide`](examples/three-course-field-guide/) — evidence-led Xiaohongshu planning, caption, prompts, and selected cover.
- ## Development and maintenance
- New here? Start with [**Good First Contributions**](.github/CONTRIBUTING.md#good-first-contributions). You do not need to understand the whole architecture to test a host, improve one installation note, report a visual regression, or contribute a complete example.
- The runtime and core test suite use standard-library Python:
- ```bash
- make check
- ```
- It compiles scripts, runs unit tests, validates all skill packages and UI metadata, checks version alignment and local links, scans for private absolute paths, validates behavioural cases, and validates every committed example according to its manifest status.
- For release-facing integration checks, install the pinned development validators and run:
- ```bash
- python -m pip install -r requirements-dev.txt
- make integration
- ```
- This adds the official Agent Skills reference validator, JSON Schema validation, and a pinned community-installer discovery smoke test. Prepare a clean behavioural eval without leaking the judge criteria into the performer request:
- ```bash
- python scripts/eval_harness.py list
- python scripts/eval_harness.py prepare single-landscape-weather --output ./tmp/eval-run
- ```
- - [Contributing](.github/CONTRIBUTING.md) — contribution quality bar
- - [`docs/architecture.md`](docs/architecture.md) — routing, skill boundaries, and extension seams
- - [`docs/evaluation.md`](docs/evaluation.md) — automated, artifact, and visual evaluation
- - [`docs/compatibility.md`](docs/compatibility.md) — tested hosts and capability fallbacks
- - [`docs/repository-benchmark.md`](docs/repository-benchmark.md) — patterns reviewed and adoption decisions
- - [`docs/maintainer-guide.md`](docs/maintainer-guide.md) — versioning and release checklist
- - [Security policy](.github/SECURITY.md) — trust model and private vulnerability reporting
- ### Road to 1.0
- - add a consented real-photo preservation benchmark and a second multi-material object benchmark;
- - complete end-to-end rendering tests in two additional Agent Skills hosts;
- - keep an explicit asset record with every visual example;
- - publish reviewer-completed behavioural eval records for major visual-kernel changes;
- - keep the visual kernel narrow while expanding subjects through evidence, not adjective lists.
- ## Community
- Made something with Paper Signal? Share the image, input or prompt, host, and version in [**Made with Paper Signal**](https://github.com/jiahuiqu17/paper-signal/discussions/4). Once real third-party submissions arrive, selected work with explicit permission can become a credited Community Gallery.
- ## Acknowledgements
- Paper Signal is independently authored and informed by the open workflows in [`baoyu-xhs-images`](https://github.com/JimLiu/baoyu-skills) and [GC Minimal Zine Poster](https://github.com/LiamGvchi/gc-minimal-zine-poster), both MIT-licensed. Their code and generated examples are not vendored. See the [acknowledgements](docs/acknowledgements.md).
- ## License
- MIT © 2026 Paper Signal contributors. Generated-image rights and backend terms depend on the runtime and source assets used for each project.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.