diff --git a/slurm_qos/README.md b/slurm_qos/README.md
new file mode 100644
index 0000000..cc89aaf
--- /dev/null
+++ b/slurm_qos/README.md
@@ -0,0 +1,57 @@
+# Slurm QoS Ansible Role
+
+This Ansible role configures Quality of Service (QoS) settings, accounts, and users in a Slurm cluster using the `sacctmgr` command-line tool.
+
+## Overview
+
+The role:
+- Creates or modifies Slurm QoS settings (e.g., `MaxTRES`, `MaxTRESPU`, `MaxSubmitJobs`, etc.).
+- Manages Slurm accounts and users (if defined).
+
+## Prerequisites
+
+- Ansible installed on the control node.
+- Slurm cluster with `sacctmgr` available on the target nodes.
+- Administrative privileges to modify Slurm configurations.
+
+## Role Variables
+
+Variables are defined in `vars/slurm_qos/qos.yml`. Example:
+```
+slurm_qos_settings:
+  - name: normal
+    MaxTRES: node=-1
+    MaxSubmitJobs: 100
+    Preempt: preempt_qos
+  - name: preempt_qos
+    GraceTime: 120
+    MaxTRES: node=4
+    MaxTRESPU: node=4
+    MaxSubmitJobs: 50
+    MaxJobsPerUser: 24
+```
+## Usage
+
+1. Clone or copy this role into your Ansible project (e.g., `roles/slurm_qos/`).
+2. Define your QoS settings in `vars/slurm_qos/qos.yml`.
+3. Include the role in your playbook:
+```
+- hosts: slurm_controller
+  roles:
+    - slurm_qos
+```
+4. Run the playbook:
+   ansible-playbook -i inventory playbook.yml
+
+## Example
+
+To apply the QoS settings shown above:
+1. Ensure `vars/slurm_qos/qos.yml` contains the desired configuration.
+2. Run the playbook targeting your Slurm controller node.
+
+Verify the settings with:
+`sacctmgr show qos format=name,gracetime,maxtres,MaxTRESPU,MaxJobsPU,MaxSubmitPU`
+
+## License
+
+MIT