diff --git a/doc/pragma-skiss.txt b/doc/pragma-skiss.txt
new file mode 100644
index 0000000000000000000000000000000000000000..e941fb4cbce449dbd51a6a8583898e1ee7bb8cb9
--- /dev/null
+++ b/doc/pragma-skiss.txt
@@ -0,0 +1,31 @@
+A pragma "packet" is a sequence of fields, where each field is
+a labcomm sample (in order to keep labcomm in-band self-describing).
+
+A pragma packet has a type, which is a globally unique string 
+(e.g., java package-like name, URI, or UUID)
+
+One predefined pragma sample type is labcomm_type_ref, which is used to refer
+to labcomm sample types in a way that is unique on a given encoder/channel.
+
+Sending:
+
+/* create a pragma packet for pragma type type
+   allocated in e->memory */
+// (or, if that is visible to user code, should
+// the parameter be a struct labcomm_memory*?)
+struct labcom_pragma_packet * = labcomm_pragma_new(struct labcomm_encoder e*,
+                                                   char *type);
+
+/* add type reference field*/
+void labcomm_pragma_add_ref(struct labcomm_signature sig);
+
+// the semantics if more than one type reference field is undefined
+// (as far as labcomm is concerned). 
+// One possible (pragma-type defined) semantic is that the latest type 
+// reference applies to the fields following it.
+
+
+// an example session
+struct labcom_pragma_packet pp = labcomm_pragma_new(enc, some_type));
+labcomm_pragma_add_ref(some_sig);
+labcomm_pragma_send(pp, enc);