Publishing Artifacts

How to publish quality artifacts to agex — from single-file rules to multi-file skills.

Quick start

From the web

Go to /app/configs/new (or click the + button → Artifact)
Fill in title, category, and type
Add files — paste content, upload, or import from GitHub
Add a README to explain what your artifact does
Select supported platforms
Click Publish

From the CLI

# Push a single file
agex push CLAUDE.md

# Push a folder as a multi-file artifact
agex push ./my-skill/

# Push with metadata
agex push CLAUDE.md --title "Next.js Rules" --type claude-md --tag nextjs,typescript

From GitHub

Paste a GitHub URL in the import field when creating an artifact:

# Single file
https://github.com/user/repo/blob/main/CLAUDE.md

# Entire folder
https://github.com/anthropics/skills/tree/main/skills/mcp-builder

The folder import fetches all files and preserves the directory structure.

Writing a good README

The README is the landing page for your artifact. It should answer:

What does this do? — one sentence summary
Who is it for? — what stack, what platform, what workflow
How to install — agex add @you/artifact (auto-shown, but context helps)
What's included — for multi-file artifacts, explain the file structure
Configuration — any env vars, settings, or customization needed
Examples — show what the agent does differently with this artifact installed

Multi-file artifacts

For skills, MCP servers, and complex configurations, use multi-file artifacts:

my-skill/
  SKILL.md            # Main skill definition (primary file)
  reference/
    best-practices.md # Reference documentation
    examples.md       # Usage examples
  scripts/
    evaluate.py       # Evaluation script
    requirements.txt  # Dependencies
  LICENSE.txt         # License

The primary file (marked with a star in the editor) is what gets output when someone runs agex run @you/artifact. All files are available via agex run --file and agex run --all.

Choosing the right category

Category	Use when...
Rules	Always-on context that the agent loads automatically (CLAUDE.md, .cursorrules)
Skills	On-demand knowledge the agent invokes for specific tasks (SKILL.md + scripts)
MCP Servers	External tool connections (server configs or full implementations)
Hooks	Event-triggered scripts (pre-edit linting, post-task notifications)
Agents	Specialized agent definitions (subagents, team configs, system prompts)
Commands	Custom slash commands or workflow shortcuts
CLI Tools	Command-line tools that can be managed by agex

Platform compatibility

Select which platforms your artifact supports:

Claude Code — CLAUDE.md, skills, hooks, MCP, agents, commands
Cursor — .cursorrules, rules (.mdc), MCP
Gemini CLI — GEMINI.md, skills, MCP
Codex — AGENTS.md
OpenCode — AGENTS.md

The CLI uses these to place files in the right location for each platform.

Versioning

Every content update creates a new version. If your artifact has maintainers, updates go through review before publishing.

Add a changelog when updating to help users understand what changed:

agex push CLAUDE.md --changelog "Added testing conventions for vitest"

Tips

Be specific — "Next.js 15 + TypeScript + Tailwind CLAUDE.md" is better than "My CLAUDE.md"
Tag well — stack tags and platform selections help people find your artifact
Version thoughtfully — breaking changes deserve a clear changelog
Respond to issues — active maintainers build trust

Publishing Artifacts

On this page