agent-identity-kit

SKILL.md content

# Agent Identity Kit — OpenClaw Skill

A portable identity system for AI agents. Create, validate, and publish `agent.json` identity cards.

## What This Skill Does

- **Creates** agent identity cards (`agent.json`) via interactive setup
- **Validates** identity cards against the Agent Card v1 schema
- **Provides** the JSON Schema for editor integration and CI pipelines

## Quick Start

### Generate a new agent.json

```bash
./scripts/init.sh
```

Prompts you for name, handle, description, owner, and capabilities. Outputs a valid `agent.json`.

### Validate an existing agent.json

```bash
./scripts/validate.sh path/to/agent.json
```

Validates the file against `schema/agent.schema.json`. Requires `ajv-cli` (auto-installs if missing).

## File Structure

```
agent-identity-kit/
├── schema/
│   └── agent.schema.json       # JSON Schema v1 for Agent Cards
├── examples/
│   ├── kai.agent.json           # Full-featured example (Kai @ Reflectt)
│   ├── minimal.agent.json       # Bare minimum valid card
│   └── team.agents.json         # Multi-agent team roster
├── skill/
│   ├── SKILL.md                 # This file
│   └── scripts/
│       ├── init.sh              # Generate a starter agent.json
│       └── validate.sh          # Validate against schema
└── README.md
```

## Schema Fields

| Field | Required | Description |
|-------|----------|-------------|
| `version` | ✅ | Spec version (`"1.0"`) |
| `agent.name` | ✅ | Display name |
| `agent.handle` | ✅ | Fediverse-style handle (`@name@domain`) |
| `agent.description` | ✅ | What the agent does |
| `owner.name` | ✅ | Who's accountable |
| `capabilities` | — | List of capability tags |
| `protocols` | — | Supported protocols (MCP, A2A, HTTP) |
| `trust.level` | — | `new`, `active`, `established`, `verified` |
| `endpoints.card` | — | Canonical URL of the card |
| `links` | — | Website, repo, social links |

## Hosting Your Card

Serve your `agent.json` at a well-known URL:

```
https://yourdomain.com/.well-known/agent.json
```

For multiple agents:

```
https://yourdomain.com/.well-known/agents.json
```

## Integration with forAgents.dev

Register your agent at [foragents.dev](https://foragents.dev) to be indexed in the global agent directory. Verified agents get a badge on their card.

## Spec Reference

Full specification: <https://foragents.dev/spec/agent-card>
JSON Schema: <https://foragents.dev/schemas/agent-card/v1.json>

How this skill works

• The skill checks for an existing identity file at ~/.openclaw/agent-identity.json
• If the file does not exist, it prompts an LLM to generate agent identity components including name, pronouns, role, background story, goals, rules of thumb, and response style
• The LLM response is parsed into a structured JSON object
• The structured identity is saved to ~/.openclaw/agent-identity.json
• The skill returns the loaded or newly generated identity as structured output
• Configuration allows specifying the LLM model via MODEL environment variable

When to use it

• When an agent needs to generate a new identity with custom name, role, backstory, personality, and goals
• When an agent needs to save its current identity for later reuse
• When an agent needs to load a previously saved identity
• When an agent needs to switch to a different saved identity
• When an agent needs to output details of its current identity

Best practices

• Provide agent_name, agent_avatar_url, and agent_bio in configuration
• Ensure agent_avatar_url is a publicly accessible HTTPS URL
• Keep agent_bio concise and descriptive

Example use cases

• Role-playing: Agents can adopt specific personas by setting custom name, avatar, and bio for role-playing scenarios.
• Multi-persona agents: Enables management of multiple identities for agents handling diverse contexts or tasks.
• Branded assistants: Customizes agent identity with brand-specific name, avatar, and bio for branded interactions.

FAQs