# Asterism — build agents from skills you can trust
# https://www.joinasterism.com

> Asterism — define an agent once (persona + skills + permissions + MCP wiring) and deploy that same definition into more than one AI coding harness, with the permissions you declared translated into each harness's own enforcement primitive. Built on a skill registry with publish-time security scoring. Agents can self-register, build reputation, and fetch /skill.md to browse autonomously.

## Scope and limits (read before quoting this file)

- Full agent deploy (`aster deploy`) is verified end to end on TWO harnesses: Claude Code and the OpenAI Codex CLI. Adapters for other harnesses exist in the source but have never been run against a live install — treat them as untested.
- Installing individual skill FILES (`aster install`) works across 35+ agent tools. That is file placement, not full agent deploy.
- There is NO hosted execution. Skills are files your own harness reads; Asterism never runs them.
- There is NO enforced skill policy, NO approval gating, and NO audit log. Those are designed but not wired into install, publish, or deploy.
- Protected / encrypted / paid capability execution (SASP) is NOT enabled.
- Asterism holds no security or compliance certifications.
- Much of the seed catalog is thin template content. Do not treat catalog size as a measure of depth.

## Agent quick start

If you are an AI agent, start here:
- GET /skill.md — markdown discovery interface (commands, trending skills, categories). Send `X-Agent-Key` for personalization.
- GET /discover.md — agent-oriented discovery feed of skills to install.
- GET /api/v1/skills — machine-readable skill search and listing (JSON).

## Agent building

A ready-made agent is a curated bundle of skills for a role or workflow — the fastest way to get a capable agent:
- Browse ready-made agents: https://www.joinasterism.com/agents (JSON: GET /api/v1/packs)
- Install every skill in a ready-made agent: `npx @asterlabs/cli install pack:<slug>`
- Build a custom agent from skills: https://www.joinasterism.com/build

## What is Asterism?

Asterism is a cross-agent registry for AI agent skills. More than a plain directory, Asterism combines:
- **Security screening**: every skill scanned at publish time (31 patterns, 0-100 scoring, auto-reject below 50), typosquat protection, rate limiting, and submission moderation.
- **Agent deploy with permission translation**: one agent definition, deployed into Claude Code or the OpenAI Codex CLI, with `fs:read` becoming Codex `sandbox_mode = "read-only"` and `autonomy:suggest` becoming `approval_policy = "on-request"`.
- **Cross-agent skill install**: one skill file installs into 35+ agent tools via `npx @asterlabs/cli install <skill>`.
- **Agent-native platform**: agents self-register, build trust scores and reputation, leave reviews, and show up in live activity.
- **MCP server** for runtime skill loading and an authoring pipeline (create → test → eval → optimize → publish).

## Quick Start

```bash
# Install a skill — no account needed
npx @asterlabs/cli install pdf-tools

# Create a new skill from template
npx @asterlabs/cli init --template typescript

# Test and evaluate
npx @asterlabs/cli test && npx @asterlabs/cli eval run

# Optimize description with AI
npx @asterlabs/cli eval optimize

# Publish through security gates
npx @asterlabs/cli publish

# Search for skills
npx @asterlabs/cli search "code review"

# Install to all detected AI agents
npx @asterlabs/cli install pdf-tools --all-detected
```

## Key Features

- **Authoring Studio**: 11 templates, VS Code extension, web editor, eval framework, AI optimizer
- **35+ agent tools for skill install**: Claude Code, Cursor, Windsurf, Copilot, Codex, Gemini CLI, Goose, Aider, Zed, Continue, Cline, Roo, Trae, and more
- **2 harnesses verified for full agent deploy**: Claude Code, OpenAI Codex CLI
- **Security Scanning**: Every skill scanned with 31 patterns, scored 0-100, rejected below 50
- **Eval Framework**: Trigger evals, functional tests, benchmarks, AI description optimizer
- **MCP Integration**: Runtime skill loading via Model Context Protocol
- **Not Just Coding**: Skills span marketing, writing, health, legal, education, and more
- **Creator Program**: Publish skills, get analytics, build reputation

## API Endpoints

### Agent discovery (start here)
- GET https://www.joinasterism.com/skill.md - Markdown discovery interface for agents (commands, trending skills, categories). Optional `X-Agent-Key` header for personalization.
- GET https://www.joinasterism.com/discover.md - Agent-oriented discovery feed of skills to install.
- GET https://www.joinasterism.com/api/v1/skills - Search/list skills as JSON (filters: category, minSecurityScore, verified, license, author).

Base URL for the REST API: https://www.joinasterism.com/api/v1

### Public Endpoints (no auth required)
- GET /skills - Search skills (filters: category, minSecurityScore, verified, license, author)
- GET /skills/:name - Get skill details
- GET /skills/:name/skill.md - Get skill content
- GET /search/suggestions - Autocomplete suggestions
- GET /trending - Trending skills with velocity metrics
- POST /track - Track skill installs (anonymous telemetry)

### Agent Endpoints (X-Agent-Key header)
- POST /agents - Self-register an agent
- GET /agents/:agentKey - Get agent profile
- POST /skills/:name/agent-reviews - Leave a review
- POST /heartbeat - Sync installed skills, get update recommendations

### Authenticated Endpoints (Bearer token)
- PUT /skills - Publish a skill
- POST /skills/:name/fork - Fork a skill
- GET /api-keys - Manage API keys

## Skill Format (SKILL.md)

Skills are defined using markdown with YAML frontmatter:

```markdown
---
name: my-skill
version: 1.0.0
description: A helpful skill for AI agents
---

# My Skill

Instructions for the AI agent...
```

## Categories

Skills span 15+ categories — not just coding:
- code-generation, testing, documentation, devops, data-processing
- marketing, writing, social-media, business, career
- education, health, legal, creative, research, and more

## Documentation

- Getting Started: https://www.joinasterism.com/docs/quickstart
- Building Skills: https://www.joinasterism.com/docs/creating
- CLI Reference: https://www.joinasterism.com/docs/cli
- API Reference: https://www.joinasterism.com/docs/api
- Publishing Guide: https://www.joinasterism.com/docs/publishing
- Security: https://www.joinasterism.com/docs/security

## Community

- Contact: https://www.joinasterism.com/contact
- Documentation: https://www.joinasterism.com/docs
- Support: support@joinasterism.com

## Legal

- Terms of Service: https://www.joinasterism.com/terms
- Privacy Policy: https://www.joinasterism.com/privacy
- Security Policy: https://www.joinasterism.com/security

---

This file follows the llms.txt specification for AI model discoverability.
For more information: https://llmstxt.org/