Skip to main content
Custom commands in Skript allow you to create powerful, user-friendly interactions for your server. Commands can include permissions, cooldowns, usage messages, and more.

​
Basic Command Structure

A simple command consists of a command declaration, optional properties, and a trigger section that executes when the command is run. 
command /broadcast <text>:
	permission: skript.example.broadcast
	description: Broadcasts a message to everybody.
	trigger:
		broadcast arg-text
This command broadcasts text to all players on the server. Only users with the skript.example.broadcast permission can use it.

​
Command Properties

Commands support several optional properties:
​
permission
string
Permission node required to use the command
​
description
string
Description shown in help messages
​
usage
string
Correct usage message displayed when command is used incorrectly
​
aliases
string
Alternative versions of the command (e.g., /i for /item)
​
executable by
string
Restricts who can run the command: players, console, or omit for both
​
cooldown
timespan
Time players must wait between uses
​
cooldown message
string
Message shown when command is on cooldown (use %remaining time%)
​
cooldown bypass
string
Permission to bypass the cooldown

​
Multi-Argument Commands

Commands can accept multiple arguments, with optional arguments in square brackets. 
command /home <text> [<text>]:
	description: Set, delete or travel to your home.
	usage: /home set/remove <name>, /home <name>
	permission: skript.example.home
	executable by: players
	trigger:
		if arg-1 is "set":
			if arg-2 is set:
				set {homes::%uuid of player%::%arg-2%} to player's location
				send "Set your home <green>%arg-2%<reset> to <grey>%location of player%<reset>" to player
			else:
				send "You must specify a name for this home." to player
		else if arg-1 is "remove":
			if arg-2 is set:
				delete {homes::%uuid of player%::%arg-2%}
				send "Deleted your home <green>%arg-2%<reset>" to player
			else:
				send "You must specify the name of this home." to player
		else if arg-2 is set:
			send "Correct usage: /home set/remove <name>" to player
		else if {homes::%uuid of player%::%arg-1%} is set:
			teleport player to {homes::%uuid of player%::%arg-1%}
		else:
			send "You have no home named <green>%arg-1%<reset>." to player
This command demonstrates:
  • Required first argument (<text>)
  • Optional second argument ([<text>])
  • Checking if arguments are set with if arg-2 is set
  • Player-only execution
  • Usage message for incorrect syntax

​
Commands with Cooldowns and Aliases

aliases:
	# Creates an alias `blacklisted` for this list of items.
	blacklisted = TNT, bedrock, obsidian, spawner, lava, lava bucket

command /item <items>:
	description: Give yourself some items.
	usage: /item <items...>
	aliases: /i
	executable by: players
	permission: skript.example.item
	cooldown: 30 seconds
	cooldown message: You need to wait %remaining time% to use this command again.
	cooldown bypass: skript.example.cooldown
	trigger:
		if player has permission "skript.example.item.all":
			give argument to player
		else:
			loop argument:
				if loop-item is not blacklisted:
					give loop-item to player
				else:
					send "<red>%loop-item%<reset> is blacklisted and cannot be spawned." to player
This advanced command shows:
  • Command alias (/i as shorthand for /item)
  • 30-second cooldown with custom message
  • Cooldown bypass permission
  • Item blacklist using local aliases
  • Permission-based filtering
  • Item type arguments that accept Skript aliases
The %remaining time% variable in cooldown messages automatically displays the time left before the command can be used again.

​
Accessing Arguments

Use these patterns to access command arguments:
  • arg-1, arg-2, arg-3 - Individual arguments by position
  • arg-text or argument - All arguments as a single value
  • arguments - All arguments as a list
Arguments are 1-indexed, so the first argument is arg-1, not arg-0.

​
Command Cooldowns

Cooldowns prevent command spam and can be configured per-command: 
cooldown: 30 seconds
cooldown message: You need to wait %remaining time% to use this command again.
cooldown bypass: skript.example.cooldown
By default, cooldown data is stored in memory. To persist cooldowns across restarts, you can configure cooldown storage in config.sk:
Set keep command last usage dates: true in config.sk if you need to access the last usage date expression in your scripts.

​
Best Practices

Organize permissions hierarchically: servername.feature.actionExample: skript.example.broadcast, skript.example.item.all
Always include a usage message to help players understand command syntax:
usage: /home set/remove <name>, /home <name>
Check if optional arguments are set before using them:
if arg-2 is set:
    # Use arg-2 safely
else:
    send "You must specify a name." to player
Store player data using UUIDs instead of names to handle name changes:
set {homes::%uuid of player%::%arg-2%} to player's location
See Configuration for command-related settings:
  • case-insensitive commands - Accept commands regardless of case
  • keep command last usage dates - Persist cooldown data

Build docs developers (and LLMs) love

Get started for freeTalk to us