Agent Skills

AI coding assistant skills for building applications with Cosmic headless CMS. Two ways to get started:

1. Agent Signup (below) - an AI agent can provision a new Cosmic project + bucket in one API call, tied to a human's email. No prior Cosmic account needed.
2. Skill install - drop the Cosmic SDK rules file into an existing project so your AI coding assistant generates accurate Cosmic code.

Agent Signup

AI agents can create a Cosmic project on behalf of a human in a single call. The project starts in restricted mode ("unclaimed") with conservative limits, an OTP is emailed to the human, and the human paste the code back to the agent to claim full free-tier access. If the human prefers, they can also claim by signing up at app.cosmicjs.com with the same email.

This is the recommended onboarding path for AI agents (Cursor, Claude Code, Bolt, Lovable, v0, custom agents) that need to create content infrastructure on the fly.

{
  "mcpServers": {
    "cosmic-agent": {
      "url": "https://mcp.cosmicjs.com/v1/agent"
    }
  }
}

Set up a new Cosmic CMS project for this app.

Steps:
1) Ask me for my email address and a project name.
2) Use the Cosmic MCP server at https://mcp.cosmicjs.com/v1/agent and call the cosmic_agent_signup tool with agent_id="cursor". If the MCP server isn't installed, POST to https://dapi.cosmicjs.com/v3/agents/sign-up with { human_email, project_name, agent_id: "cursor" } instead.
3) Save the returned bucket slug, read_key, and write_key into .env.local as COSMIC_BUCKET_SLUG, COSMIC_READ_KEY, and COSMIC_WRITE_KEY.
4) Install @cosmicjs/sdk and scaffold a minimal data layer for the content I'll be building.
5) Add the Cosmic Insights tracker to my app shell:
   <script defer src="https://insights.cosmicinsights.dev/script.js" data-project="PROJECT_ID"></script>
6) After Cosmic emails me a 6-digit code, ask me for it and call cosmic_agent_verify (or POST /v3/agents/verify) to unlock AI features.
7) If the API returns user_already_exists (409), tell me to log in at app.cosmicjs.com and grant you a bucket key directly. Do not retry sign-up with a different email.

One-curl signup

curl -X POST https://dapi.cosmicjs.com/v3/agents/sign-up \
  -H "Content-Type: application/json" \
  -d '{
    "human_email": "tony@example.com",
    "project_name": "Recipe Blog",
    "agent_id": "my-agent-platform"
  }'

Response:

{
  "message": "Agent signup created. OTP sent to human_email.",
  "auth_type": "unclaimed",
  "agent_key": "agk_...",
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "project": { "id": "...", "name": "Recipe Blog" },
  "bucket": {
    "slug": "recipe-blog-...",
    "read_key": "...",
    "write_key": "..."
  },
  "claim_url": "https://app.cosmicjs.com/claim?token=agk_...",
  "limits": {
    "ai_credits_remaining": 0,
    "media_mb_total": 5,
    "objects_max": 50
  },
  "auto_delete_after_days": 14
}

The response returns three credentials, each with a distinct purpose:

Three auth states

Unclaimed projects are hard-deleted after 14 days if not claimed. Plan accordingly.

Verify (OTP back from human)

When the human gives the agent the 6-digit code from their email, the agent calls:

curl -X POST https://dapi.cosmicjs.com/v3/agents/verify \
  -H "Authorization: Bearer agk_..." \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

On success, restricted-mode limits lift, AI generation is enabled on the bucket, and the response includes a fresh access_token with a longer 90-day expiry. Replace any previously stored token with this one.

Status

curl https://dapi.cosmicjs.com/v3/agents/status \
  -H "Authorization: Bearer agk_..."

Returns the current auth_type, plan_id, claim status, remaining limits, the bucket keys (so an agent that lost its sign-up response can recover them), and a freshly issued access_token. Treat /status as the canonical refresh endpoint: call it periodically with the agent_key to rotate the user JWT before it expires.

Existing user collision

If human_email is already a Cosmic user, sign-up returns 409 user_already_exists with a claim_existing_url. Ask the human to log in at app.cosmicjs.com and grant the agent a bucket key directly; do not retry with a different email.

Using the CLI

cosmic agent-signup --email tony@example.com --project "Recipe Blog" --agent-id my-agent
# CLI is now logged in as the agent: cosmic ls, cosmic types create,
# cosmic objects create, etc. all operate on the new bucket immediately.
cosmic agent-verify 123456
cosmic agent-status
cosmic agent-keys       # show the full bucket read/write keys
cosmic agent-use        # re-activate the agent session if cosmic login replaced it

The CLI stores agent_key, access_token, and bucket keys in ~/.cosmic/credentials.json. After agent-signup the CLI activates the agent session automatically (sets the access token + bucket keys + context) so every standard command works without a separate "use" step. If an existing login is present, the CLI prints a notice that the previous session was replaced. cosmic whoami clearly labels active agent sessions.

Using the MCP server

The agent scope is hosted at mcp.cosmicjs.com/v1/agent and exposes three tools that proxy to the endpoints above:

• cosmic_agent_signup - no auth required
• cosmic_agent_verify - Authorization: Bearer agk_...
• cosmic_agent_status - Authorization: Bearer agk_...

For stdio mode, set COSMIC_MCP_SCOPE=agent and (after signup) COSMIC_AGENT_KEY=agk_... and the same three tools are exposed locally.

Installation

Install skills for your AI coding assistant using the skills CLI:

npx skills add cosmicjs/skills

This will add the Cosmic skill to your local project, giving your AI assistant context about the Cosmic SDK and API.

What the Skill Covers

