Chapter 8

The Skills System

An on-demand knowledge library

🎯

Like Borrowing Books from a Library

You can't memorize every book in a library. But when you know what topic you need, you go and borrow the right book. The Agent's skill system works the same way — it doesn't stuff all knowledge into the prompt. Instead, it "borrows" the relevant skill manual when needed.

Why Do We Need a Skills System?

An LLM's knowledge is limited — it might not know your project's specific conventions, workflows, or best practices. At the same time, the system prompt has a length limit. Cramming everything in would: • Consume massive amounts of tokens (higher cost) • Bury key information • Slow down response time The skills system's solution: normally load only the core prompt, and dynamically load the relevant skill knowledge when the Agent encounters a specific task.

What Does a Skill Look Like?

Each skill is a Markdown file containing metadata and specific knowledge:

Skill File Example

skills/commit.md

1---
2name: commit
3description: Help users create well-formatted Git commits
4---
5
6# Git Commit Guidelines
7
8## When to Use
9Use this skill when the user asks to commit code.
10
11## Workflow
121. Run git status to check changes
132. Run git diff to see specific modifications
143. Analyze changes and compose a commit message
154. Commit message format: type(scope): description
16
17## Notes
18- Don't use git add -A; add files individually
19- Keep commit messages concise — explain "why" not "what"
20- Don't commit files containing secrets

Skill Discovery and Loading

OpenHarness discovers skills from these locations: 1. Built-in skills — Bundled with OpenHarness (e.g., commit, review-pr) 2. User directory — Custom skills in ~/.openharness/skills/ 3. Plugin-provided — Skills registered through the plugin system When the Agent encounters a relevant task, it uses the Skill tool to load the corresponding skill. Once loaded, the skill's content is injected into the current conversation context.

Skill Design Philosophy

Good skills should: ✅ Focus on a single domain — one skill solves one type of problem ✅ Include concrete workflows — not just knowledge, but steps ✅ Describe "when to use" — so the Agent knows when to load it ✅ Provide caveats — prevent common mistakes Bad skills: ❌ Content too broad, tries to cover everything ❌ Only abstract concepts, no concrete steps ❌ Missing description of when to use

📌 Key Takeaway

On-Demand Loading = Efficient + Precise

The core idea of the skills system is "on-demand loading." It solves the "too much knowledge to fit" problem by giving the Agent domain-specific knowledge only when needed. Each skill is just a Markdown file — simple yet powerful.

🧠 Check Your Understanding

Why not put all knowledge into the system prompt?

The Hook System The Memory System