How to Create Custom Skills for the LifeOS Skills Library: A Complete Guide

Create custom skills for LifeOS by adding a folder under LifeOS/install/USER/CUSTOMIZATIONS/SKILLS/ containing a SKILL.md front-matter file, workflow markdown files, and optional tools—no registration or core-repo modifications required.

LifeOS is an open-source AI operating system that treats every capability as a skill. The skills architecture enables users to extend or override functionality without forking the core repository. This guide walks through the exact steps to create custom skills for the LifeOS skills library, based on the actual source code in danielmiessler/LifeOS.

---

Understanding the LifeOS Skill Structure

Every skill in LifeOS follows a consistent skill-as-container pattern. At runtime, the system scans the LifeOS/ directory and builds a registry from discovered SKILL.md files.

A complete skill consists of three core components:

Component	Purpose	Location
SKILL.md	Declares name, version, description, and available workflows	LifeOS/install/skills/<SkillName>/SKILL.md (shipped) or LifeOS/install/USER/CUSTOMIZATIONS/SKILLS/<SkillName>/SKILL.md (custom)
Workflows/	Markdown files defining individual operations invoked via Skill("Name") → Workflows/File.md	…/Workflows/ subfolder
Tools/ (optional)	TypeScript or Bash utilities executed at runtime	…/Tools/ subfolder

The core orchestrator lives in LifeOS/SKILL.md. It registers the entire LifeOS skill system and routes user commands to the appropriate workflow based on the skill name mentioned.

---

Customizing Skills Without Forking

LifeOS provides a customization layer specifically designed for user modifications. This layer takes precedence over shipped defaults automatically.

Where to Place Custom Skills

The customization directory is documented in LifeOS/install/USER/CUSTOMIZATIONS/SKILLS/README.md. Files placed here override matching files in the base skill installation:

• Create a subfolder named exactly like the skill you want to customize or create
• Add only the files you want to replace or add
• The runtime checks this folder first; if a file exists, it supersedes the shipped version

No additional registration step is required. The installer's Doctor.ts picks up new skills on the next run through its skill discovery step.

---

How to Add a Brand-New Custom Skill

Follow these five steps to create a completely new skill for the LifeOS skills library:

1. Scaffold the Skill Folder

Create the directory structure under the customization layer:

mkdir -p LifeOS/install/USER/CUSTOMIZATIONS/SKILLS/MyNewSkill/Workflows
mkdir -p LifeOS/install/USER/CUSTOMIZATIONS/SKILLS/MyNewSkill/Tools

2. Create the SKILL.md Front-Matter File

The name field in SKILL.md becomes the canonical identifier used by the router. Place this at LifeOS/install/USER/CUSTOMIZATIONS/SKILLS/MyNewSkill/SKILL.md:

---
name: MyNewSkill
version: 0.1.0
description: Demonstrates a custom skill that echoes a message.
---

# MyNewSkill

This skill simply returns a friendly greeting.

3. Add Workflow Markdown Files

Workflows contain the actual prompt templates. Create LifeOS/install/USER/CUSTOMIZATIONS/SKILLS/MyNewSkill/Workflows/Echo.md:

## Echo Workflow

**Prompt:**  
You are a helpful assistant. Return the text: "Hello from MyNewSkill!"

Workflows can reference other skills using the Skill("Name") DSL, enabling composition across the skills library.

4. (Optional) Add Tool Scripts

For skills requiring code execution, add TypeScript or Bash utilities. Example LifeOS/install/USER/CUSTOMIZATIONS/SKILLS/MyNewSkill/Tools/echo.ts:

export function run() {
  console.log("Hello from MyNewSkill!");
}

5. Run the Doctor to Discover the Skill

Execute the discovery script to register your new skill:

bun LifeOS/TOOLS/Doctor.ts

The doctor lists the new skill and makes it addressable. You can now invoke it with:

Skill("MyNewSkill") → Workflows/Echo.md

---

Key Architectural Principles for Custom Skills

Understanding these patterns ensures your skills integrate properly with the LifeOS runtime:

• Front-matter-driven registration: The name field in SKILL.md is the single source of truth for skill identity
• Override precedence hierarchy: USER/CUSTOMIZATIONS/SKILLS/<SkillName>/ files shadow shipped defaults permanently
• Declarative workflow design: Prompt templates live in markdown, keeping behavior data-driven and editable
• Harness-agnostic execution: The Skill(...) DSL works with Claude Code, Hermes, Cursor, or any AI agent that parses the syntax

---

Example: Complete Custom Skill Implementation

Here is a fully functional custom skill you can drop into your LifeOS installation:

SKILL.md (LifeOS/install/USER/CUSTOMIZATIONS/SKILLS/MyNewSkill/SKILL.md):

---
name: MyNewSkill
version: 0.1.0
description: Demonstrates a custom skill that echoes a message.
---

# MyNewSkill

This skill simply returns a friendly greeting.

Workflow (LifeOS/install/USER/CUSTOMIZATIONS/SKILLS/MyNewSkill/Workflows/Echo.md):

## Echo Workflow

**Prompt:**  
You are a helpful assistant. Return the text: "Hello from MyNewSkill!"

Tool (LifeOS/install/USER/CUSTOMIZATIONS/SKILLS/MyNewSkill/Tools/echo.ts):

export function run() {
  console.log("Hello from MyNewSkill!");
}

---

Summary

• Custom skills live in LifeOS/install/USER/CUSTOMIZATIONS/SKILLS/<SkillName>/ — never modify core repository files
• Three required pieces: SKILL.md front-matter, Workflows/ folder with markdown templates, optional Tools/ for code execution
• No registration needed: The Doctor.ts discovery process automatically detects new skills on each run
• Override mechanism: Files in the customization layer take permanent precedence over shipped defaults
• Harness-agnostic: Skills work across Claude Code, Hermes, Cursor, and compatible AI agents

---

Frequently Asked Questions

What file format does SKILL.md use?

SKILL.md uses YAML front-matter between triple dashes at the top of the file. Required fields are name, version, and description. The name field becomes the canonical identifier that the LifeOS router uses to dispatch commands to your skill.

Can I override an existing LifeOS skill without forking?

Yes. Create a folder under LifeOS/install/USER/CUSTOMIZATIONS/SKILLS/ with the exact same name as the existing skill. Add only the files you want to replace—typically config.toml, custom prompts, or modified workflow markdown. The runtime automatically prefers these override files over the shipped versions.

What programming languages can I use for tools?

LifeOS supports TypeScript and Bash for tool scripts placed in the Tools/ directory. These utilities are invoked by workflows when code execution is required. The tool entry point must export a run() function for TypeScript scripts.

How does LifeOS discover my new skill?

The Doctor.ts installer script—located at LifeOS/TOOLS/Doctor.ts—performs skill discovery on each run. It scans the LifeOS/install/skills/ directory and the USER/CUSTOMIZATIONS/SKILLS/ overlay, building a registry from all SKILL.md files found. No manual registration or configuration file edits are necessary.

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