# LifeOS Skill System Architecture and Skill Directory Structure Explained

> Explore the LifeOS skill system architecture and skill directory structure. Learn how modular skills are organized and discovered for seamless integration.

- Repository: [Daniel Miessler 🛡️/LifeOS](https://github.com/danielmiessler/LifeOS)
- Tags: architecture
- Published: 2026-08-12

---

**The LifeOS skill system uses a modular, file-based architecture where each skill is a self-contained folder under `LifeOS/install/skills/` containing a [`SKILL.md`](https://github.com/danielmiessler/LifeOS/blob/main/SKILL.md) manifest and a `Workflows/` subdirectory, discovered at runtime by [`InstallEngine.ts`](https://github.com/danielmiessler/LifeOS/blob/main/InstallEngine.ts) and registered in a global `SkillRegistry`.**

The LifeOS skill system and its skill directory structure enable users to extend the platform without modifying core engine code. Created by Daniel Miessler, this open-source personal operating system treats skills as **plug-and-play modules** that the engine automatically discovers, parses, and exposes through both CLI and web interfaces.

## How the Core Engine Discovers and Loads Skills

The skill loading lifecycle begins in [`LifeOS/Tools/InstallEngine.ts`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/InstallEngine.ts), which implements a three-phase registration process:

1. **Filesystem traversal** – recursively walks `LifeOS/install/skills/` using Node.js fs utilities
2. **Metadata extraction** – parses [`SKILL.md`](https://github.com/danielmiessler/LifeOS/blob/main/SKILL.md) front-matter to build a `Skill` object with `id`, `description`, and `workflows` array
3. **Registry population** – stores the compiled skill in the global `SkillRegistry` available to the rest of the platform

The `Skill` object derives its identifier directly from the folder name, making the filesystem structure the single source of truth for skill organization.

## Skill Directory Structure and Required Files

Every skill follows a lightweight convention with two mandatory elements and optional extensions:

| Element | Required | Purpose |
|---------|----------|---------|
| [`SKILL.md`](https://github.com/danielmiessler/LifeOS/blob/main/SKILL.md) | **Yes** | Human-readable description with YAML front-matter for metadata (name, version, dependencies, inputs/outputs) |
| `Workflows/` | **Yes** | Directory containing Markdown files that define step-by-step procedures the engine can render or invoke |
| Domain-specific assets | No | Templates, prompts, config files, or helper scripts that workflows reference |

### Concrete Example: `WriteStory` Skill Layout

```

LifeOS/install/skills/WriteStory/
├── SKILL.md
├── Workflows/
│   ├── WriteChapter.md
│   ├── Revise.md
│   └── ...
├── AntiCliche.md
└── AestheticProfiles.md

```

The additional Markdown files ([`AntiCliche.md`](https://github.com/danielmiessler/LifeOS/blob/main/AntiCliche.md), [`AestheticProfiles.md`](https://github.com/danielmiessler/LifeOS/blob/main/AestheticProfiles.md)) serve as **reusable prompt snippets** imported by workflows—demonstrating how skills can package both procedural logic and composable content.

## Runtime Workflow Execution Flow

When a user invokes a skill (e.g., `lifeos run WriteStory`), the command dispatcher coordinates across three architectural layers:

- **SkillRegistry lookup** – resolves the skill ID to its registered metadata and workflow list
- **Workflow selection** – presents available operations (e.g., *WriteChapter*, *Revise*)
- **LLM execution** – feeds the selected workflow's Markdown prompts to the model engine

The LLM abstraction layer lives in [`LifeOS/Tools/DeployCore.ts`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/DeployCore.ts) and [`LifeOS/Tools/DeployComponents.ts`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/DeployComponents.ts), which handle model-specific APIs while remaining **agnostic to skill content**. This separation ensures skills define *what* to do while the core handles *how* to invoke the underlying models.

## Built-in Skills Included in the Repository

The default installation ships with four reference implementations illustrating the directory structure's flexibility:

| Skill | Purpose | Notable Workflows |
|-------|---------|-------------------|
| `Art/` | Visual generation and diagramming | [`Visualize.md`](https://github.com/danielmiessler/LifeOS/blob/main/Visualize.md), [`Mermaid.md`](https://github.com/danielmiessler/LifeOS/blob/main/Mermaid.md) |
| `Fabric/` | Pattern execution and management | [`ExecutePattern.md`](https://github.com/danielmiessler/LifeOS/blob/main/ExecutePattern.md), [`UpdatePatterns.md`](https://github.com/danielmiessler/LifeOS/blob/main/UpdatePatterns.md) |
| `Telos/` | Report writing and information extraction | [`WriteReport.md`](https://github.com/danielmiessler/LifeOS/blob/main/WriteReport.md), [`InterviewExtraction.md`](https://github.com/danielmiessler/LifeOS/blob/main/InterviewExtraction.md) |
| `WriteStory/` | Creative writing assistance | [`WriteChapter.md`](https://github.com/danielmiessler/LifeOS/blob/main/WriteChapter.md), [`Revise.md`](https://github.com/danielmiessler/LifeOS/blob/main/Revise.md) |

Each follows identical structural conventions while serving entirely different domains.

## How to Create a New Skill

Add a custom skill to your LifeOS installation by following these steps:

1. **Create the skill folder** under `LifeOS/install/skills/` using the desired skill name (e.g., `MySkill`)

2. **Add [`SKILL.md`](https://github.com/danielmiessler/LifeOS/blob/main/SKILL.md)** with proper front-matter:

```markdown
---
id: MySkill
title: My Custom Skill
version: 0.1.0
description: A short description of what the skill does.
---

```

3. **Create the `Workflows/` subdirectory** with Markdown files describing each supported operation

4. **(Optional)** Include supporting assets—prompt templates, static data, or TypeScript helper modules

5. **Register the skill** by running `lifeos install` or restarting the server

The engine will auto-detect the new skill on next startup without code changes.

## Key Source Files for Skill System Development

| File Path | Responsibility |
|-----------|--------------|
| [`LifeOS/Tools/InstallEngine.ts`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/InstallEngine.ts) | Skill discovery, [`SKILL.md`](https://github.com/danielmiessler/LifeOS/blob/main/SKILL.md) parsing, `SkillRegistry` construction |
| [`LifeOS/Tools/DeployCore.ts`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/DeployCore.ts) | LLM abstraction layer for prompt execution |
| [`LifeOS/Tools/DeployComponents.ts`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/DeployComponents.ts) | Component-level deployment logic (model selection, caching) |
| `LifeOS/install/skills/<SkillName>/SKILL.md` | Per-skill metadata manifest |
| `LifeOS/install/skills/<SkillName>/Workflows/*.md` | Executable workflow definitions |
| [`LifeOS/SKILL.md`](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/SKILL.md) | Top-level documentation of skill conventions |

## Summary

- **Skills are filesystem-based modules** under `LifeOS/install/skills/` with mandatory [`SKILL.md`](https://github.com/danielmiessler/LifeOS/blob/main/SKILL.md) and `Workflows/` components
- **Automatic discovery** via [`InstallEngine.ts`](https://github.com/danielmiessler/LifeOS/blob/main/InstallEngine.ts) eliminates registration boilerplate
- **Clean separation of concerns**: skills define content, [`DeployCore.ts`](https://github.com/danielmiessler/LifeOS/blob/main/DeployCore.ts) handles LLM integration
- **Zero-downtime extensibility**: new skills become available after `lifeos install` or server restart
- **Reference implementations** in `Art/`, `Fabric/`, `Telos/`, and `WriteStory/` demonstrate real-world patterns

## Frequently Asked Questions

### What happens if a skill folder lacks a SKILL.md file?

The [`InstallEngine.ts`](https://github.com/danielmiessler/LifeOS/blob/main/InstallEngine.ts) scanner skips any folder without [`SKILL.md`](https://github.com/danielmiessler/LifeOS/blob/main/SKILL.md), so the skill will not appear in `SkillRegistry` or CLI/UI listings. This is the primary filter for valid skill detection.

### Can skills depend on other skills or external packages?

Yes. The [`SKILL.md`](https://github.com/danielmiessler/LifeOS/blob/main/SKILL.md) front-matter supports a `dependencies` field where you can declare required skills or npm packages. The install engine validates these before registration, though the exact dependency resolution implementation should be checked against the current [`InstallEngine.ts`](https://github.com/danielmiessler/LifeOS/blob/main/InstallEngine.ts) version.

### How do I debug why my skill isn't appearing in the registry?

Verify three things: (1) the folder resides directly under `LifeOS/install/skills/`, (2) [`SKILL.md`](https://github.com/danielmiessler/LifeOS/blob/main/SKILL.md) exists with valid YAML front-matter including an `id` field, and (3) you've run `lifeos install` or restarted the server since creation. Check [`InstallEngine.ts`](https://github.com/danielmiessler/LifeOS/blob/main/InstallEngine.ts) console output for parsing errors during startup.