AGENTS.md — Simplified for AI

Operational guidance for AI coding assistants (Codex, Claude Code, Cursor) using this plugin.

Project overview

Simplified for AI lets agents operate Simplified's image/video generation, assets, brand context, marketing projects, and social media, then compose those platform primitives into marketer workflows — through:

• Skills (skills/) — SKILL.md workflow files that teach the agent sequencing, terminology, and safety behavior.
• A hosted MCP connector — the tools the skills drive, served at https://apikit.simplified.com/mcp (OAuth-secured). Declared in .mcp.json.

Plugin structure

simplified-ai/
├── .mcp.json                 # hosted MCP connector (OAuth) — shared by all clients
├── .claude-plugin/plugin.json   # Claude Code manifest
├── .codex-plugin/plugin.json    # Codex / ChatGPT Apps manifest
├── skills/                   # SKILL.md workflows (Agent Skills spec)
│   ├── manage-assets/
│   ├── generate-image/
│   ├── edit-image/
│   ├── transcribe-media/
│   ├── generate-voiceover/
│   ├── repurpose-video/
│   ├── generate-video/
│   ├── simplified-workspace/
│   ├── simplified-social/
│   ├── manage-brand/
│   ├── manage-projects/
│   ├── simplified-project-management/
│   ├── simplified-cli/
│   ├── simplified-workflows/
│   ├── simplified-agents/
│   ├── social-content-planner/
│   ├── cross-platform-campaign/
│   ├── content-repurposer/
│   ├── evergreen-content-engine/
│   ├── local-business-marketing/
│   ├── creative-testing/
│   ├── social-performance-analyst/
│   └── campaign-review/
├── assets/                   # brand icon + logo
└── evals/                    # test cases + runnable I/O harness

Skills

The outcome-driven skills compose the platform operators. Workspace identity establishes the scope for every other operator. Image and video generation with asset storage returns permanent asset IDs for simplified-social.media; brand and project skills provide reusable context and operational handoffs. Workflow skills orchestrate those primitives around marketer jobs without duplicating API mechanics.

MCP servers

Three connectors, configured in .mcp.json:

All three are the same Simplified account. Each is OAuth-secured — the client walks the OAuth flow; no API key to set. The hosted ChatGPT app connects only to simplified, which is why the automation skills are left out of that bundle. On a 401, the client refreshes its token automatically (server emits the standard challenge).

Key conventions (agent behavior)

• Confirm before spending credits. Image/video generation and social publishing consume credits / post to live accounts — confirm when intent is ambiguous.
• Resolve scope before scoped work. Use api_getWorkspaceInfo as whoami when workspace/teamspace context is named or uncertain. Resolve names to exact numeric IDs, then pass space_id on every downstream tool call in that scoped task.
• Draft before publish. For social posts, create a draft and show it before scheduling/queuing. Publish only within explicit user authorization; reuse approval for the same content, accounts, timing, and comments instead of asking again.
• Keep agency reviews client-isolated. Resolve the client's workspace/teamspace, carry its space_id through every account, draft, update, and review-bundle call, and create a separate bundle per client and campaign. Never mix cross-client IDs.
• "Post now" uses the available publishing action add_to_queue. Do not promise immediate delivery; report the actual timing returned by the service. There is no separate immediate publish action; the action enum is schedule | add_to_queue | draft.
• Auto-comments are post-relative. comments[].delay is a nonnegative number of seconds after the post publishes, not after the preceding comment. Convert “first comment after X minutes” to X * 60, and include the comment text and delay in the publication plan the user authorizes.
• Prefer asset IDs for Simplified media. Generated file URLs can expire. Social media accepts asset UUIDs, supported URLs, or URL/thumbnail objects. Posting account_ids is string[], while analytics account_id is integer; do not conflate these identifiers.
• Present media using client capabilities. Use a native media preview when the client supports it and the user wants to review the result. Otherwise show a usable link. Refresh expired asset URLs; do not download remote media merely to bypass client display restrictions. Review bundles and other web pages remain links.
• Accountless drafts are supported. If connected accounts are empty, continue an authorized action: "draft" request without account_ids. Scheduling, queueing, and account-specific analytics require the relevant connected accounts.

Commit attribution

When an AI agent commits to this repo, include a Co-Authored-By: line with the agent model's name.

Media contracts

Route asset discovery/intake/reuse to manage-assets. Use current generation schemas: image parameters.reference_images takes asset IDs or URLs; video normalized slots take asset UUIDs. Current middleware waits for generation completion; continue only returned non-terminal jobs. Installed skills do not change deployed tool availability. Do not use historical eval tool counts as current capabilities.