
modern-web-guidance
Browser compatibility, platform guidance and Chrome extension development.
- version
- 1.0.0
- GitHub stars
- 1.2K
Add marketplace
/plugin marketplace add fcakyon/claude-codex-settingsRun it inside Claude Code once, then install the plugin below.
Install
/plugin install modern-web-guidance@claude-settingsRun it inside Claude Code after adding the marketplace.
Files
Discovered from sourceChrome Extensions
Build production-quality Chrome extensions using Manifest V3 and publish them to the Chrome Web Store.
Part 1 — Building Extensions
Mandatory Rules
These address the most common causes of broken extensions. Violating any produces a non-functional build.
1. Icons: only reference files you create — or omit icons entirely
❌ BROKEN — referencing files that don't exist or reusing one file for all sizes:
"icons": { "16": "icon.png", "48": "icon.png", "128": "icon.png" }
✅ CORRECT — each size is a separate file at the correct pixel dimensions:
"icons": { "16": "icons/icon-16.png", "48": "icons/icon-48.png", "128": "icons/icon-128.png" }
(where icon-16.png is 16×16px, icon-48.png is 48×48px, icon-128.png is 128×128px)
✅ ALSO CORRECT — omit icons from manifest if you cannot generate real PNG files:
(just remove the "icons" and "default_icon" fields — Chrome uses a default icon)
If you include icon references, you MUST create the actual image files. Generate them with a script (see references/extensions/icons.md) or leave them out. Never reference non-existent files.
2. Side panel: you MUST provide a way to open it
Defining "side_panel": {"default_path": "..."} does NOT make it openable. Add a trigger:
// In service-worker.js — open side panel on extension icon click
// IMPORTANT: chrome.action.onClicked ONLY fires when there is NO default_popup
chrome.action.onClicked.addListener(async (tab) => {
await chrome.sidePanel.open({ windowId: tab.windowId });
});
If the extension has both a popup AND side panel, add a button in the popup that calls chrome.sidePanel.open(). Alternatively, use chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true }) — but the property is openPanelOnActionClick, NOT openPanelOnActionIconClick; the "Icon" variant causes a synchronous TypeError that silently aborts the service worker. Do NOT also define default_popup when using setPanelBehavior. See references/extensions/side-panel.md.
3. Code execution: sandboxed iframes ONLY
Extension CSP blocks eval(), new Function(), inline <script> in all extension pages.
// ❌ BROKEN — direct iframe DOM access throws SecurityError
iframe.contentDocument.write(html);
// ❌ BROKEN — eval in extension page
eval(userCode); // CSP blocks this
// ✅ OPTION A: Sandbox in manifest + postMessage
// manifest.json: { "sandbox": { "pages": ["sandbox.html"] } }
iframe.contentWindow.postMessage({ html, css, js }, '*');
// sandbox.html receives and runs:
window.addEventListener('message', (e) => { eval(e.data.js); /* allowed in sandbox */ });
// ✅ OPTION B: Blob URL (creates separate origin, bypasses extension CSP)
iframe.src = URL.createObjectURL(new Blob([doc], { type: 'text/html' }));
// ✅ OPTION C: srcdoc
iframe.srcdoc = `<style>${css}</style>${html}<script>${js}<\/script>`;
See references/extensions/csp-sandbox.md for full details.
4. tab.url requires the tabs permission
Without it, tab.url silently returns undefined — no error thrown. See
references/extensions/permissions.md.
5. Always use async/await — never .then() chains
// ❌ BAD
chrome.tabs.query({active: true, currentWindow: true}).then(tabs => {
chrome.scripting.executeScript({target: {tabId: tabs[0].id}, files: ['content.js']}).then(() => {});
});
// ✅ GOOD
const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
await chrome.scripting.executeScript({ target: { tabId: tab.id }, files: ['content.js'] });
For runtime.onMessage listeners that do async work:
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
(async () => {
const data = await chrome.storage.local.get('key');
sendResponse({ data });
})();
return true; // keeps channel open
});
6. Content scripts: don't block the main thread
When modifying many DOM elements, batch with requestAnimationFrame and yield between batches:
async function highlightAll(elements) {
const BATCH = 20;
for (let i = 0; i < elements.length; i += BATCH) {
await new Promise(r => requestAnimationFrame(() => {
elements.slice(i, i + BATCH).forEach(el => el.style.backgroundColor = 'yellow');
r();
}));
if (globalThis.scheduler?.yield) await scheduler.yield();
}
}
See references/extensions/content-scripts.md.
7. Service workers are ephemeral — never store state in variables
// ❌ BROKEN — state lost when SW terminates (~30s of inactivity)
let count = 0;
chrome.tabs.onUpdated.addListener(() => { count++; });
// ✅ CORRECT — persist in chrome.storage, read on every event
chrome.tabs.onUpdated.addListener(async (tabId, changeInfo) => {
if (changeInfo.status !== 'complete') return;
const { count = 0 } = await chrome.storage.local.get('count');
await chrome.storage.local.set({ count: count + 1 });
await chrome.action.setBadgeText({ text: String(count + 1) });
});
Use chrome.alarms instead of setTimeout/setInterval. See references/extensions/service-worker.md.
8. chrome.identity: extension ID differs between dev and production
When using Google sign-in, the OAuth client_id is tied to a specific extension ID. The ID changes between unpacked development and the Chrome Web Store.
To stabilize the ID during development, add a "key" field to manifest.json:
- Pack the extension once (chrome://extensions → Pack)
- Extract the public key from the .crx
- Add
"key": "MIIBIjANBgkqh..."to manifest.json
Always document: "After publishing to the Chrome Web Store, update the OAuth client with the store-assigned extension ID." See references/extensions/auth-identity.md.
9. Context menus: show user feedback after action
When a context menu item performs an action (save, copy, etc.), confirm it to the user. Use a notification, badge flash, or injected toast — don't let actions happen silently. See references/extensions/context-menus.md for a complete toast implementation.
10. Prompt API: available in service workers, popup, and side panel
The LanguageModel API works in all extension contexts — service worker, popup, and side panel — with no additional manifest permissions required. Extensions also get LanguageModel.params(), which is unavailable on the web:
const params = await LanguageModel.params();
// { defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2 }
For general Prompt API patterns (availability checks, session creation, streaming), use the modern-web-guidance skill. See references/extensions/prompt-api.md for the extension-specific wiring example.
11. chrome.action API requires action in manifest
Using chrome.action.setBadgeText, chrome.action.setIcon, or chrome.action.onClicked requires
an "action" key in manifest.json — even if it's empty. Without it, chrome.action is undefined.
// ❌ BROKEN — manifest has no "action" key
await chrome.action.setBadgeText({ text: '5' });
// TypeError: Cannot read properties of undefined (reading 'setBadgeText')
// ✅ FIX — add "action" to manifest.json (at minimum an empty object)
{ "action": {} }
// or with a popup:
{ "action": { "default_popup": "popup/popup.html" } }
12. activeTab only works on direct user gestures — not from side panels
activeTab grants temporary access to the current tab ONLY on a direct user gesture (action
icon click, context menu item, keyboard shortcut, omnibox suggestion) — NOT from a button click
inside a side panel or popup. Use tabs + host_permissions instead. See
references/extensions/permissions.md and references/extensions/side-panel.md.
13. DevTools panel URLs are relative to the extension root
When creating a DevTools panel, the panel HTML path is relative to the extension root, NOT
relative to the devtools page that calls chrome.devtools.panels.create().
// ❌ BROKEN — path relative to devtools/ directory
chrome.devtools.panels.create("My Panel", "", "panel/panel.html");
// ✅ CORRECT — full path from extension root
chrome.devtools.panels.create("My Panel", "", "devtools/panel/panel.html");
See references/extensions/devtools.md.
14. Offscreen documents have NO access to most chrome.* APIs
Offscreen documents (chrome.offscreen) are severely restricted. Most chrome.* APIs
are unavailable, including chrome.downloads, chrome.tabs, chrome.action, and others.
// ❌ BROKEN — chrome.downloads is undefined in offscreen documents
chrome.downloads.download({ url, filename: 'recording.webm' }); // TypeError
// ❌ BROKEN — chrome.action is undefined in offscreen documents
chrome.action.setBadgeText({ text: 'REC' }); // TypeError
The only APIs available in offscreen documents are:
chrome.runtime.sendMessage/chrome.runtime.onMessagechrome.runtime.getURL- Standard Web APIs (DOM, fetch, MediaRecorder, Canvas, Web Audio, etc.)
Rule of thumb: Offscreen documents do the Web API work (recording, parsing, audio). The service worker does all chrome.* API work (downloads, badge updates, notifications). Use chrome.runtime.sendMessage to bridge between them. See references/extensions/message-passing.md.
15. Notifications and badge icons must reference real image files
chrome.notifications.create() requires a valid iconUrl pointing to an actual image file.
If the file doesn't exist or the path is wrong, the call fails with "Unable to download all specified images."
// ❌ BROKEN — icon file doesn't exist
chrome.notifications.create('reminder', {
type: 'basic',
iconUrl: 'icons/icon-128.png', // File not in extension!
title: 'Reminder',
message: 'Time is up!'
});
// ✅ Generate a data URL at runtime via OffscreenCanvas — no file needed.
// See `references/extensions/icons.md` for a reusable implementation.
const iconUrl = await getIconDataUrl();
chrome.notifications.create('reminder', { type: 'basic', iconUrl, title: 'Reminder', message: 'Time is up!' });
This applies to ALL image references in chrome.* APIs — notifications, chrome.action.setIcon,
context menu icons, etc. If you reference a file, it must exist.
16. Tab capture: guard against double-start with state locking
chrome.tabCapture.getMediaStreamId() fails with "Cannot capture a tab with an active stream"
if called while a previous capture is still active. Fast double-clicks on the extension icon
easily trigger this. Use explicit state locking:
// ❌ BROKEN — no guard against rapid clicks
let isRecording = false;
chrome.action.onClicked.addListener(async (tab) => {
if (isRecording) { stopRecording(); isRecording = false; }
else { isRecording = true; startRecording(tab); } // Second click = "active stream" error
});
// ✅ CORRECT — use transitional states to lock out concurrent operations
// State machine: 'idle' → 'starting' → 'recording' → 'stopping' → 'idle'
// Store state in chrome.storage.session (survives SW restart, cleared on browser close)
chrome.action.onClicked.addListener(async (tab) => {
const { recordingState = 'idle' } = await chrome.storage.session.get('recordingState');
if (recordingState === 'starting' || recordingState === 'stopping') return;
if (recordingState === 'idle') {
await chrome.storage.session.set({ recordingState: 'starting' });
try {
await startRecording(tab);
await chrome.storage.session.set({ recordingState: 'recording' });
await chrome.action.setBadgeText({ text: 'REC' });
await chrome.action.setBadgeBackgroundColor({ color: '#FF0000' });
} catch (err) {
console.error('Failed to start recording:', err);
await chrome.storage.session.set({ recordingState: 'idle' });
}
} else if (recordingState === 'recording') {
await chrome.storage.session.set({ recordingState: 'stopping' });
try { await stopRecording(); }
finally {
await chrome.storage.session.set({ recordingState: 'idle' });
await chrome.action.setBadgeText({ text: '' });
}
}
});
This pattern applies to any chrome API that manages exclusive resources:
chrome.tabCapture, chrome.desktopCapture, chrome.offscreen.createDocument (only one
offscreen document allowed at a time). See references/extensions/media-capture.md.
17. chrome.desktopCapture requires a target tab with URL access
When calling chrome.desktopCapture.chooseDesktopMedia() from a service worker, you must pass
the active tab as the targetTab parameter. The tab object must have its url field populated,
which requires the "tabs" permission.
// ❌ BROKEN — called without targetTab from service worker
chrome.desktopCapture.chooseDesktopMedia(['screen', 'window'], (streamId) => { ... });
// Error: "A target tab is required when called from a service worker context."
// ❌ BROKEN — tab doesn't have url field (missing "tabs" permission)
const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
chrome.desktopCapture.chooseDesktopMedia(['screen', 'window'], tab, (streamId) => { ... });
// Error: "targetTab doesn't have URL field set."
// ✅ CORRECT — "tabs" permission in manifest + pass tab object
// manifest.json: { "permissions": ["tabs", "desktopCapture"] }
const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
chrome.desktopCapture.chooseDesktopMedia(['screen', 'window'], tab, (streamId) => {
if (!streamId) return; // User cancelled
});
Note: Prefer chrome.tabCapture.getMediaStreamId() for tab-only recording. Use chrome.desktopCapture only when the user should choose which screen/window to capture. See references/extensions/media-capture.md.
18. User scripts: four non-obvious pitfalls
chrome.userScripts runs user-provided code at runtime. Use it for script managers and
user automation — not for extension-bundled scripts.
- API throws on property access if not enabled. Chrome 138+ requires the user to toggle "Allow User Scripts" on the extension's details page; Chrome < 138 requires Developer mode. Always call
isUserScriptsAvailable()before anychrome.userScripts.*call and show an error UI when it returns false. - Registered scripts are cleared on extension update. Persist configs in
chrome.storage; re-register them inruntime.onInstalledfor the"update"reason. - Messaging requires explicit opt-in. Call
configureWorld({ messaging: true })first; listen onruntime.onUserScriptMessage, notruntime.onMessage. ScriptSourceconstraint: eachjsentry must have exactly one ofcodeorfile.idconstraint: cannot start with_.
See references/extensions/user-scripts.md.
19. chrome.windows has NO .query() method — use getAll, getLastFocused, or getCurrent
Unlike chrome.tabs.query(), the chrome.windows API does NOT have a .query() method.
// ❌ BROKEN — chrome.windows.query does not exist
const windows = await chrome.windows.query({ focused: true });
// TypeError: chrome.windows.query is not a function
// ✅ CORRECT — use the right method for your need
const focused = await chrome.windows.getLastFocused({ populate: true });
const current = await chrome.windows.getCurrent({ populate: true });
const all = await chrome.windows.getAll({ populate: true });
chrome.windows methods: getAll, getLastFocused, getCurrent, get(windowId), create, update, remove. See references/extensions/tab-management.md.
20. chrome.permissions.request() in the service worker must be called with no await before it in the message listener
A user gesture from a UI context (side panel, popup) does propagate across chrome.runtime.sendMessage
to the service worker's onMessage listener — but only for that one synchronous turn. If the
listener does an await (even a short delay) before calling chrome.permissions.request(), the
gesture is gone and the call throws "This function must be called during a user gesture". Call
it as the first thing in the listener, with nothing awaited before it — see
references/extensions/permissions.md.
Always Manifest V3
Never generate Manifest V2 code.
background.service_workernotbackground.scriptschrome.actionnotchrome.browserActionchrome.scripting.executeScriptnotchrome.tabs.executeScripthost_permissionsis separate frompermissions- No inline scripts in HTML — use
<script src="file.js"> - No inline event handlers — use
addEventListener
Part 2 — Publishing to the Chrome Web Store
Manage CHROMEWEBSTORE.md — the single source of truth for all Chrome Web Store listing
metadata, permissions justifications, privacy disclosures, version history, and publishing
readiness for a Chrome extension project.
Core Workflow
Every time you touch a Chrome extension project in a way that affects its store presence,
update (or create) CHROMEWEBSTORE.md in the project root. The file tracks everything the
developer needs to fill out in the Chrome Developer Dashboard, so they can copy-paste from
a single doc instead of scrambling at publish time.
When to create CHROMEWEBSTORE.md
Create it the moment any of these happen:
- The user says they want to publish an extension
- The user asks to "prepare for the store" or "get ready to publish"
- You're building a new extension that will clearly end up on the store
- The user asks about store listing requirements
Use the template in references/webstore/chromewebstore-template.md as your starting point. Read it
before generating the file.
When to update CHROMEWEBSTORE.md
Update it whenever:
- User-facing changes: Bump the "Last Updated" date, update the feature list in descriptions, and add an entry to Version History
- manifest.json changes: If permissions, host_permissions, or content_scripts changed, update the Permissions Justification section — every permission needs a plain-English reason the review team can understand
- New release: Add a Version History entry with version number, date, and summary
- Privacy-relevant changes: If data collection, storage, or transmission changed, update the Privacy & Data Use section and the privacy policy
- Asset changes: If icons or UI changed, note which screenshots need refreshing
- Rejection response: If the user reports a CWS rejection, update the file with the fix and add a note to Version History
How to fill it out
For each section, pull information from the actual project files:
- Read
manifest.jsonto extract name, version, description, permissions, host_permissions - Scan the codebase for data collection (storage, fetch calls, analytics)
- Check for icon files and their dimensions
- Look at the extension's UI to understand features for the description
Write store-facing copy in a tone that is specific, honest, and benefit-oriented. The Chrome Web Store review team rejects vague descriptions. "Makes your life easier" will be rejected. "Highlights search results on any webpage and lets you save highlights to a local list" will pass.
Never mention implementation details. Users care what the extension does for them, not how it was built. Strip any mention of APIs, libraries, frameworks, or code patterns:
| ❌ Implementation detail (cut it) | ✅ User benefit (keep it) |
|---|---|
| "Uses a MutationObserver to detect page changes" | "Automatically detects new content as you browse" |
| "Built with custom elements and Shadow DOM" | "Works seamlessly without affecting page styles" |
| "Powered by a service worker for background processing" | "Runs quietly in the background without slowing your browser" |
| "Leverages the chrome.storage.sync API" | "Your settings sync across all your devices" |
| "Implements declarativeNetRequest for filtering" | "Blocks ads and trackers without reading your page content" |
CHROMEWEBSTORE.md Sections
Read references/webstore/chromewebstore-template.md before generating the file — it defines
what each section covers and how to fill it out. The highest-risk section is Permissions
Justification: write a specific plain-English reason per permission and per host_permission.
"Needed for the extension to work" will be rejected. Read references/webstore/privacy-policy.md
for guidance on generating a privacy policy.
Pre-Publish Checklist
Before submission, run through references/webstore/review-checklist.md. The most common
first-submission failures:
- Every permission and host_permission must have a specific justification (not "needed to work")
- Privacy policy URL must be live and match the data use disclosure form
- At least 1 screenshot at 1280×800 or 640×400
- ZIP must exclude
.git/,node_modules/,.env,CHROMEWEBSTORE.md
Store Listing Copy Guidelines
For copy guidelines and common rejection reasons, see references/webstore/store-listing.md.
Key rule: lead with function ("Highlights search terms on any webpage"), not feeling ("Enjoy
searching again").
Reference Files
For detailed API patterns and publishing guidance, read the relevant file BEFORE writing code or content:
| Topic | Reference |
|---|---|
| Permissions | references/extensions/permissions.md |
| Side panels | references/extensions/side-panel.md |
| Content scripts & DOM | references/extensions/content-scripts.md |
| Popups | references/extensions/popup-ui.md |
| Service worker lifetime | references/extensions/service-worker.md |
| Code execution & CSP | references/extensions/csp-sandbox.md |
| API calls | references/extensions/api-calling.md |
| Declarative Net Request | references/extensions/declarative-net-request.md |
| Chrome Prompt API | references/extensions/prompt-api.md |
| DevTools panels | references/extensions/devtools.md |
| Authentication | references/extensions/auth-identity.md |
| Context menus | references/extensions/context-menus.md |
| Omnibox | references/extensions/omnibox.md |
| Storage | references/extensions/storage.md |
| Tab & window management | references/extensions/tab-management.md |
| Tab/desktop capture | references/extensions/media-capture.md |
| User scripts | references/extensions/user-scripts.md |
| Message passing | references/extensions/message-passing.md |
| Icons | references/extensions/icons.md |
| CHROMEWEBSTORE.md template | references/webstore/chromewebstore-template.md |
| Privacy policy guidance | references/webstore/privacy-policy.md |
| Pre-publish review checklist | references/webstore/review-checklist.md |
| Store listing tips & rejections | references/webstore/store-listing.md |
Output Checklist
Verify EVERY item before delivering:
-
manifest_version: 3— no V2 APIs anywhere - All icon files referenced in manifest exist as real files with correct dimensions — or icons are omitted
- Side panel has an explicit open trigger (not just a manifest declaration)
- Code execution uses sandbox/blob/srcdoc — no
eval()in extension pages -
tabspermission declared iftab.urlortab.titleis accessed - All code uses
async/await— no.then()chains - Content scripts batch DOM updates with
requestAnimationFrame - Service worker stores NO state in global variables — uses
chrome.storage - No inline scripts or event handlers in HTML
- Context menu actions show user confirmation
-
"action": {}(or more) present in manifest if usingchrome.action.*APIs - If reading/scripting tabs from a side panel: use
tabs+host_permissions(NOTactiveTab) - DevTools panel paths in
chrome.devtools.panels.create()are relative to extension root - Offscreen documents use ONLY
chrome.runtimemessaging — nochrome.downloads,chrome.action, etc. - All image refs in
chrome.notifications,chrome.action.setIcon, etc. point to real files (or use data URLs) - Tab/desktop capture uses state locking to prevent double-start errors
-
chrome.desktopCapture.chooseDesktopMediapassestargetTabwithtabspermission -
chrome.windowscalls usegetAll/getLastFocused/getCurrent— NOT.query()(it doesn't exist) -
chrome.permissions.request()in a service workeronMessagelistener is called with noawaitbefore it (gesture is lost after the first async gap) -
chrome.userScriptsavailability checked before use (API throws if user hasn't enabled it) - User script configs persisted in
chrome.storageand restored onruntime.onInstalled"update"reason -
configureWorld({ messaging: true })called before user scripts send messages; listening ononUserScriptMessagenotonMessage -
ScriptSourceentries each have exactly one ofcodeorfile(not both, not neither) - User script
idvalues do not start with underscore -
sidePanel.setPanelBehaviorusesopenPanelOnActionClick— NOTopenPanelOnActionIconClick - Error handling on all async operations
-
host_permissionsscoped to specific domains (not<all_urls>unless needed) -
return trueinonMessagelisteners with async responses - Any use of
"tab"inchrome.contextMenuscontextsrequires Chrome M150+
From the fcakyon/claude-codex-settings README
Battle-tested Claude Code, Claude Desktop, OpenAI Codex, Cursor, and Antigravity CLI setup with skills, commands, hooks, subagents, and MCP servers, plus Kimi, MiniMax, and GLM API support.
"They make wrong assumptions on your behalf and just run along with them without checking. They don't manage their confusion, they don't seek clarifications, they don't surface inconsistencies, they don't present tradeoffs. They really like to overcomplicate code and APIs, they bloat abstractions, they don't clean up dead code after themselves." -- Andrej Karpathy
This repo's guidelines are structured to fix exactly these pitfalls.
Installation • Plugins • Configuration • References
Claude Settings has setup guides and skill downloads. Agent Plugins is the compact plugin directory.
Installation
Plugins add skills, commands, and automations to your AI coding tool. Install only what you need from the plugin list below.
Prerequisites: See INSTALL.md for setup requirements.
Claude Code
# Add marketplace (one time)
claude plugin marketplace add fcakyon/claude-codex-settings
# Install any plugin by name
claude plugin install humanize@claude-settings
In Claude Code desktop, select + beside the prompt, then Plugins and Add plugin.
Codex CLI
# Add marketplace (one time)
codex plugin marketplace add fcakyon/claude-codex-settings
# Install any plugin by name
codex plugin add simplify@claude-settings
In the Codex desktop app, open Plugins, find the plugin, and select Install.
Antigravity CLI
git clone https://github.com/fcakyon/claude-codex-settings.git
cd claude-codex-settings
uv run .github/scripts/antigravity.py sync
Install one plugin instead:
uv run .github/scripts/antigravity.py install simplify
Requires Antigravity CLI and uv. sync installs the curated Antigravity plugins and merges .gemini/config/config.json and .gemini/antigravity-cli/settings.json into ~/.gemini while keeping local plugins and trustedWorkspaces. Shell and file-edit hooks come along, while agents, commands, output styles, and Claude-only hooks stay with their original tools. Add more plugin names to install to install several at once.
Cursor
# Add marketplace (one time)
agent plugin marketplace add https://github.com/fcakyon/claude-codex-settings
# Start the interactive CLI
agent
Enter /plugin, open the marketplace, and install the plugin at user or project scope. In the Cursor app, open Customize and select Install.
Want the shared agent guidance too? .claude/CLAUDE.md is the file written for your projects. Run /claude-tools:sync-claude-md to pull it into ~/.claude/CLAUDE.md, or paste it into a project as CLAUDE.md, then point the other tools at the same file:
ln -sfn CLAUDE.md AGENTS.md # Codex, Cursor, Antigravity, Copilot
Plugins
code-review - Find bugs in code changes, with optional local fixes and review comments
| Codex CLI | Cursor | Antigravity CLI |
|---|---|---|
codex plugin add code-review@claude-settings | Run agent, enter /plugin, and install by name | uv run .github/scripts/antigravity.py install code-review |
Skills CLI
npx skills add https://github.com/fcakyon/claude-codex-settings/tree/main/plugins/code-review --skill '*'
Review your current changes before a direct push, or specify a branch, commit range, path, GitHub PR, or GitLab MR. Select the installed code-review skill in your client.
- Review only by default. Choose
lowfor a diff scan ormediumthroughmaxfor deeper passes. Use--max-findingsto set the report limit. - Add
--fixto apply verified fixes to the local checkout. - Add
--commentwith a GitHub PR or GitLab MR target to post findings.
Skills (ZIP for ChatGPT, Claude.ai, Cursor, Codex, VS Code):
| Skill | Description | ZIP |
|---|---|---|
code-review | Verify regressions in a diff and report them by impact |
simplify - Review changed code for reuse, redundancy, and over-engineering, then apply fixes
| Codex CLI | Cursor | Antigravity CLI |
|---|---|---|
codex plugin add simplify@claude-settings | Run agent, enter /plugin, and install by name | uv run .github/scripts/antigravity.py install simplify |
Use simplify in Codex, Cursor, or Antigravity to review your staged or committed diff for reuse, simplification, efficiency, and fix placement. The skill reviews all four angles in parallel and applies the cleanups.
Skills:
simplify- review the changed diff across four angles and apply the fixes
Hooks:
guard.py- Require a completed /simplify run before each Codex commit, unless you explicitly ask to skip it for one commit
humanize - Write naturally and block AI buzzwords in files, commits, and messages
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install humanize@claude-settings | codex plugin add humanize@claude-settings | uv run .github/scripts/antigravity.py install humanize |
Before a Write or Edit saves, humanize scans the new text and blocks whatever reads like a machine wrote it, each hit paired with a plain-word swap. It reads Markdown files whole and checks comments and docstrings in code files while skipping source code and recognized code-shaped references:
- 3 marks: the em-dash, section sign, and stray semicolon (the en-dash stays)
- 53 stock words like
leverage,seamlessly,vibrant,game-changing, each mapped to a plain swap - 16 openers and cliches like
in conclusion,a testament to,aims to bridge - 10 pile-up words like
crucialorsignificant, flagged at 3+ uses in one write
The hook runs on Claude Code and Codex, and on Antigravity CLI for file writes and shell commands. Unlike a markdown rule the model can ignore, the hook checks every Write or Edit and blocks each match until it is replaced. The word list draws on Wikipedia's "Signs of AI writing".
Skills (ZIP for claude.ai, ChatGPT, Claude Code, Cursor, Codex, VS Code):
| Skill | Description | ZIP |
|---|---|---|
humanize | Avoid common AI writing patterns with examples |
Hooks:
humanize.py- blocks matched marks, buzzwords, and cliches before a Write or Edit lands
fable-advisor - Get a second opinion from Claude Fable 5.1 before big decisions
| Codex CLI | Cursor | Antigravity CLI |
|---|---|---|
codex plugin add fable-advisor@claude-settings | Run agent, enter /plugin, and install by name | uv run .github/scripts/antigravity.py install fable-advisor |
Ask a Fable 5.1 reviewer to challenge a plan or conclusion from Codex, Cursor, or Antigravity. The skill calls Fable through an authenticated Claude CLI.
Skills:
fable-advisor- Request a focused second opinion from Fable
codex-advisor - Get a second opinion from GPT-6 Astra via Codex CLI before big decisions
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install codex-advisor@claude-settings | codex plugin add codex-advisor@claude-settings | uv run .github/scripts/antigravity.py install codex-advisor |
Ask GPT-6 Astra to challenge a plan before you build it, the cross-model check the built-in advisor cannot give you. Claude Code attaches the recent conversation, so "ask the codex advisor" is enough. Codex, Cursor, and Antigravity reach the same reviewer. Needs the Codex CLI signed in.
Agents:
codex-advisor- Sends the recent conversation to GPT-6 Astra and returns the verdict verbatim
Skills:
codex-advisor- Routes Claude Code to its native agent and other tools tocodex exec
adhd-output-style - Use fewer output tokens with short steps, quick insights, and clear next actions
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install adhd-output-style@claude-settings | codex plugin add adhd-output-style@claude-settings | uv run .github/scripts/antigravity.py install adhd-output-style |
Cuts filler and keeps output token use down with the answer or next step first, one-action-per-step lists, concrete time estimates, a single under-two-minute next action, and short teaching notes while coding. Claude Code applies the output style automatically. Codex, Cursor, and Antigravity CLI expose the same instructions as an adhd-output-style skill because they do not support plugin output styles.
Output styles:
ADHD Explanatory- Low-token ADHD formatting plus educational Insight blocks while coding
Skills (ZIP for claude.ai, Claude Code, Cursor, Codex, VS Code):
| Skill | Description | ZIP |
|---|---|---|
adhd-output-style | Apply the same reply format in Codex, Cursor, and Antigravity CLI |
intelligent-compact - Keep file paths, root causes, and open questions through auto-summaries
| Claude Code | Codex CLI |
|---|---|
claude plugin install intelligent-compact@claude-settings | codex plugin add intelligent-compact@claude-settings |
When Claude Code auto-summarizes a long session, the default summary routinely drops the highest-signal facts. This plugin tells the summarizer to keep them:
- File paths under investigation so the next turn doesn't re-discover where you were
- Confirmed root causes so you don't re-debug what's already solved
- Open questions, metrics, and IDs that prose summaries usually round away
- Findings from expensive subagent runs that took minutes to gather
Runs on every /compact (manual) and every auto compaction. Claude Code only; Codex, Cursor, and Antigravity CLI don't yet expose a comparable summary hook.
Hooks:
precompact_priorities.sh- Priority-preservation instructions for the compaction summarizer
claude-telemetry-hooks - Track Claude Code usage, rejections, and session stats in one dashboard
| Claude Code | Codex CLI |
|---|---|
claude plugin install claude-telemetry-hooks@claude-settings | n/a |
Adds the two missing pieces Claude Code's telemetry needs to power a usage dashboard:
- Sticky session ID per project: resumed conversations stay one session, not dozens
- Categorized rejection reasons (profanity, wrong target, scope drift, retry, and more): chart why Claude pushes back
Per-device data is already in Claude Code's built-in OpenTelemetry stream. Pairs naturally with openobserve-skills for the dashboard side.
Hooks:
session_start_chat_id.py- SessionStart hook that emits a sticky per-projectchat_iduser_prompt_reject_feedback.py- UserPromptSubmit hook that categorizes tool-rejection reasons
anthropic-office-skills - Official Anthropic PDF, Word, PowerPoint, Excel skills
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install anthropic-office-skills@claude-settings | codex plugin add anthropic-office-skills@claude-settings | uv run .github/scripts/antigravity.py install anthropic-office-skills |
Skills CLI
npx skills add https://github.com/fcakyon/claude-codex-settings/tree/main/plugins/anthropic-office-skills --skill '*'
Official office document skills from anthropics/skills.
| Skill | Description | Install |
|---|---|---|
pdf | PDF processing (read, merge, split, create, OCR, forms) | |
pptx | PowerPoint presentation building and editing | |
xlsx | Excel spreadsheet processing with formulas | |
docx | Word document creation and editing |
openai-office-skills - Official OpenAI PDF, Word, PowerPoint, Excel skills
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install openai-office-skills@claude-settings | codex plugin add openai-office-skills@claude-settings | uv run .github/scripts/antigravity.py install openai-office-skills |
Skills CLI
npx skills add https://github.com/fcakyon/claude-codex-settings/tree/main/plugins/openai-office-skills --skill '*'
Office document skills for creating and editing PDFs, Word documents, slide decks, and spreadsheets.
| Skill | Description | Install |
|---|---|---|
pdf | PDF generation and extraction with visual review | |
slides | Slide deck creation with PptxGenJS | |
spreadsheet | Spreadsheet processing with formulas and formatting | |
doc | Word document creation and editing |
python-skills - Python best practices from PEP 8, Zen of Python, Google style, and Effective Python
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install python-skills@claude-settings | codex plugin add python-skills@claude-settings | uv run .github/scripts/antigravity.py install python-skills |
Python coding guidelines grounded in authoritative sources: PEP 8, PEP 20 (Zen of Python), Google Python Style Guide, and Brett Slatkin's "Effective Python" (3rd ed.). Covers code integration, idiomatic patterns, YAGNI anti-abstraction rules, Google-style docstrings, and 18 before/after code examples.
Skills (ZIP for claude.ai, Claude Code, Cursor, Codex, VS Code):
| Skill | Description | ZIP |
|---|---|---|
python-guidelines | Core rules, self-tests, and reference index |
Reference files:
zen-of-python.md- Full PEP 20 with annotationsgoogle-style-guide.md- Curated sections with source URLsidiomatic-patterns.md- 18 patterns with before/after codeeffective-python-tips.md- Key tips from 3rd edition
swift-skills - SwiftUI practices for iOS and macOS
Write and review SwiftUI apps with guidance on accessibility, data flow, navigation and performance.
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install swift-skills@claude-settings | codex plugin add swift-skills@claude-settings | uv run .github/scripts/antigravity.py install swift-skills |
| Skill | What it does | Download |
|---|---|---|
swiftui-best-practices | SwiftUI development and review guidance | ZIP |
typescript-skills - TypeScript type safety and coding practices
Use practical examples to model types and validate data at application boundaries.
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install typescript-skills@claude-settings | codex plugin add typescript-skills@claude-settings | uv run .github/scripts/antigravity.py install typescript-skills |
| Skill | What it does | Download |
|---|---|---|
typescript-best-practices | Type safety, boundary validation and practical examples | ZIP |
heroui-skills - HeroUI for web and mobile apps
Build and theme React and React Native interfaces, or migrate an existing HeroUI app to v3.
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install heroui-skills@claude-settings | codex plugin add heroui-skills@claude-settings | uv run .github/scripts/antigravity.py install heroui-skills |
Skills CLI
npx skills add https://github.com/fcakyon/claude-codex-settings/tree/main/plugins/heroui-skills --skill '*'
| Skill | What it does | Download |
|---|---|---|
| heroui-react | Build and theme React interfaces with HeroUI v3 | ZIP |
| heroui-migration | Migrate React apps from HeroUI v2 to v3 | ZIP |
| heroui-native | Build React Native interfaces with HeroUI Native | ZIP |
react-skills - Official React, Next.js, and React Native best practices
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install react-skills@claude-settings | codex plugin add react-skills@claude-settings | uv run .github/scripts/antigravity.py install react-skills |
Skills CLI
npx skills add https://github.com/fcakyon/claude-codex-settings/tree/main/plugins/react-skills --skill '*'
React and frontend best practices from vercel-labs/agent-skills.
Skills (ZIP for claude.ai, Claude Code, Cursor, Codex, VS Code):
| Skill | Description | ZIP |
|---|---|---|
composition-patterns | React composition patterns: compound components, render props, context | |
react-best-practices | 64 React/Next.js performance rules from Vercel Engineering | |
react-native-skills | 35+ React Native/Expo rules for performance and animations | |
react-view-transitions | View Transition API for page/route animations | |
web-design-guidelines | UI review against 16 web interface guideline categories |
agent-browser - Drive browsers and Electron apps, run UI QA, and turn websites into API clients
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install agent-browser@claude-settings | codex plugin add agent-browser@claude-settings | uv run .github/scripts/antigravity.py install agent-browser |
Skills CLI
npx skills add https://github.com/fcakyon/claude-codex-settings/tree/main/plugins/agent-browser --skill '*'
Browser automation via CLI instead of MCP. 93% less context usage than Playwright MCP by using snapshot + element refs instead of full DOM tree dumps. From vercel-labs/agent-browser.
Skills (ZIP for claude.ai, Claude Code, Cursor, Codex, VS Code):
| Skill | Description | ZIP |
|---|---|---|
agent-browser | Browser automation: navigation, forms, clicking, screenshots, auth, sessions | |
electron | Automate Electron desktop apps (VS Code, Slack, Discord, Figma, Notion) | |
derive-client | Build a direct API client from a site's recorded browser traffic | |
dogfood | Explore a web app to find bugs and UX issues | |
webmcp-gen | Expose a page's workflows as WebMCP tools | |
ui-regression | Verify actions, recovery, locales, accessibility, and real integrations |
The locally maintained ui-regression skill checks known workflows on local, staging, and deployed UIs, including browser extensions. Use dogfood for exploratory bug discovery.
CLI Tool: agent-browser - install via npm i -g agent-browser && agent-browser install
frontend-design-skills - Frontend design, testing, and writing skills (Anthropic + OpenAI + Vercel)
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install frontend-design-skills@claude-settings | codex plugin add frontend-design-skills@claude-settings | uv run .github/scripts/antigravity.py install frontend-design-skills |
Skills CLI
npx skills add https://github.com/fcakyon/claude-codex-settings/tree/main/plugins/frontend-design-skills --skill '*'
Frontend design, testing, and writing skills from anthropics/claude-plugins-official, openai/plugins, and vercel-labs/writing-guidelines.
| Skill | Description | Install |
|---|---|---|
product-ui-design | Design product flows, polished controls and app-specific design rules | Included in the plugin |
openai-frontend-design | Composition-first design: restrained layout, image-led hierarchy, tasteful motion | |
frontend-testing-debugging | Test rendered apps, debug interactions, and check responsive layouts | |
anthropic-frontend-design | Bold aesthetic direction, distinctive typography, anti-generic AI aesthetics | |
writing-guidelines | Review interface copy and text for clear, consistent writing |
Pairs naturally with reusable-app-components.
mongodb-skills - Official MongoDB skills for schema design, queries, indexing, and Atlas Search
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install mongodb-skills@claude-settings | codex plugin add mongodb-skills@claude-settings | uv run .github/scripts/antigravity.py install mongodb-skills |
Skills CLI
npx skills add https://github.com/fcakyon/claude-codex-settings/tree/main/plugins/mongodb-skills --skill '*'
Official MongoDB agent skills for schema design, queries, indexing, Atlas Search, and connections. From mongodb/agent-skills.
Skills (ZIP for claude.ai, Claude Code, Cursor, Codex, VS Code):
| Skill | Description | ZIP |
|---|---|---|
mongodb-atlas-stream-processing | Atlas stream processing patterns | |
mongodb-connection | Connection management | |
mongodb-mcp-setup | MCP server setup | |
mongodb-natural-language-querying | Natural language to queries | |
mongodb-query-optimizer | Query performance tuning | |
mongodb-schema-design | Schema design patterns | |
mongodb-search-and-ai | Atlas Search and AI integration |
supabase-skills - Supabase skills for Postgres, Auth, Edge Functions, the JS SDK, and the CLI
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install supabase-skills@claude-settings | codex plugin add supabase-skills@claude-settings | uv run .github/scripts/antigravity.py install supabase-skills |
Skills CLI
npx skills add https://github.com/fcakyon/claude-codex-settings/tree/main/plugins/supabase-skills --skill '*'
Supabase skills covering Postgres query/schema best practices from supabase/agent-skills, JavaScript SDK usage from supabase/supabase-js, and CLI workflows from supabase/cli.
Skills (ZIP for claude.ai, Claude Code, Cursor, Codex, VS Code):
| Skill | Description | ZIP |
|---|---|---|
supabase-postgres-best-practices | Postgres performance and schema design across 8 categories | |
supabase-js | JavaScript SDK for auth, database, storage, realtime, edge functions | |
supabase-cli | CLI for local dev, migrations, edge functions, project management | |
supabase | Supabase security, RLS, CLI, and schema change workflow |
stripe-skills - Official Stripe skills for payments, billing, Connect, Apps, and API upgrades
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install stripe-skills@claude-settings | codex plugin add stripe-skills@claude-settings | uv run .github/scripts/antigravity.py install stripe-skills |
Skills CLI
npx skills add https://github.com/fcakyon/claude-codex-settings/tree/main/plugins/stripe-skills --skill '*'
Official Stripe agent skills for payment integration: API selection, Connect platform setup, billing/subscriptions, Treasury, and SDK upgrades. From stripe/ai.
Skills (ZIP for claude.ai, Claude Code, Cursor, Codex, VS Code):
| Skill | Description | ZIP |
|---|---|---|
stripe-best-practices | Payments, billing, Connect, Treasury integration best practices | |
stripe-projects | Stripe Projects CLI setup and stack provisioning | |
upgrade-stripe | Stripe API version and SDK upgrade guide | |
connect-recommend | Choose a Stripe Connect setup for marketplaces and platforms | |
connect-required-verification-information | Connected account verification and KYC requirements | |
metronome | Usage-based billing with Metronome | |
stripe-apps | Build and review Stripe Apps | |
stripe-docs | Look up Stripe docs and API reference |
polar-skills - Official Polar agent skills for billing, subscriptions, and local dev environment
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install polar-skills@claude-settings | codex plugin add polar-skills@claude-settings | uv run .github/scripts/antigravity.py install polar-skills |
Skills CLI
npx skills add https://github.com/fcakyon/claude-codex-settings/tree/main/plugins/polar-skills --skill '*'
Official Polar agent skills for billing system, Stripe integration, subscription lifecycle, and local dev with Docker. From polarsource/polar.
Skills (ZIP for claude.ai, Claude Code, Cursor, Codex, VS Code):
| Skill | Description | ZIP |
|---|---|---|
polar-billing | Polar billing system, Stripe integration, subscriptions, benefit provisioning | |
polar-local-environment | Polar local development environment with Docker |
livekit-skills - Build, test, simulate, and deploy LiveKit voice AI agents
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install livekit-skills@claude-settings | codex plugin add livekit-skills@claude-settings | uv run .github/scripts/antigravity.py install livekit-skills |
Skills CLI
npx skills add https://github.com/fcakyon/claude-codex-settings/tree/main/plugins/livekit-skills --skill '*'
Voice AI agent development with the LiveKit Agents SDK, from design and live testing to simulations and production. Works with LiveKit Cloud or a self-hosted server, and looks up current docs with the lk CLI when no docs server is connected. Based on livekit/agent-skills, patched so the Cloud-only parts also cover self-hosting.
Skills (ZIP for claude.ai, Claude Code, Cursor, Codex, VS Code):
| Skill | Description | ZIP |
|---|---|---|
building-livekit-agents | Structure voice agents: latency, context size, handoffs and tasks | |
debugging-livekit-agents | Drive a local conversation with the agent and read its tool calls | |
operating-livekit-agents | Deploy, roll back, and keep a live agent fast and stable | |
reading-livekit-docs | Look up current LiveKit APIs, CLI flags, and changelogs | |
running-livekit-simulations | Run whole-conversation simulations before shipping | |
testing-livekit-agents | Write turn-level agent tests with pytest or Vitest | |
writing-livekit-scenarios | Write and maintain the scenarios simulations run |
cloudflare-skills - Pick Cloudflare products and build with Workers, Durable Objects, and Wrangler
| Claude Code | Codex CLI | Antigravity CLI |
|---|---|---|
claude plugin install cloudflare-skills@claude-settings | codex plugin add cloudflare-skills@claude-settings | uv run .github/scripts/antigravity.py install cloudflare-skills |
Skills CLI
npx skills add https://github.com/fcakyon/claude-codex-settings/tree/main/plugins/cloudflare-skills --skill '*'
Choose the Cloudflare services your project needs, then load the relevant specialist skill. From cloudflare/skills.
- Includes Workers, Wrangler, Durable Objects, Agents SDK, Sandbox, and Turnstile guidance.
- Covers Next.js deployment, email, Zero Trust, migrations, and web performance.
- Keeps detailed references inside each skill so they are read only when needed.
Skills (ZIP for claude.ai, Claude Code, Cursor, Codex, VS Code):
Details
- Marketplace
- fcakyon/claude-codex-settings
- Source
- plugins/modern-web-guidance
- Category
- Web Testing
- License
- Apache-2.0
- Keywords
- web-platform, accessibility, css, browser-extensions
More from fcakyon/claude-codex-settings
All 50- mongodb-skillsv1.0.5
- openai-office-skillsv1.0.2
- openobserve-skillsv1.0.5
- openship-skillsv1.0.3
- overleaf-skillsv1.1.0
- paper-search-toolsv3.0.1
- phd-skillsv1.3.0
- polar-skillsv1.0.5
- python-skillsv1.0.4
- qav1.10.0
- react-skillsv1.0.6
- remote-mcp-skillsv1.0.0
- reusable-app-componentsv1.4.4
- seo-skillsv1.4.0
- simplifyv1.1.15
- stripe-skillsv1.1.4
- supabase-skillsv1.1.3
- swift-skillsv1.0.0
- tavily-toolsv2.0.7
- test-auditv1.0.2
- typescript-skillsv1.0.0
- ultralytics-brandingv1.0.1
- ultralytics-devv2.5.2
- web-performance-skillsv1.0.6
Similar to modern-web-guidance
More Web & Browser
taste-skillLeonxlnx/taste-skill117.9K starstasteskill 2.5.1: professional company websites at the figma.com and x.ai level, with one section per screen, real photographs, real product UI, effects kept fo
ruflo-browserruvnet/ruflo82.2K starsAgentic browser automation with Playwright for testing, scraping, and UI interaction
chrome-devtools-mcpChromeDevTools/chrome-devtools-mcp58.1K starsReliable automation, in-depth debugging, and performance analysis in Chrome using Chrome DevTools and Puppeteer
agent-browservercel-labs/agent-browser52.4K starsAutomates browser interactions for web testing, form filling, screenshots, and data extraction
anchor-browser-automationComposioHQ/awesome-claude-skills51.5K starsAutomate Anchor Browser tasks via Rube MCP (Composio). Always search tools first for current schemas.
atlassian-twg-clianthropics/claude-plugins-official47.9K starsTeamwork Graph CLI is Atlassian's agent-first interface to your entire work context: Jira issues, Confluence pages, Bitbucket PRs, along with your connected thi