Skill Framework

Lithos introduces a Skill Framework to help AI agents (like the one writing this!) understand how to interact with your codebase and vault effectively. Skills bridge the gap between human intent and agent execution by encoding domain-specific knowledge into reusable instruction sets.

What is a Skill?

A Skill is a structured document that teaches an agent how to perform a specific high-value task. It captures domain knowledge, conventions, and constraints that would otherwise be lost or require constant repetition. Think of skills as "recipes" for AI agents — they know what ingredients to use, what order to follow, and what the final dish should look like.

Each skill defines the rules, schemas, and workflows needed to produce consistent, high-quality output. This is particularly valuable in documentation projects where consistency across dozens of pages is paramount. Without skills, every interaction with an agent starts from scratch, leading to inconsistent formatting, missing metadata, and broken cross-references.

The skill framework is inspired by the broader trend of "agentic workflows" where AI agents are given structured instructions rather than free-form prompts. By encoding project conventions into skills, you ensure that AI-generated content meets the same quality bar as human-written documentation.

Structure

Skills are stored in the skills/ directory at the project root. Each skill occupies its own folder containing a SKILL.md file and optional resources like templates or example files.

skills/
├── lithos-doc/
│   └── SKILL.md           # General documentation creation
├── lithos-feature/
│   └── SKILL.md           # Feature page creation
├── lithos-landing/
│   └── SKILL.md           # Landing page editing
├── obsidian-bases/
│   └── SKILL.md           # Base file creation
├── academic-post/
│   └── SKILL.md           # Blog post creation
├── academic-project/
│   └── SKILL.md           # Project documentation
└── academic-research/
    └── SKILL.md           # Research evaluation

Skill Definition (SKILL.md)

A skill definition includes several key sections that guide the agent through task execution. The frontmatter provides metadata for skill discovery — when an agent sees a request that matches the description, it knows which skill to activate.

1. Frontmatter:
   • name: Unique identifier (kebab-case)
   • description: When to use this skill (used for automatic skill selection)
2. Critical Rules: Non-negotiable constraints ("Do this, Don't do that")
3. Volumetry: Content quantity requirements (paragraphs per section, minimum word counts)
4. Frontmatter Schema: The required metadata for files created by this skill
5. Document Structure: Template for the expected output format
6. Workflow: Step-by-step execution plan

Available Skills

Usage

System-wide Skills

Core skills for the Lithos system are distributed with the repository in the skills/ directory. These skills encode the project's documentation conventions and ensure consistency across all vault content. Future versions may support a global skill directory at ~/.config/lithos/skills for cross-project reuse.

Project-specific Skills

Individual projects can define their own skills in ./skills or .agent/skills. These override or extend system skills, allowing each vault to encode its unique conventions. For example, the Academic vault defines academic-post with specific frontmatter requirements and writing style guidelines.

Invoking Skills

Skills are invoked automatically when an AI agent recognizes a matching task, or explicitly by referencing the skill name. The agent reads the SKILL.md, follows the critical rules, applies the frontmatter schema, and executes the workflow steps in order. The result is a complete, well-formatted file ready for review.