# .ai Directory Overview

## Purpose
The `.ai` directory contains all the modular skills and configurations that govern the AI's behavior, decision-making, and workflows. It is the central repository for AI instructions.

## Root-Skill: The Master Configuration
The `root-skill` is the **master configuration** and **state machine** for the AI. It must be read first to understand how the AI operates and interacts with other skills.

- **File Location:** `.ai/skills/root-skill/SKILL.md`
- **Key Rules:**
  - Always start by reading `root-skill`.
  - Follow the state machine rules defined in `root-skill`.

## Operational Expectation
This project assumes strict instruction-following once the core rules are loaded.

- After loading `root-skill` and selected skills, the AI must follow them consistently in the same session.
- If behavior drifts or rules are missed, handle it with the `post-mortem` workflow and apply minimal preventive updates.
- Treat this `.ai` folder as the canonical source of instruction truth.

## Skills: Modular Instructions
Each skill is a modular instruction set designed for specific tasks. Skills are located in `.ai/skills/` and follow a consistent structure:
- **File Name:** `SKILL.md`
- **Metadata:** Each skill includes `name`, `description`, and `category`.

### Example Skills:
- **Core Principles:** Foundational behavior and decision-making rules.
- **Git:** Rules for Git operations and workflows.
- **IaC:** Infrastructure as Code principles.

## Local Usage (VS Code UI)
For authoring and skill lifecycle rules, consult `/.ai/skills/write-skill/SKILL.md` which documents when to regenerate the skill manifest.

## Browser-Based AI Usage

For browser-based AI systems loads skills from file: '.ai/skill-list.txt'.

Root skill: https://gitea.nikos-dev.keskikuja.site/niko/ai-superpower/raw/branch/main/.ai/skills/root-skill/SKILL.md

Skill list: https://gitea.nikos-dev.keskikuja.site/niko/ai-superpower/raw/branch/main/.ai/skill-list.txt

When using this project in a browser-based AI, ensure the AI reads `root-skill` first. To avoid scanning the entire directory: Focus on the `name` and `description` metadata in each skill at skill-list.txt document.

## Further read

- https://github.com/mattpocock/skills/tree/main
- https://github.com/anthropics/skills/tree/main