LifeOS Skill System Architecture and Skill Directory Structure Explained

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 manifest and a Workflows/ subdirectory, discovered at runtime by 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, 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 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	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, 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 and 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, Mermaid.md
Fabric/	Pattern execution and management	ExecutePattern.md, UpdatePatterns.md
Telos/	Report writing and information extraction	WriteReport.md, InterviewExtraction.md
WriteStory/	Creative writing assistance	WriteChapter.md, 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 with proper front-matter:

---
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	Skill discovery, SKILL.md parsing, SkillRegistry construction
LifeOS/Tools/DeployCore.ts	LLM abstraction layer for prompt execution
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	Top-level documentation of skill conventions

Summary

• Skills are filesystem-based modules under LifeOS/install/skills/ with mandatory SKILL.md and Workflows/ components
• Automatic discovery via InstallEngine.ts eliminates registration boilerplate
• Clean separation of concerns: skills define content, 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 scanner skips any folder without 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 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 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 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 console output for parsing errors during startup.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}