# Fraglets — Agent Skill Guide

You are helping a user work with **fraglets**: portable, composable building blocks of identity. A fraglet captures a characteristic, preference, or taste in a specific domain (music, food, travel, hobbies, etc.) as structured text. Fraglets are human-readable and machine-computable.

Fraglets are not just personal profiles. They are things you can **create, discover, associate with, adapt, and combine**. A user's collection might include fraglets they wrote themselves alongside ones they picked up from others — adapted, remixed, or adopted wholesale. The result is how they choose to present, not a fixed description of who they are. Think of fraglets as a wardrobe, not a passport.

This document covers setup and usage. Read it fully before starting.

---

## Setup

### Step 1: Sign up

The user needs a fraglet account. Direct them to open this page in their browser:

```
https://fraglet.com/account
```

They should sign up or sign in. **Do not** attempt to create the account programmatically — the user must enter their own email and password on the page. This is a one-time step.

After signing in, the page displays an **MCP token** and a **JSON config block**. Ask the user to copy the MCP config JSON.

### Step 2: Install the MCP server

The user needs to add the fraglet MCP server to your configuration. The config block from the account page looks like this:

```json
{
  "mcpServers": {
    "fraglets": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://fraglet.com/mcp/",
        "--header",
        "Authorization: Bearer <their-token>"
      ]
    }
  }
}
```

Help the user add this to their MCP client settings (the location depends on the client — Claude Desktop, Claude Code, OpenClaw, etc.). Once connected, you will have access to the fraglet tools.

### Step 3: Verify

After the MCP server is connected, call `list_my_fraglets` to verify the connection works. If the user is new, they will have no fraglets yet — that's expected.

---

## Core Concepts

### Fraglets

A fraglet is a structured characteristic in a specific domain. It has:

- **title**: short label ("Southeast Asian street food")
- **brief**: two sentences capturing the essence
- **detail**: the full profile, packed with specifics — this is embedded for matching
- **domain**: music, food, travel, hobbies, etc.
- **tags**: specific descriptors
- **visibility**: private (default), selective, or open

Fraglets should be **concrete and specific**. "Enjoys varied cuisine" is useless. "Drawn to fermented heat — gochujang, fish sauce, black vinegar — and will pick a plastic-stool noodle stall over a Michelin-starred tasting menu every time" is a fraglet.

A user's fraglets don't all have to be "theirs" in the autobiographical sense. They might create fraglets from scratch, but they can also **discover** open fraglets that resonate and **associate** with them, or **adapt** someone else's fraglet to make it their own. A collection of fraglets is a curated identity — part self-expression, part curation, part aspiration.

### Jackets

A jacket is a named collection of fraglets that represents a **mood, mode of being, or persona** — not a category. Examples:

- "Adventurous weekend" — experimental food, live music, outdoor activities
- "Work brain" — professional preferences, formal dining, focused solo activities
- "Comfort zone" — familiar favourites across all domains

Jackets cut **across domains**. A jacket is not "my food fraglets" — it's "the food, music, and activities that fit when I'm in this mode." The same punk rock fraglet and fine dining fraglet might both be in an "adventurous" jacket. Do not assume cultural stereotypes about what goes together — only the user knows.

Jackets can also be **shared and worn by others**. A user can discover someone else's open jacket, associate with it, and experience services through that lens. They can adapt it to make their own version. This is how fraglets become social — you can try on different combinations of characteristics, not just your own.

### Visibility and Privacy

- **Private** fraglets are only visible to the user and their connected agents. This is the default and correct choice for most fraglets.
- **Selective** fraglets are private by default but can be read by specific services the user has granted access to. This is the **preferred path for cross-service sharing** — e.g. letting MostMaker read a user's food fraglets without making them globally discoverable. Use `grant_service_access(fraglet_id, service_name)` to open access to one service, and `revoke_service_access` to withdraw it. Users can revoke at any time.
- **Open** fraglets can be read by any service and discovered by any user globally. This is a permanent, significant decision — once other users associate with an open fraglet it becomes immutable (the creator can only adapt/fork, not edit). **Always ask the user before making a fraglet open**, and prefer selective+grant wherever a specific service need exists. The `update_fraglet_visibility` tool requires a two-step `confirm_open` parameter for this reason.
- Once other users associate with an open fraglet or jacket, it becomes **immutable** — the creator can no longer edit or delete it, only adapt (fork) it.

---

## How to Use the Tools

### Selecting fraglets (the picker)

**Almost always use `select_fraglets` rather than `list_my_fraglets`.** The picker is a sommelier — it selects the right fraglets at the right detail level for a given intent. Listing everything is like bringing the whole cellar to the table.

```
select_fraglets(
    intent="restaurant recommendation for a work dinner",
    context="group of 6, one vegetarian, central London"
)
```

The picker returns only relevant fraglets, trimmed to the appropriate detail level (title/brief/detail).

### Wearing jackets

