# `MingaAgent.Skills`
[🔗](https://github.com/jsmestad/minga/blob/main/lib/minga_agent/skills.ex#L1)

Skills system for context-aware prompt injection.

Skills are Markdown files that provide specialized instructions for
specific tasks. They live in `~/.config/minga/skills/` (global) and
`.minga/skills/` (project-local). Each skill is a directory containing
a `SKILL.md` file with YAML-style frontmatter and instruction body.

## Skill format

    ---
    name: plan
    description: Plan mode for complex tasks
    activates_on:
      - plan
      - design
      - scope
      - feature
    ---

    # Planning Instructions

    When planning a feature, always...

## Loading

Skills can be activated:
- Explicitly via `/skill:name` in chat
- Automatically when user prompts match `activates_on` keywords

Multiple skills can be active simultaneously.

# `skill`

```elixir
@type skill() :: %{
  name: String.t(),
  description: String.t(),
  activates_on: [String.t()],
  instructions: String.t(),
  path: String.t(),
  source: :global | :project | :extension
}
```

A discovered skill with metadata and instructions.

# `auto_activate`

```elixir
@spec auto_activate([skill()], String.t()) :: [skill()]
```

Returns skills whose `activates_on` keywords match the given text.

Performs case-insensitive word boundary matching. A keyword "plan"
matches "let's plan this" but not "airplane".

# `discover`

```elixir
@spec discover(String.t() | nil) :: [skill()]
```

Discovers all available skills from global and project directories.

Project-local skills override global skills with the same name.

# `find`

```elixir
@spec find(String.t(), String.t() | nil) :: {:ok, skill()} | :not_found
```

Finds a skill by name from the discovered skills.

# `format_for_prompt`

```elixir
@spec format_for_prompt([skill()]) :: String.t() | nil
```

Formats active skills into a system prompt section.

# `parse_skill_file`

```elixir
@spec parse_skill_file(String.t(), :global | :project) ::
  {:ok, skill()} | {:error, term()}
```

Parses a SKILL.md file into a skill struct.

Extracts YAML-style frontmatter (between `---` delimiters) for metadata
and uses the remainder as instruction text.

# `summary`

```elixir
@spec summary(String.t() | nil) :: String.t()
```

Returns a human-readable summary of all discovered skills.

---

*Consult [api-reference.md](api-reference.md) for complete listing*