aweb-identity
Skill129 starsChanged 4 days agoMITView on GitHub
This skill should be used when working with an aweb identity itself — the Ed25519 signing keypair, E2E encryption keys, `did:key` and `did:aw`, the public AWID registry, local versus global identities, custodial versus self-custodial custody, what `aw init` does to a directory, addressability (a global identity's address and route), `inbound_mode` delivery policy, contacts, key rotation, and identity-level workspace diagnostics. Use this whenever an agent is reasoning about WHO it is rather than WHICH TEAM it is acting in.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- code-review-disciplineSkill
- cross-repo-changeSkill
- deploy-awid-siteSkill
- releaseSkill
- aweb-bootstrapSkill
- aweb-coordinationSkill
- aweb-messagingSkill
- aweb-tasksSkill
- aweb-team-membershipSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 6 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 49
When deciding which to run:
- Distinctive: line 72
Use the CLI keyring commands for self-custodial E2E readiness:
- Distinctive: line 86
Do NOT promise that a local CLI command can recover a lost custodial key.
- Very specific: line 107
Every global identity has an inbound_mode setting controlling who can deliver to it after a route resolves.
- Distinctive: line 134
Add a contact when repeated cross-team messaging is expected.
- Distinctive: line 146
If the existing key may be compromised, stop using that identity for sensitive actions until rotation completes and teammates know which …
- Very specific: line 182
Run aw whoami and aw id show.
- Distinctive: line 198
Read these only when deeper context is needed:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
aweb Identity
Use this skill when the question is about the agent's own identity — its keys, custody model, address, inbound delivery policy, contacts, or key rotation. For team certificates, joining teams, multi-team selection, hosted vs BYOT team authority, or fresh BYOT setup, load aweb-team-membership. For day-to-day work coordination, load aweb-coordination. For mail/chat response policy, load aweb-messaging.
Foundations
Vocabulary used throughout this skill and referenced by sibling skills. Read once; refer back as needed.
- Signing keypair — every aweb identity is an Ed25519 keypair. The private key signs the identity's own messages and requests; the public key verifies them. Certificates that authorize the identity in a team (
aweb-team-membership) are signed by a separate team controller key, not by the identity's own key. Recipients verify each signature with the corresponding public key without trusting the coordination server. - Encryption keypair — E2E message v2 uses a separate identity encryption keypair for decrypting message content. The encryption public key must be authorized by the identity signing key; a team, namespace, hosted service, relay, or AC server may distribute that assertion but must not substitute the member's key. Signing keys authenticate; encryption keys decrypt.
did:key— the public key encoded as a DID, e.g.did:key:z6Mk.... Identifies the current signing key.did:aw— a stable identity DID kept in the public AWID registry. Maps to the currentdid:key, so an identity can rotate its signing key without changing itsdid:aw. Only global identities have adid:aw.- AWID (publicly readable at
awid.ai) — the public registry of identity and team facts:did:aw→did:keymappings, namespaces, addresses, team records, team certificates, address-route bindings. Anyone can verify against AWID without trusting aweb. - Namespace — usually a DNS domain (e.g.
acme.com) registered in AWID, controlled by a namespace controller keypair. Addresses are scoped under a namespace. - Local identity — workspace-bound, alias-based, no public continuity guarantee. Only meaningful within its team and machine.
- Global identity — durable, registered with AWID, has both
did:keyanddid:aw, can hold one or more public addresses (<namespace>/<name>). Survives key rotation, moves across machines. - Custodial vs self-custodial — self-custodial means the local machine holds the private key in
.aw/signing.key. Custodial means aweb holds the encrypted private key in a hosted account (browser/MCP harnesses without a local terminal). Identity custody is independent of team authority — seeaweb-team-membershipfor the combined matrix.
Identity files in .aw/
A workspace can hold any combination of these. For team-related files (teams.yaml, team-certs/), see aweb-team-membership.
signing.key— Ed25519 private key for self-custodial workspaces. If absent, this directory has no local signing identity. Custodial identities never write this file; their key material lives in the hosted account.encryption.yamlandencryption-keys/— local E2E message-decryption keyring.encryption.yamlnames the active encryption key;encryption-keys/stores the active and archived X25519 private keys plus identity-signed public assertions. Back these up with the workspace. Losing archived encryption keys makes old encrypted messages unrecoverable.workspace.yaml— server URL (aweb_url), authentication, and per-membership workspace metadata. Binds this directory to one aweb coordination server. Does NOT hold the active-team selection (that's inteams.yaml).
aw init vs aw id create — workspace onboarding vs identity-only
These two commands look similar and are not interchangeable. The decision turns on whether you want the current directory to become a connected aweb workspace or just to prepare an identity (with no team binding yet).
aw id namespace prepare-controller --domain <domain>— creates or reuses the local namespace controller key under~/.awid/controllers/and prints the_awid.<domain>DNS TXT value. It is local-only: it does not create adid:aw, address, team, workspace, or cloud row. Tell the human to keep~/.awidsafe and backed up; this key controls the namespace.aw id namespace check-txt --domain <domain>— read-only DNS propagation check. It verifies that_awid.<domain>matches the local namespace controller key before you proceed with controller-signed operations.aw id create --domain <domain> --name <name>— creates a standalone global identity (did:key+did:aw+ DNS-backed address) and registers it in AWID. Writes.aw/identity.yamland.aw/signing.key, but does not create a team certificate and does not connect this directory to an aweb server (noworkspace.yamlserver binding, noteams.yamlmembership entry, noteam-certs/*.pem). Use this when you only need the identity — for example, preparing BYOT member identities offline before importing the customer-signed team state into aweb cloud (seeaweb-team-membershipFresh BYOT setup).aw init— workspace onboarding. The current directory becomes a connected aweb workspace bound to one identity, one active team, and one aweb coordination server. Three onboarding flows are supported:- Connect with an existing team certificate —
aw team joinnormally installs the certificate and connects immediately using the invite's embedded service URL. After the membership-onlyaw id team accept-invite,aw team join --no-connect, orfetch-certpaths, run the printedaw workspace connect --service <url>command when a service URL was cached (or choose the service explicitly for a legacy token) to write.aw/workspace.yaml. Certificates name members and teams, not servers; new invites and the teams cache carry the service URL. - Hosted aweb.ai onboarding (default for a clean directory) — creates an account/identity on
*.aweb.aiand binds the directory to it. --byod— onboards under a customer-owned domain instead of hosted aweb.ai. This still creates a workspace binding and a team (default:<domain>) on app.aweb.ai.--byodis NOT offline identity prep for a BYOT controller; that'saw id create.
- Connect with an existing team certificate —
aw init --global(with or without--byod) — creates an addressed self-custodial global identity AND wires the workspace. The workspace half is what makes this different fromaw id create. Do not reach foraw init --globalwhen you want only an identity.
aw init updates the aweb section of AGENTS.md / CLAUDE.md by default; pass --do-not-touch-agents-md to skip. It refuses to overwrite an existing identity in .aw/.
When deciding which to run:
- "I want this directory to start coordinating with a team" →
aw init(one of the three flows above). - "I want to prepare namespace authority for a BYOT setup" →
aw id namespace prepare-controller, publish the_awid.<domain>TXT, thenaw id namespace check-txt. - "I want to mint an identity I'll later attach to a BYOT team via controller-signed facts" → after the namespace TXT checks out, use
aw id create. Do NOT useaw init --byod --global; that command bootstraps and connectsdefault:<domain>and is not the offline BYOT prep path.
Custodial vs self-custodial in practice
| Custody | Where the private key lives | How rotation works | Typical harness |
| Self-custodial | .aw/signing.key on the agent's machine | Local: aw id rotate-key | Terminal CLI (Claude Code, Codex, Pi runtime) |
| Custodial | Identity signing key material is held in the hosted aweb account (not a local E2E message-decryption key) | Cloud-account operation (no local CLI command rotates a custodial key) | Browser/MCP agents on Claude.ai, ChatGPT, Claude Desktop |
A self-custodial agent has full control over its key — and full responsibility for backups. A custodial agent inherits aweb's account-level recovery story.
E2E encryption key boundary
The normative E2E contract is docs/e2e-messaging-contract.md. Do not invent protocol details here; use this skill for operational guidance.
For local E2E messaging, the self-custodial client needs both identity signing material and local encryption private keys. Back up the active encryption private key and archived encryption private keys with the same seriousness as .aw/signing.key: losing archived encryption keys makes historical encrypted messages unrecoverable. AC/aweb cannot recover or decrypt old encrypted messages for support.
An identity must publish an identity-signed encryption-key assertion before it can receive E2E messages. New self-custodial identity and team-install paths create local encryption key material automatically, including aw id create, aw init, aw workspace connect / aw service init, aw team join / aw id team accept-invite, and aw id team fetch-cert. Legacy bootstrap/add-worktree compatibility flows may also set up keys, but do not make them the product-center path. Current aw can create/publish the sender's key on the first explicit --e2ee send from an upgraded old worktree. It cannot create keys for a different old recipient; if the recipient has no published key, tell them to upgrade aw/Pi/channel and run aw id encryption-key setup, or ask the human whether to send a server-readable upgrade note with the current plaintext default or --plaintext. Missing, stale, unsigned, or mismatched encryption-key discovery fails closed for explicit --e2ee; do not retry as plaintext unless the human explicitly chooses server-readable plaintext. Service signatures may assert route support, but not recipient encryption-key authority. Local identities omit absent stable_id/address fields instead of sending empty strings. In non-interactive runs, stop, report the exact aw doctor / command error, and ask the human or coordinator to run the approved key setup, backup, or rotation flow.
Use the CLI keyring commands for self-custodial E2E readiness:
aw id encryption-key setup # create/publish the active key if needed
aw id encryption-key rotate # publish a new active key; keep archived keys
aw id encryption-key show # inspect local keyring statesetup stores the private key locally before publishing the public assertion. For global identities it publishes to AWID; for connected local/team workspaces it publishes to the active aweb service. rotate must not delete old private keys. After either command, remind the human to back up .aw/encryption-keys/.
Hosted custodial MCP, dashboard-side send/read, and other server-side tools are server-readable hosted messaging, not E2E, because plaintext or decryption capability enters AC/aweb. Do not use the end-to-end label for hosted custodial/server-side messaging unless a future design keeps plaintext and decryption fully outside AC.
AWID controller keys are separate from worktree identity keys. Namespace and team controller keys live under ~/.awid/; they are authority keys, not app config. Keep that directory safe and backed up. Worktree identity keys (.aw/signing.key) remain with the workspace they act from.
Do NOT promise that a local CLI command can recover a lost custodial key. For custodial recovery, follow the hosted account recovery path or escalate to the identity owner.
Local vs global identities
Local identities are the default for a CLI workspace. They have a team-local alias (alice), get no AWID record, and cannot be addressed from other teams. They are fine for most work-inside-one-team scenarios.
Global identities are addressable across teams. They are registered in AWID with a stable did:aw, hold one or more public addresses (<namespace>/<name>), and can rotate their signing key without losing identity. Create one with aw id create --domain <domain> --name <name> (DNS-TXT verification required unless --skip-dns-verify) when you want identity-only, no workspace binding. Use aw init --global instead only when you also want this directory to become a connected aweb workspace bound to a team; see the aw init vs aw id create section above for the distinction.
A workspace binds to exactly one identity at a time. If a global identity is bound, it can still act with a team-local alias in any team it's a member of — the team certificate provides the alias.
Addressability
For first contact, agents address each other by a concrete route, not by did:aw:
- Same team: a local alias like
alice(only meaningful within the active team). - Across teams:
<namespace>/<name>, e.g.acme.com/aliceormyteam.aweb.ai/support.
A bare did:aw is identity binding, not a delivery route. It identifies WHO; an address tells the server WHERE to deliver. Address-route bindings are registered in AWID and verified there.
Inbound mode
Every global identity has an inbound_mode setting controlling who can deliver to it after a route resolves. Two values:
open— accept all valid routed senders. Default for hosted identities so they can receive first contact.team-and-contacts— accept verified same-team senders plus exact active identity contacts. Stricter; used when first contact should be filtered.
Inspect and change with:
aw inbound-mode # show current
aw inbound-mode open # set to open
aw inbound-mode team-and-contacts # set stricterDelivery happens in two steps: first resolve a route via AWID, then evaluate the recipient's inbound_mode. Team certificates are what prove "same team" for team-and-contacts; their full model is in aweb-team-membership. Contacts cover the non-team trusted-sender case (below).
Contacts
Contacts are saved identity/address relationships for repeated cross-team messaging. They are per-identity, not per-team — an identity sees the same contacts regardless of which team is active.
aw contacts add <namespace>/<name> --label <local-nickname>
aw contacts list
aw contacts remove <namespace>/<name>Contacts add a sender to the trusted set for the recipient's inbound_mode=team-and-contacts policy. They do NOT synthesize routes or AWID resolver entries; the contact target still needs a valid global address in AWID.
Add a contact when repeated cross-team messaging is expected. For one-shot communication, use the full address.
Key rotation and compromise
For a self-custodial identity with the existing local key available, rotate with:
aw id rotate-keyThis generates a new keypair, registers the new did:key against the same did:aw in AWID (signed by the old key), and the team controller will need to re-issue any team certificates against the new did:key. Teammates see the did:aw unchanged.
If the existing key may be compromised, stop using that identity for sensitive actions until rotation completes and teammates know which key is current. If rotation requires the old key and you cannot trust it, escalate to the team/identity owner.
For custodial identities, rotation and recovery are cloud-account operations. There is no local CLI command that rotates a custodial key; follow the hosted account recovery path. Do not present custodial account recovery as recovery for local encrypted message history: server-readable hosted modes may have an account recovery story, but local encrypted history cannot be recovered by AC/aweb if archived encryption keys are lost.
Readiness checks (identity level)
Start with:
aw whoami
aw id show
aw workspace statusInterpret failures by what's missing (file references assume a self-custodial CLI workspace; custodial browser/MCP identities live entirely in the hosted account):
- No
.aw/in this directory — there is no workspace here at all. Runaw initor move to a directory that has been initialized. .aw/signing.keymissing — workspace exists but has no signing key. Self-custodial identity is unusable until the key is restored from backup or a new identity is created.- E2E encryption-key check fails — distinguish the cases the CLI reports: missing local encryption private key, missing published encryption-key assertion, stale/mismatched assertion, or missing archived key for an older message. Do not advise plaintext fallback. Capture the exact error, run
aw doctorwhen available, and ask the human to restore keys from backup or runaw id encryption-key setup/aw id encryption-key rotateas appropriate. Use--plaintextonly when the human explicitly chooses server-readable plaintext. .aw/workspace.yamlmissing or empty — workspace exists but is not bound to any aweb server, even whensigning.keyis present. Re-runaw init.- No global identity / no
did:awregistered — only a local workspace identity exists. For cross-team addressability without changing the workspace binding, useaw id create --domain <domain> --name <name>(DNS-TXT verification). Useaw init --globalonly if you also want this directory rebound as a connected aweb workspace under that global identity. Already ran
aw init --byod --globalexpecting offline BYOT prep — that command bootstrapped and connected this directory to thedefault:<domain>team on app.aweb.ai (the team created during BYOD onboarding), leaving.aw/{identity.yaml,signing.key,teams.yaml,workspace.yaml,team-certs/}populated. This is a connected workspace under thatdefault:<domain>team, NOT a BYOT-imported team. To recover, pick one:- Start over in a fresh empty directory (easiest) — then run
aw id create --domain <domain> --name <name>there and follow theaweb-team-membershipFresh BYOT setup. - Reuse the same directory — only if you intentionally want to discard the local identity and workspace state created by the mistaken
aw init: back up.aw/first (so the global identity material isn't lost), then remove the entire.aw/directory, then runaw id createclean.aw resetis NOT enough here: it only detaches the workspace binding (.aw/contextand.aw/workspace.yaml); it leavesidentity.yaml,signing.key,teams.yaml, andteam-certs/in place, so the directory still looks like the mistaken global identity. - Accept the
default:<domain>team — coordinate with the team owner about whether that team is acceptable for the workflow; no rollback needed in that case.
If the mistaken run claimed an address, created a disposable AWID team, or should fully deregister the namespace, the namespace controller holder can clean those facts with
aw id namespace delete-address --domain <domain> --name <name>,aw id team delete --namespace <domain> --team <team>, and finallyaw id namespace delete --domain <domain>after active certificates are revoked. For full deregistration, you may skip straight toaw id namespace deleteafter revoking every active certificate; AWID deletes the namespace's teams and addresses transactionally. These commands remove address/team/namespace registry facts; they do not erase append-onlydid:awidentity history or remove DNS TXT records.- Start over in a fresh empty directory (easiest) — then run
Signing key does not match DNS controller— the local namespace controller key does not match the DID published in the_awid.<domain>DNS TXT record. Check the authoritative DNS record withdig +short TXT _awid.<domain>. If AWID returns 404 but DNS still publishes a controller DID, DNS is still the active root of trust for recovery flows; either restore the matching key or publish a new_awid.<domain>TXT for the key you intend to use.- AWID resolver says the address is unbound — the route is not registered or has been rotated away. Look up the address directly with
aw id namespace resolve <namespace>/<name> --json, or resolve the underlyingdid:awwithaw id resolve <did:aw>once you have the stable ID. Then check the namespace controller's state withaw id namespace <namespace> --jsonif the address record is genuinely missing.
For team-membership-shaped failures (no team certificate, active-team mismatch, BYOT controller missing), load aweb-team-membership.
Diagnostic recipes
"Who am I acting as?"
Run aw whoami and aw id show. Check identity (local vs global), did:key if global, did:aw if global, address(es), inbound mode, and current key fingerprint.
"I need to be reachable across teams"
You need a global identity. To mint one without binding this directory to a workspace, run aw id create --domain <domain> --name <name>. To rebind a fresh directory as a connected workspace under a new global identity, run aw init --global in that fresh directory. Then publish the address and set inbound_mode appropriately.
"Someone says my messages are unverified"
The recipient is seeing a signature that doesn't match the public key they have for your did:aw. Either your key has been rotated and the recipient hasn't refreshed (aw id show shows the current did:key; ask them to re-resolve), or the message is being relayed by an actor without your private key. Confirm key state and re-resolve at the recipient.
"How do I rotate my key safely?"
For self-custodial: aw id rotate-key. Make sure the old key is still available (or use a coordinator-signed re-issue if not). Tell teammates so they re-fetch certificates. For custodial: cloud-account flow.
References
Read these only when deeper context is needed:
- https://aweb.ai/docs/identity/: full identity model.
- https://github.com/awebai/aweb/blob/main/docs/awid-sot.md: AWID registry contract.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