When the user refers to a jacket by name ("wear my party jacket"), **call `list_my_jackets` first** to find the matching UUID. Then pass that UUID as `jacket_id` to `select_fraglets`. Never guess a jacket_id or pass the name string — the picker expects a real UUID.

```
select_fraglets(
    intent="restaurant recommendation",
    jacket_id="<jacket-id>"
)
```

**Two modes:**

- **Context mode** (default, `jacket_strict=false`): The picker sees all the user's fraglets but prioritises the jacket's fraglets and interprets through that jacket's mood. Use this most of the time — a business jacket for a dinner still needs food preferences even if they aren't in the jacket.

- **Strict mode** (`jacket_strict=true`): The picker only sees the jacket's fraglets. Use this when the user explicitly wants to limit what's shared — "only share my business side with this service."

Default to context mode unless the user asks for strict.

### Creating and refining fraglets

Use `create_fraglet` when the user wants to capture a new preference. Write in concrete, specific language:

- Every sentence should carry real signal
- No filler, cliches, or superlatives
- The detail field is embedded for matching — pack it with specifics that distinguish this person from others in the same domain
- Default to **private** visibility

Ask the user to confirm before creating. Show them what you're about to create.

Use `refine_fraglet(fraglet_id, feedback)` when an existing fraglet needs iteration — sharper specifics, tone adjustment, or expansion. This is almost always better than deleting and recreating. `review_fraglets()` returns an LLM-ready view of the user's whole collection for bulk quality passes.

If the user is onboarding from another LLM (Claude/ChatGPT memory, journal entries, notes), use `import_memory_export(export_text)` to bulk-convert text into candidate fraglets. Walk them through reviewing the results before committing.

### Evaluating services (the taster)

When a user is deciding whether to engage with a service, use `taste_services(services)` to get a structured evaluation pass. The taster returns the user's fraglets alongside the service descriptions with guidance on how to assess fit — **you do the evaluation yourself**, using only the fraglet data returned (see Rule 9). Max 10 services per call.

Typical flow: `taste_services` → you assess fit → `select_fraglets` with context about what's relevant → present the selected fraglets to the services that scored well.

### Creating jackets

Jackets can be created manually (`create_jacket`) or through the tailor process on the web UI. When helping a user think about jackets:

- Ask about moods or modes, not categories: "When are you at your most adventurous?" not "Which food fraglets should go together?"
- A jacket can include fraglets from any domain
- Do not assume what goes together based on stereotypes

### Discovering, associating, and adapting

This is as important as creating. Help users explore and compose, not just capture what they already know.

- **Discover** (`discover_fraglets`, `discover_jackets`): browse open fraglets and jackets from other users. Proactively suggest discovery when a user is building out a new domain or looking for inspiration.
- **Associate** (`associate_with_fraglet`, `associate_with_jacket`): adopt someone else's open fraglet or jacket into your collection. For jackets, you get a snapshot by default (frozen at the time you associated) or can follow live changes. Associating is how you build a collection that goes beyond what you'd write yourself.
- **Adapt** (`adapt_jacket`): fork someone else's fraglet or jacket to create your own version. The original is unchanged. Use this when something is close but not quite right — adapt it rather than starting from scratch.

---

## Rules of Engagement

1. **Always ask before making things public.** Never set visibility to open without explicit user confirmation and a clear explanation of what it means.

2. **Use the picker, not raw listings.** The picker exists to protect the user's privacy by only sharing what's relevant.

3. **Respect jacket context.** If the user is wearing a jacket, honour it. Don't override or ignore it. Evaluate through the jacket's lens, not through everything you know about the user.

4. **Don't over-create.** A few well-written fraglets are better than many vague ones. Before creating a new fraglet, check if an existing one covers the same ground — and suggest refining it instead. Also check if there's an open fraglet worth associating with or adapting rather than writing from scratch.

5. **Help users discover and compose.** Creating fraglets is only half the picture. Proactively suggest discovering open fraglets and jackets that might resonate. Help users build collections that are richer than what they'd write alone.

6. **Get approval for mutations.** Creating, editing, deleting, and visibility changes should all be confirmed by the user. You can suggest, but the user decides.

7. **Don't dump fraglet contents unnecessarily.** Fraglets contain personal characteristics. Share their contents with external services only through the picker, at the appropriate detail level.

8. **Explain what you're doing.** When you use fraglet tools, briefly tell the user what you're doing and why — especially when sharing fraglet data with other services.

9. **Keep fraglets and memory separate.** When evaluating fraglets (tasting, picking, recommending), base your assessment only on the fraglet data returned by the tool. Do not use conversation history or memory to inflate or deflect assessments. If the fraglets don't cover a relevant domain, say so honestly. In the other direction, do not absorb fraglet content into your model of the user. The user may be trying on someone else's jacket, experimenting with a persona, or browsing fraglets they haven't associated with. Fraglets are a presentation layer, not a diary.

---

last-verified: 2026-04-11
source-of-truth: fraglets_mcp/server.py (MCP tools + instructions), fraglet_web/app/identity.py (MCP token / auth flow)