niko/ai-superpower
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
191f9f4f2a
ai-superpower/.ai/README.md
moilanik 191f9f4f2a refactor(ai-skills): harden control flow and reduce instruction drift 
Tighten root/core control flow, add dedicated post-mortem, web, and
context-hygiene capabilities, and reduce instruction drift through clearer
ownership, conflict-priority handling, and README/docs workflow alignment.
This makes long-session AI behavior more deterministic while keeping the
instruction system compact and maintainable.
2026-04-21 16:01:21 +03:00

2.3 KiB
Raw Blame History

.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