Skip to content
Back to search

opency

MarketplaceWorks with Claude CodeGitHub

Your agency's content team, inside your agent. An open-source skill and MCP server that turn Claude Code, Claude Desktop, Cursor, Codex or any MCP client into account manager, art director, designer…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/damianricobelli--opency/badge.svg)](/listings/damianricobelli--opency)

HTML

<a href="/listings/damianricobelli--opency"><img src="/api/listings/damianricobelli--opency/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.

Requires Node 20.9+ and Chrome (or the Chromium that `setup` downloads). For video, ffmpeg.

**See it first** — renders a demo carousel on your machine, nothing to configure:

npx @opency/cli demo

**1. The MCP server** — the tools your agent uses. In Claude Code:

claude mcp add opency -- npx -y @opency/cli mcp

<details> <summary>Claude Desktop, Cursor and any other MCP client</summary>

{
  "mcpServers": {
    "opency": {
      "command": "npx",
      "args": ["-y", "@opency/cli", "mcp"]
    }
  }
}

</details>

**2. The skill** — the craft: how to brief, write, compose and review.

npx skills add damianricobelli/opency

That is all. There is no workspace to set up: your brands and pieces live in `~/opency`, created on first use. To keep them somewhere else (a client's repo, a shared drive), run `npx @opency/cli init <folder>` there, or set `OPENCY_HOME`.

<details> <summary>As a Claude Code plugin (skill + MCP server + reviewer subagent in one step)</summary>

/plugin marketplace add damianricobelli/opency
/plugin install opency@opency

</details>

Then ask your agent:

> Load my brand from mysite.com.<br> > Build a campaign for the December launch.<br> > Carousel about automating reports, 6 slides, for Thursday.<br> > Adapt it to a story and make the video.<br> > Propose this week's content plan.

The agent answers in your language and writes the copy in the brand's language.

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.

.claude-plugin/marketplace.json · Manifest · 15 lines
  1. {
  2. "name": "opency",
  3. "owner": {
  4. "name": "Damián Ricobelli",
  5. "url": "https://github.com/damianricobelli"
  6. },
  7. "plugins": [
  8. {
  9. "name": "opency",
  10. "source": "./",
  11. "description": "Skill + MCP server: interactive briefs, brand kits, campaigns, stock photos (Openverse, Unsplash) and pixel-level quality checks.",
  12. "category": "marketing"
  13. }
  14. ]
  15. }
README.md · README · 383 lines
  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset=".github/assets/hero-dark.webp">
  4. <img src=".github/assets/hero-light.webp" alt="opency: your agency's content team, inside your agent" width="100%">
  5. </picture>
  6. </p>
  7. <h1 align="center">opency</h1>
  8. <p align="center">
  9. <strong>Your agency's content team, inside your agent.</strong><br>
  10. An open-source skill and MCP server that turn Claude Code, Claude Desktop, Cursor, Codex or any MCP client<br>
  11. into account manager, art director, designer and copywriter.
  12. </p>
  13. <p align="center">
  14. <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-111111"></a>
  15. <img alt="Node 20.9+" src="https://img.shields.io/badge/node-%E2%89%A520.9-111111">
  16. <img alt="MCP server" src="https://img.shields.io/badge/MCP-server-e8502a">
  17. <img alt="Agent skill" src="https://img.shields.io/badge/agent-skill-e8502a">
  18. <img alt="Local first" src="https://img.shields.io/badge/local--first-no%20account-111111">
  19. </p>
  20. <p align="center">
  21. <a href="#install">Install</a> ·
  22. <a href="#how-it-works">How it works</a> ·
  23. <a href="#what-the-render-checks">Quality control</a> ·
  24. <a href="#mcp-tools">MCP tools</a> ·
  25. <a href="#commands">Commands</a>
  26. </p>
  27. ---
  28. It asks what you want to say before it designs. It builds the campaign with your brand's identity. It finds photos on Openverse and Unsplash. It renders every piece and checks it at the pixel level. **You approve what ships.**
  29. Everything runs on your machine and everything is a file you own: HTML/CSS per slide, PNG/JPG/PDF/MP4 ready to upload. No account, no download limits, no SaaS.
  30. <p align="center">
  31. <img src=".github/assets/example-carousel.webp" alt="A five-slide carousel produced by opency: cover, statement, steps, comparison and closer" width="100%">
  32. <br><sub>A carousel straight out of <code>npx @opency/cli render</code>: five slides, one material, zero errors.</sub>
  33. </p>
  34. ## Why opency
  35. | | |
  36. |---|---|
  37. | **It asks first** | A short, interactive brief before any campaign: what you want to get across, to whom, where and by when. It never asks what it can read from your brand or your website. |
  38. | **It stays on brand** | Colors, typefaces, logo and voice are read from your site and stored as tokens. Every piece is built from them, never from scratch. |
  39. | **It checks its own work** | Contrast, safe zones, widows, cropped faces and unsourced figures are measured on the actual render, then a fresh subagent reviews the result cold. |
  40. | **It is yours** | Open source, local-first, plain files in a folder. Several brands per workspace, ready for agencies from day one. |
  41. ## Install
  42. Requires Node 20.9+ and Chrome (or the Chromium that `setup` downloads). For video, ffmpeg.
  43. **See it first** — renders a demo carousel on your machine, nothing to configure:
  44. ```bash
  45. npx @opency/cli demo
  46. ```
  47. **1. The MCP server** — the tools your agent uses. In Claude Code:
  48. ```bash
  49. claude mcp add opency -- npx -y @opency/cli mcp
  50. ```
  51. <details>
  52. <summary>Claude Desktop, Cursor and any other MCP client</summary>
  53. ```json
  54. {
  55. "mcpServers": {
  56. "opency": {
  57. "command": "npx",
  58. "args": ["-y", "@opency/cli", "mcp"]
  59. }
  60. }
  61. }
  62. ```
  63. </details>
  64. **2. The skill** — the craft: how to brief, write, compose and review.
  65. ```bash
  66. npx skills add damianricobelli/opency
  67. ```
  68. That is all. There is no workspace to set up: your brands and pieces live in `~/opency`, created on first use. To keep them somewhere else (a client's repo, a shared drive), run `npx @opency/cli init <folder>` there, or set `OPENCY_HOME`.
  69. <details>
  70. <summary>As a Claude Code plugin (skill + MCP server + reviewer subagent in one step)</summary>
  71. ```
  72. /plugin marketplace add damianricobelli/opency
  73. /plugin install opency@opency
  74. ```
  75. </details>
  76. Then ask your agent:
  77. > Load my brand from mysite.com.<br>
  78. > Build a campaign for the December launch.<br>
  79. > Carousel about automating reports, 6 slides, for Thursday.<br>
  80. > Adapt it to a story and make the video.<br>
  81. > Propose this week's content plan.
  82. The agent answers in your language and writes the copy in the brand's language.
  83. ## How it works
  84. ```mermaid
  85. flowchart LR
  86. A([Your request]) --> B[Brief]
  87. B --> C[Brand kit]
  88. C --> D[Campaign plan]
  89. D --> E[Copy]
  90. E --> F[Images]
  91. F --> G[Compose<br/>HTML/CSS]
  92. G --> H{Render +<br/>quality checks}
  93. H -- errors --> G
  94. H -- clean --> I[Cold review]
  95. I --> J([You approve])
  96. ```
  97. ### 1. It asks before it designs
  98. <p align="center">
  99. <picture>
  100. <source media="(prefers-color-scheme: dark)" srcset=".github/assets/brief-dark.webp">
  101. <img src=".github/assets/brief-light.webp" alt="The interactive brief: the agent asks what you want to convey, audience, channels and verified facts, then produces the piece" width="100%">
  102. </picture>
  103. </p>
  104. Before a campaign or a new brand, the agent runs a brief a few questions at a time: what you want to get across, objective, audience, offer, tone, channels, dates, images. What it can infer from the brand or the website, it proposes instead of asking. Over MCP the questions arrive as a form (`brief_interview` uses MCP elicitation when the client supports it), in the language you are writing in: the brief ships in English and Spanish.
  105. The one question it never skips: **what do you want to get across?** The answer becomes the thesis every piece has to prove.
  106. ### 2. It learns your brand
  107. A new brand is set up in four short chapters, in the chat, and it can stop and resume anywhere:
  108. 1. **The brand.** Its name, and its website if it has one.
  109. 2. **Identity.** From the website, from one of eight house presets, or from the colors and typefaces you give. The agent proposes seven color roles and three type families, repairs any combination that fails contrast, installs open-licensed typefaces by name, saves the logo — and shows you a **brand board** (palette, contrast, typefaces, three sample slides) to say yes or no to.
  110. 3. **The goal.** What your content should achieve and who it is for, as choices with suggestions, not an essay.
  111. 4. **Your first piece.** Three ideas that fit that goal; you pick one and it is designed.
  112. ```text
  113. > Set up my brand: Kumo Café, kumocafe.com
  114. ```
  115. That one line is enough to get to the board. Several brands can live in one workspace, and the long brief (voice rules, pillars, verified facts) is there for when you want more depth.
  116. ### 3. It plans, then builds
  117. Each piece of the campaign proves the message from a different angle, and you approve the plan before anything is designed.
  118. The agent does not write HTML and does not pick layouts. It says what each slide has to say — its job, its claim, its proof — plus one design direction, and a deterministic compositor chooses the layout of every slide and explains why:
  119. ```json
  120. { "direction": { "thesis": "Cold brew is specialty coffee too", "dominantMode": "type", "pattern": "grid" },
  121. "slides": [
  122. { "role": "hook", "claim": "Cold is not lazy.", "labels": ["Summer menu", "No. 3"] },
  123. { "role": "how", "claim": "How we brew it",
  124. "proof": { "kind": "steps", "items": ["Coarse grind.", "Cold water, 18 hours.", "Filtered twice."] } },
  125. { "role": "proof", "claim": "hours in every glass", "proof": { "kind": "number", "value": "18" } },
  126. { "role": "close", "claim": "Try it this week.", "cta": "Order a cold brew at the bar" } ] }
  127. ```
  128. ```text
  129. 01 type_poster on-secondary drawn for a hook slide; the copy fills the layout as drawn
  130. 02 steps on-bg drawn for a how slide; turns light after a dark slide
  131. 03 type_number on-primary drawn for a proof slide; a peak that contrasts with what comes before
  132. 04 type_closer on-secondary drawn for a close slide
  133. ```
  134. A recipe is eligible only when it shows exactly what the slide sent and every text fits its character budget; among the eligible ones the compositor scores copy fit, the slide's job, the direction, rhythm (no layout twice in a row, no three slides of one tone in a row), one hero gesture per piece, a readable accent color, and what you liked or rejected before. A photo is used only when its crop is known to be safe. No model runs in that step and nothing is invented: when a text fits nowhere, nothing is created and the answer says what to change — never smaller type.
  135. - **Another version.** `piece_variant` recomposes the same words in another structure and keeps the previous one a restore away.
  136. - **It learns your taste.** "I love this one" and "not like this" are recorded in your words (`piece_feedback`), along with the references you hand over (`inspiration_add`). The next pieces of that brand are composed with them.
  137. - **23 recipes over 20 tested layouts** — type and photo covers, posters, a chat conversation, a dictionary entry, a prompt box, an event poster, steps, comparisons, data, product windows — plus five house backdrops. Explicit layouts (`piece_compose`) and raw HTML stay available for the idea no recipe covers.
  138. <p align="center">
  139. <img src=".github/assets/layouts.webp" alt="The slide layouts: type cover, photo cover, statement, big number, steps, comparison, photo card, data bars, testimonial, closer, news cards, app window, logo grid, co-brand, poster, chat, duotone photo, definition, prompt and event" width="100%">
  140. </p>
  141. Formats 4:5, 1:1, 9:16 and 16:9. Captions per network, alt text, PDF for LinkedIn and MP4 video.
  142. ### 4. It finds the right photo
  143. Your own photos come first. Then stock: one search queries the available providers in parallel, the agent **looks at the previews**, imports only the chosen photo at full resolution and records author and license. It marks the focal point and the faces so they are never cropped or covered by text.
  144. | Provider | Key | License |
  145. |---|---|---|
  146. | [Openverse](https://openverse.org) | None needed | Only CC0, public domain and CC BY (attribution is recorded) |
  147. | [Unsplash](https://unsplash.com/developers) | Your own Access Key (free) | Unsplash License |
  148. Openverse works out of the box. Unsplash is optional and uses **your own** account — opency ships no keys:
  149. ```bash
  150. npx @opency/cli stock connect unsplash
  151. ```
  152. It walks you through creating a free app in your Unsplash account, asks for the Access Key with hidden input, checks it and saves it to the workspace's git-ignored `.env`. Requests count against your own quota (50 per hour on a demo app).
  153. ### 5. It measures the render, not the intent
  154. <p align="center">
  155. <picture>
  156. <source media="(prefers-color-scheme: dark)" srcset=".github/assets/quality-dark.webp">
  157. <img src=".github/assets/quality-light.webp" alt="Quality control: contrast over photos, safe zones, widows, face crops, unsourced figures and AI-sounding phrases" width="100%">
  158. </picture>
  159. </p>
  160. Every piece is laid out by a real browser engine — the same text shaping, kerning and color math a designer sees — rasterized at twice the size and reduced with Lanczos for clean type edges, then checked pixel by pixel. Beyond contrast, crops and overflow, the checks look for what makes a piece read as generated: no element leading the slide, empty boxes, three slides of one layout in a row, one background from end to end, a carousel made only of sentences. Fixes that cannot change meaning or design — a headline's line breaks, the logo variant for the surface, mixed textures — are applied automatically; everything else is reported with what to do. Nothing is delivered with errors, and passing checks is not aesthetic approval — so a subagent that did not see the process reviews the contact sheet cold and returns up to 5 findings.
  161. ### 6. You decide
  162. opency never publishes on its own. When a piece is ready:
  163. - **Review page.** One self-contained HTML file with the slides, captions and alt text. Open it or forward it to your client: no account, no server.
  164. - **Live preview.** A local page where you double-click any text to correct it; the agent treats your edits as approved.
  165. - **Approval.** Recorded only when you say yes.
  166. - **Delivery folder.** Numbered images, one caption file per network, the alt text and a checklist that flags captions over a network's limit and photo credits that are still missing.
  167. ## What the render checks
  168. - **Pixel-level contrast**, including over photos and gradients, and logo contrast against its background.
  169. - **Text:** headline widows, overlaps, clipping, sizes unreadable on a phone and each layout's character budget.
  170. - **Zones:** safe area and the strip each network's UI covers.
  171. - **Composition:** content crammed or sunk, dead space and too much accent color.
  172. - **Consistency across slides:** a bottom bar that moves, mixed textures, the same layout repeated.
  173. - **Photos:** upscaled beyond their resolution, crops that cut faces, text over the subject, unregistered or vetoed images.
  174. - **Brand:** colors outside the tokens and fonts that failed to load.
  175. - **Copy:** "AI-sounding" phrases, mixed form of address, subheads that repeat the headline, figures without a source (checked one by one), filler hashtags, generic CTAs, per-network limits and missing alt text.
  176. <details>
  177. <summary>What a report looks like when things go wrong</summary>
  178. An excerpt of the real report for the deliberately broken fixture used in the test suite:
  179. ```
  180. # Quality report — defects
  181. 4:5 · 1 slide(s) · ×1 · 7 errors · 11 warnings
  182. ## Slide 1 (flat)
  183. - warning `outside_safe_area` #out — text outside the safe area
  184. - warning `illegible_text_size` #tiny — 14 px on canvas = 5.1 pt on a phone (min. 10.5)
  185. - **ERROR** `headline_orphan` #headline — last line has a single word: "sola"
  186. - **ERROR** `critical_overlap` #a — overlaps #b
  187. - **ERROR** `external_image` img — external image: download it into assets/ and register it
  188. - **ERROR** `placeholder_left` — {{…}} placeholders left unfilled
  189. - warning `over_budget` #headline — 43 characters; this layout is designed for ~20
  190. - warning `unreadable_contrast` #low — contrast 4.18:1 (min. 4.5:1)
  191. - warning `brand_literal_color` — colors outside tokens: #777777
  192. ## Copy and captions
  193. - **ERROR** `unsourced_figure` slide 1 #claim — "40%": unsourced figure
  194. - warning `copy_too_many_hashtags` caption instagram — 4 hashtags (max. 3)
  195. - warning `copy_generic_cta` caption instagram — generic CTA: name the object (what, where, how)
  196. - warning `missing_alt_text` slides 1 — missing alt text
  197. ```
  198. </details>
  199. ## What you get
  200. A workspace is a folder of plain files. Nothing is locked in a database.
  201. ```
  202. my-agency/
  203. ├── AGENTS.md · references/ the agent's instructions
  204. ├── templates/ base.css and the 20 layouts
  205. └── brands/
  206. └── acme/
  207. ├── brand.json form of address, logos, pillars, verified facts
  208. ├── brand-kit.md voice, color roles, standing instructions
  209. ├── tokens.css the actual colors, typefaces and scale
  210. ├── assets/ logos, photos, stock, fonts + assets.json
  211. ├── campaigns/winter/ brief.json, brief.md and the piece plan
  212. └── pieces/2026-12-01-launch/
  213. ├── piece.json direction, copy, captions, sources, history
  214. ├── slide-01.html … one HTML file per slide
  215. ├── versions/ saved versions, no git required
  216. └── render/ slide-NN.png/jpg, contact-sheet.png, carousel.pdf,
  217. caption-*.txt, alt-text.txt, report.md
  218. ```
  219. ## MCP tools
  220. | Group | Tools |
  221. |---|---|
  222. | Start | `workspace_status` · `demo` · `doctor` · `skill_guide` · `workspace_init` |
  223. | First-run setup | `onboarding_status` · `onboarding_start` · `brand_identity` · `brand_presets` · `brand_board` · `piece_ideas` |
  224. | Brand | `brand_get` · `brand_create` · `brand_use` · `brand_import_site` · `brand_fonts` · `brand_check` · `brand_write` |
  225. | Brief | `brief_questions` · `brief_interview` |
  226. | Campaigns | `campaign_create` · `campaign_brief` · `campaign_plan` · `campaign_status` · `campaign_list` |
  227. | Images | `stock_status` · `stock_search` · `stock_import` · `asset_add` · `asset_analyze` · `asset_view` · `asset_list` · `asset_veto` |
  228. | Design | `recipes_list` · `piece_design` · `piece_variant` · `piece_edit` · `piece_repair` · `piece_read` · `piece_list` |
  229. | Taste | `piece_feedback` · `inspiration_add` · `taste_get` |
  230. | Explicit layouts | `layouts_list` · `piece_compose` |
  231. | Review and delivery | `piece_preview` · `piece_handoff` · `piece_view` · `piece_render` |
  232. | Reuse | `piece_duplicate` · `template` · `piece_version` · `piece_motion` |
  233. | Raw HTML | `piece_create` · `piece_write` |
  234. | Feed and results | `feed_check` · `results_add` · `results_summary` |
  235. Also: the skill's instructions as resources (`opency://guide/…`) and three prompts (`new-campaign`, `load-brand`, `weekly-plan`).
  236. - **One call from intent to contact sheet.** `piece_design` takes what each slide has to say, chooses the layouts, builds them, renders and returns the recipes with their reasons, the report and the image.
  237. - **Tools return images, not just text.** The agent sees the contact sheet and the stock previews before it decides.
  238. - **No setup step.** The first call creates the workspace and says where; `doctor` can download the render browser.
  239. - **One implementation.** Every tool runs the same script as the CLI, so MCP and terminal never drift apart.
  240. - **Guardrails built in.** Approval and changes to a brand that already has pieces need the user's confirmation, slides cannot contain scripts, downloads reject private addresses, and API keys never travel through the chat.
  241. ## Commands
  242. | Command | What it does |
  243. |---|---|
  244. | `npx @opency/cli start` | Where your brand's setup stands and what comes next |
  245. | `npx @opency/cli onboard begin / set / presets / identity / board / ideas` | The setup steps: create the brand, build its identity, render the brand board, propose a first piece |
  246. | `npx @opency/cli demo` | Renders the demo carousel |
  247. | `npx @opency/cli init [folder]` | Creates a workspace in a specific folder (the default is `~/opency`) |
  248. | `npx @opency/cli setup` · `doctor` | Installs the render browser · checks the environment |
  249. | `npx @opency/cli mcp` | MCP server (stdio) |
  250. | `npx @opency/cli brief questions [brand\|campaign\|piece]` | The questions of each brief |
  251. | `npx @opency/cli campaign new / brief / plan / status / list` | Campaigns |
  252. | `npx @opency/cli brand list / use / new / import <url> / check` | Brands |
  253. | `npx @opency/cli fonts search / add / list` | Install the brand's typefaces by name |
  254. | `npx @opency/cli compose design <slug> --spec intent.json` | Design a piece from intent: the compositor picks the layouts (`--dry` shows the plan) |
  255. | `npx @opency/cli compose variant <piece>` | Another version: same words, another structure |
  256. | `npx @opency/cli compose recipes / layouts / new / edit / slots` | Recipes; pieces from explicit layouts |
  257. | `npx @opency/cli taste feedback / inspire / show / forget` | Reviews and references the compositor learns from |
  258. | `npx @opency/cli repair <piece>` | Apply the safe fixes from the last render |
  259. | `npx @opency/cli handoff review / status / package <piece>` | Review page, approval, delivery folder |
  260. | `npx @opency/cli template save / list` | Brand templates |
  261. | `npx @opency/cli new <slug> --layouts cover-type,steps,closer` | New piece with sample copy (`--campaign`, `--from`, `--format`, `--language`, `--template`) |
  262. | `npx @opency/cli render <piece>` | PNG, JPG, contact sheet, captions and report (`--pdf`, `--scale 2`) |
  263. | `npx @opency/cli dev <piece>` | Live preview with editable text |
  264. | `npx @opency/cli version <piece> save / list / diff / restore` | Versions, without relying on git |
  265. | `npx @opency/cli motion <piece> --slides all --audio track.mp3` | MP4 video |
  266. | `npx @opency/cli assets add / stock / stock-import / analyze / veto / list` | Images |
  267. | `npx @opency/cli stock status / connect unsplash / disconnect unsplash` | Stock providers |
  268. | `npx @opency/cli feed` · `results` | Feed rhythm · what performed best |
  269. All of them accept `--brand <slug>`. The workspace is the nearest folder that contains `brands/`, else `OPENCY_HOME`, else `~/opency`.
  270. ## Known limits
  271. - **Publishing:** opency does not publish to social networks. It leaves everything ready in `render/`, or uses the publishing MCP you connect (Buffer, Metricool, Postiz…), with your confirmation on every send.
  272. - **Image generation:** no model is included. It works with your photos, stock providers and typography.
  273. - **Unsplash:** implemented against its API, but the automated tests only cover Openverse (no key required).
  274. - **Photos with people:** the face-crop check depends on the agent marking the regions correctly.
  275. - **Video:** no automatic subtitles or voice-over.
  276. - **Copy linter:** the cliché phrase lists cover English and Spanish. Other languages get the structural checks only (figures without a source, limits, alt text, repeated subheads).
  277. - **Typefaces:** installed by name only when they are open-licensed (Fontsource). A commercial typeface needs its files from you.
  278. - **Review page:** a file you send, not a hosted link with comments.
  279. ## Development
  280. ```bash
  281. git clone https://github.com/damianricobelli/opency
  282. cd opency
  283. pnpm install
  284. pnpm test # engine + MCP server
  285. OPENCY_TEST_NETWORK=1 pnpm test # adds the live stock test
  286. ```
  287. | Path | What it is |
  288. |---|---|
  289. | `scripts/` | The engine: each file is a command |
  290. | `mcp/server.mjs` | The MCP server |
  291. | `skills/opency/` | `SKILL.md` and its references: what the agent reads |
  292. | `templates/` | `base.css` and the layouts |
  293. | `web/` | The landing page (TanStack Start) |
  294. Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md).
  295. ## License
  296. [MIT](LICENSE). The fonts bundled with the demo brand are under the SIL Open Font License.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.