> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/0x48lab/skills/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started with the API

> Add Skills as a dependency, obtain a SkillsAPI instance, and start querying player data from your plugin.

<Steps>
  <Step title="Add Skills as a dependency">
    Add the Skills plugin jar to your project as a `compileOnly` dependency. Because the jar is not published to a public Maven repository, reference it from your local files or a file-system repository.

    ```kotlin build.gradle.kts theme={null}
    dependencies {
        compileOnly(files("libs/skills-0.4.13-all.jar"))
        // or via a local Maven repo:
        // compileOnly("com.hacklab.minecraft:skills:0.4.13")
    }
    ```

    Then declare the dependency relationship in your `plugin.yml`. Use `depend` if your plugin cannot function without Skills, or `softdepend` if Skills is optional.

    ```yaml plugin.yml (hard dependency) theme={null}
    name: MyPlugin
    version: "1.0.0"
    main: com.example.myplugin.MyPlugin
    depend:
      - Skills
    ```

    ```yaml plugin.yml (soft dependency) theme={null}
    name: MyPlugin
    version: "1.0.0"
    main: com.example.myplugin.MyPlugin
    softdepend:
      - Skills
    ```
  </Step>

  <Step title="Obtain the API instance">
    The API is registered with Bukkit's `ServicesManager`. Retrieve it once during `onEnable`.

    ```kotlin theme={null}
    val registration = Bukkit.getServicesManager().getRegistration(SkillsAPI::class.java)
    val api = registration?.provider
    ```

    `registration` is `null` if Skills is not loaded. `provider` returns the live `SkillsAPI` implementation.
  </Step>

  <Step title="Handle soft dependency">
    If Skills is optional, guard every usage with a null check.

    ```kotlin theme={null}
    val api: SkillsAPI? = Bukkit.getServicesManager()
        .getRegistration(SkillsAPI::class.java)?.provider

    if (api == null) {
        logger.info("Skills plugin not found — skill features disabled")
        return
    }
    ```

    <Warning>
      If Skills is declared as `softdepend` and is not installed, `api` will be `null`. Calling any method on a null reference will throw a `NullPointerException`. Always check before use.
    </Warning>
  </Step>

  <Step title="Query player data">
    With a valid `api` reference you can read and modify skill data for any online player.

    **Check a player's skill value**

    ```kotlin theme={null}
    val swordSkill: Double = api.getSkill(player, "Swordsmanship") ?: 0.0
    ```

    **Check if a player meets a minimum skill requirement**

    ```kotlin theme={null}
    if (api.hasSkillLevel(player, "Mining", 50.0)) {
        player.sendMessage("You are skilled enough to use this ore vein.")
    }
    ```

    <Tip>
      Prefer `hasSkillLevel()` over `getSkill()` for threshold checks. It handles the `null` case internally and returns `false` when the skill name is invalid.
    </Tip>

    **Get all skill values at once**

    ```kotlin theme={null}
    val skills: Map<String, Double> = api.getAllSkills(player)
    skills.forEach { (name, value) ->
        println("$name: $value")
    }
    ```

    **Read stats (STR / DEX / INT)**

    ```kotlin theme={null}
    val str: Int = api.getStat(player, "STR") ?: 0
    val dex: Int = api.getStat(player, "DEX") ?: 0
    val int: Int = api.getStat(player, "INT") ?: 0
    ```

    **Read HP, Mana, and Stamina**

    ```kotlin theme={null}
    val currentHp  = api.getCurrentHp(player)
    val maxHp      = api.getMaxHp(player)
    val currentMana = api.getCurrentMana(player)
    val maxMana    = api.getMaxMana(player)
    val stamina    = api.getCurrentStamina(player)
    val maxStamina = api.getMaxStamina(player)
    ```
  </Step>
</Steps>

## Skill name formats

All methods that accept a `skillName: String` parameter are case-insensitive and treat spaces and underscores as interchangeable.

| Format                       | Example                              |
| ---------------------------- | ------------------------------------ |
| Display name (title case)    | `"Swordsmanship"`, `"Mace Fighting"` |
| Enum name (upper snake case) | `"SWORDSMANSHIP"`, `"MACE_FIGHTING"` |
| Lower case with spaces       | `"mace fighting"`                    |
| Lower case with underscores  | `"mace_fighting"`                    |

All four of the examples below refer to the same skill:

```kotlin theme={null}
api.getSkill(player, "Mace Fighting")
api.getSkill(player, "MACE_FIGHTING")
api.getSkill(player, "mace fighting")
api.getSkill(player, "mace_fighting")
```

For a complete list of available skill names see the [skill name reference table](/api/skills-api-reference#skill-name-reference).