The Cosmic agent skill provides comprehensive guidance on:

SDK-first Development

• Setting up the @cosmicjs/sdk package
• Configuring bucket clients with proper authentication
• Type-safe methods and error handling

Objects API

Create, read, update, and delete content with the Objects API:

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: 'BUCKET_SLUG',
  readKey: 'BUCKET_READ_KEY',
  writeKey: 'BUCKET_WRITE_KEY'
})

// Get multiple Objects
const { objects: posts } = await cosmic.objects
  .find({ type: 'posts' })
  .props(['id', 'title', 'slug', 'metadata'])
  .limit(10)

// Get single Object by slug
const post = await cosmic.objects
  .findOne({ type: 'posts', slug: 'hello-world' })
  .props(['title', 'slug', 'metadata'])

// Create an Object
await cosmic.objects.insertOne({
  title: 'My Post',
  type: 'posts',
  metadata: {
    content: 'Post content here...',
    author: 'author-object-id'
  }
})

Object Types & Metafields

Content modeling with Object types and all available Metafield types:

• Text, textarea, markdown, HTML
• Number, date, switch, color
• Select, multi-select, dropdown, radio buttons, checkboxes
• Single and multiple file uploads
• Object relationships (single and multiple)
• JSON, repeater, and parent (nested) fields

Media API

Upload and manage files and images:

// Upload media
const uploaded = await cosmic.media.insertOne({
  media: { originalname: 'photo.jpg', buffer: fileBuffer },
  folder: 'uploads',
  alt_text: 'Description of image'
})

// Use imgix for image transformations
const optimized = `${media.imgix_url}?w=800&auto=format,compress`

Queries

MongoDB-style filtering and search:

// Comparison operators
await cosmic.objects.find({
  type: 'products',
  'metadata.price': { $lt: 100 }
})

// Array matching
await cosmic.objects.find({
  type: 'products',
  'metadata.tags': { $in: ['sale', 'featured'] }
})

// Text search
await cosmic.objects.find({
  type: 'posts',
  title: { $regex: 'hello', $options: 'i' }
})

AI Generation

Built-in AI capabilities for text, images, and video:

// Generate text
const text = await cosmic.ai.generateText({
  prompt: 'Write a product description',
  model: 'claude-sonnet-4-5-20250929'
})

// Generate image
const image = await cosmic.ai.generateImage({
  prompt: 'Mountain landscape at sunset',
  size: '1024x1024',
  folder: 'ai-generated'
})

// Generate video
const video = await cosmic.ai.generateVideo({
  prompt: 'A kitten playing with yarn',
  duration: 8,
  resolution: '720p'
})

Framework Patterns

Integration patterns for popular frameworks:

• Next.js App Router - Server Components and Server Actions
• React - Client-side data fetching
• Astro - Static and server-rendered pages
• And more - Remix, Nuxt, Svelte, etc.

Quick Example

Here's a complete Next.js App Router example:

// app/posts/page.tsx
import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: process.env.COSMIC_BUCKET_SLUG!,
  readKey: process.env.COSMIC_READ_KEY!
})

export default async function Posts() {
  const { objects: posts } = await cosmic.objects
    .find({ type: 'posts' })
    .props(['title', 'slug', 'metadata.excerpt'])
    .limit(10)

  return (
    <ul>
      {posts.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

Supported AI Agents

The Cosmic agent skill works with:

• Cursor - AI-first code editor
• Claude Code - Anthropic's coding assistant
• GitHub Copilot - AI pair programmer
• Windsurf - AI coding assistant
• Gemini - Google's AI assistant
• And 16+ other AI coding agents

Key Reminders

The skill teaches your AI assistant these important patterns:

1. Object type is the SLUG - Use type: 'blog-posts', not type: 'Blog Posts'
2. Media uses name - Reference media by name property, not URL
3. Relations use id - Reference related Objects by id, not slug
4. Never expose writeKey - Keep it server-side only
5. Use props() - Always specify needed properties for performance
6. imgix for images - Use imgix_url with query params for optimizations

Rules for Agents

These rules are non-negotiable for agents using the signup flow. Failure modes here are security issues, not bugs.

1. NEVER send agent_key to any domain other than *.cosmicjs.com. It is a bearer credential. Treat it like a password. Do not log it, post it to chat, or include it in user-visible code blocks.
2. NEVER share write_key in user-visible output. If you need to show the user the bucket exists, show only the bucket slug and read key. The write key stays in your tool context.
3. NEVER call cosmic_agent_signup without an explicit human_email. The endpoint enforces this, but you should ask the human directly for their email rather than guessing or pulling it from context (prompt-injection risk).
4. Treat agent_id as your platform attribution string. Use the same value across every signup so the partner team can see your funnel volume. Examples: cursor-agent, claude-code, bolt, lovable. Do not put per-user IDs here.
5. On 409 user_already_exists, stop and instruct the human to log in. Do not retry with a synthetic email. Cosmic intentionally refuses agent provisioning for known users to prevent account squatting.
6. On 402 agent_unclaimed_limit, prompt the human for the OTP. This is the expected failure for AI generation, object creation past 50, or media upload past 5 MB on an unclaimed bucket. Calling cosmic_agent_verify with the OTP lifts the restriction.
7. Do not retry the signup endpoint with the same human_email more than once per minute. The endpoint is rate-limited per IP (1/min) and per agent_id (100/day for unregistered agents). Sustained retries will get your agent_id flagged.
8. Do not promise the human their bucket is permanent before they claim. Unclaimed buckets are hard-deleted after 14 days. Surface this clearly in chat.

Resources

• Cosmic Documentation
• API Reference
• Discord Community