Artifacts

The seven artifact categories — what they are, when to use each, and how they map to files on disk.

Every piece of content on agex is an artifact — a package of one or more files that configures or extends how an AI agent behaves in your project. Artifacts are organized into seven categories, aligned with the shared terminology across Claude Code, Cursor, Gemini CLI, Codex, and OpenCode.

Categories

Rules

Always-on context that is loaded automatically whenever an agent starts a session in your project. Rules tell the agent about your codebase, conventions, architecture decisions, and what to avoid.

Type	File	Description
`CLAUDE.md`	`CLAUDE.md`	Project-level instructions for Claude Code
`.cursorrules`	`.cursorrules`	Rules for Cursor
`AGENTS.md`	`AGENTS.md`	Agent instructions for Codex, OpenCode
`GEMINI.md`	`GEMINI.md`	Context for Gemini CLI
`Copilot Instructions`	`.github/copilot-instructions.md`	GitHub Copilot rules
`Other Rules`	varies	Any other always-on context file

Best for: codebase context, code style preferences, architectural constraints, testing conventions, git workflow.

Skills

On-demand knowledge and workflows that agents can invoke when needed. Skills can be multi-file packages containing reference docs, scripts, and evaluations — not just a single markdown file.

Type	Description
`Action Skill`	Step-by-step procedure for a specific task (SKILL.md + scripts)
`Reference Skill`	Knowledge the agent can look up (API docs, design patterns)
`Recipe / Guide`	Reusable workflow combining multiple steps

Skills are placed in .claude/skills/{name}/ for Claude Code, or .cursor/rules/{name}.mdc for Cursor. Multi-file skills preserve their directory structure.

MCP Servers

External tool connections via the Model Context Protocol. Share server configurations and full server implementations.

Type	Description
`MCP Server Config`	Configuration file for connecting to an MCP server
`MCP Server Implementation`	Full server code + config

MCP configs are merged into .mcp.json (Claude Code) or .cursor/mcp.json (Cursor) — the CLI handles the merge so existing entries are preserved.

Hooks

Event-triggered automation scripts that run as part of agent workflows.

Type	Description
`Hook Script`	Script triggered by agent lifecycle events (pre-tool, post-tool, etc.)
`Hook Configuration`	Configuration defining when and how hooks run

Hooks are merged into .claude/settings.local.json for Claude Code.

Agents

Specialized agent and subagent definitions for task-specific workflows.

Type	Description
`Subagent Definition`	A specialized agent invoked by the primary agent
`Agent Team Config`	Multi-agent team configuration
`Agent System Prompt`	System prompt for a custom agent persona

Subagents and agent team configs are placed in .claude/agents/{name}.md.

Commands

Custom shortcuts and reusable workflows that extend agent capabilities.

Type	Description
`Custom Command`	A reusable command definition
`Slash Command`	Slash-invocable command for supported platforms

CLI Tools

Command-line tools managed by agex, scoped to your project.

Type	Description
`CLI Tool`	A command-line tool installable via agex
`CLI Extension`	An extension to an existing CLI tool

Multi-file artifacts

Artifacts can contain multiple files. This is common for skills, MCP server implementations, and CLI tools that include documentation, scripts, and configuration.

my-skill/
  SKILL.md              # Main skill definition
  reference/
    best-practices.md   # Reference documentation
    examples.md
  scripts/
    evaluation.py       # Supporting scripts
    requirements.txt
  LICENSE.txt

When you agex push ./my-skill/, the CLI bundles all files into a single artifact. On the hub, users can browse the file tree before installing.

You can also import a folder directly from GitHub:

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

Versioning

Every artifact update creates a new version. You can pin to a specific version in agex.toml:

[rules]
my-rules = "@rkrebs/nextjs-claude@3"

If no version is specified, agex sync always fetches the latest.

Version reviews

Artifacts with maintainers can require review before new versions are published (similar to pull requests). The owner configures how many approvals are needed (1–3). Solo-owner artifacts publish immediately.

Artifact references

Artifacts are referenced by @username/slug, optionally with a version:

@rkrebs/nextjs-claude          # latest
@rkrebs/nextjs-claude@2        # specific version

The @ prefix is optional in agex.toml.

On this page