diff --git a/bluesky/README.org b/bluesky/README.org
new file mode 100644
index 0000000..1f4feeb
--- /dev/null
+++ b/bluesky/README.org
@@ -0,0 +1,53 @@
+# -*- ispell-local-dictionary: "english" -*-
+
+* Usage
+
+** compose declaration
+
+No options are needed.
+
+#+begin_src yaml
+bluesky:
+  charm: bluesky  ## line is optional if your service name is "bluesky"
+#+end_src
+
+You might have to configure the domain, if you didn't do it already in
+the frontend service configuration with a service-map.
+
+#+begin_src yaml
+bluesky:
+  charm: bluesky  ## line is optional if your service name is "bluesky"
+  relations:
+    web-proxy:
+      apache:
+        domain: bsky.mydomain.org
+#+end_src
+
+You probably should also make sure that ~smtp-server~ relation is fulfilled if
+you want to be able to verify emails, you could for instance use ~stmp-stub~ to
+provide settings for an external SMTP service:
+
+
+#+begin_src yaml
+bluesky:
+  charm: bluesky  ## line is optional if your service name is "bluesky"
+  # ...
+
+myemail:
+  charm: smtp-stub
+  options:
+    port: 25
+    connection-security: none    # "none", "starttls", "ssl/tls"
+    auth-method: none            # "none", "password"
+    user: myuser
+    password: mypassword
+#+end_src
+
+** request a new invite
+
+To be able to add account, you need to create new invites from your
+PDS to give to people to create accounts.
+
+#+begin_src sh
+compose new-invite bluesky
+#+end_src