SoPhi Harness — Transforming Static Files into Self-Generating Skills: Evolving the Skill System of an AI Agent
Static Markdown skills became useful only after SkillTool, /skill, and ADR-030 added retrieval, hierarchy, and self-writing in a Kotlin agent harness.
Key Takeaways
- SoPhi skills started as inert Markdown files: they were loaded early, but had no runtime value until consumers such as SkillTool and /skill arrived.
- The skills module was deliberately decoupled from agent machinery, depending only on Kotlin, YAML parsing, and versioning, not on tools, coroutines, or the agent core.
- SkillTool and /skill made skills usable by loading skill instructions into model context or injecting them directly into a session, with project skills overriding global ones.
- Self-writing skills added later enabled agents to create or install new skill cards, but ADR-030 required safety gates, including static checks for secrets and prompt injection.
- Skill writing and skill verification are separate, staged processes: new cards are trial versions until `sophi skill verify` confirms they actually help later.
Meta description: SoPhi skills system shipped as inert Markdown before agents could read it. Article 07 explains how SkillTool, /skill, and ADR-030 made it useful.
Tags: SoPhi skills, Kotlin agent harness, AI agent instructions, ADR-030, skill verification
Featured image: abstract friendly illustration of an empty recipe box becoming labeled instruction cards for an AI agent, no real people, no logos, no text.
This Article 07 in the Building SoPhi - a Kotlin Agent Harness series is for engineers building agent runtimes on the JVM. It shows how SoPhi skills were shipped early as inert Markdown instruction files, then became useful only after SkillTool, a /skill command, and self-writing skills arrived months later.
Early work stayed inert until consumers arrived
sophi-skills landed during skeleton creation as rough-in work. The module had no useful runtime job on the day it shipped. It stored instructions that nobody was reading yet, and its real value appeared later when another part of the system needed a place to pull them from.
A skill in SoPhi is a single Markdown file with YAML frontmatter, a metadata block at the top of the file. One example card is titled "Deploy runbook", described as "How to deploy this service safely", and tagged with [ops, deploy]. Internally, that file maps to a data class named Skill, with SkillMetadata, a body, and a source: Path.
SkillLoader reads a whole directory eagerly. Every file, every byte, is parsed at startup and sorted by title. SkillRegistry then layers a global directory underneath a project directory, with project entries winning on ID collision. The loader is tolerant of a malformed card through runCatching { loader.loadFile(file) }.getOrNull(), so one bad file does not spoil the whole box.
The lazy part is not loading. It is what happens after loading: a skill body sits parked in Map<String, Skill> and does nothing until something specifically asks for it.
Skills kept the module free of agent machinery
The dependency list made the separation visible. sophi-skills's pom.xml depends on kotlin-stdlib, a YAML parser, and sophi-versioning. sophi-versioning itself is only kotlin-stdlib plus a storage abstraction. The skills module has no sophi-core dependency, no Tool interface, and no coroutines anywhere in that chain.
That design means a skill card can exist without the agent runtime, much as a written recipe does not need a stove to exist. For a while, though, it also meant the skills shelf had no route into the kitchen. SkillLoader and SkillRegistry shipped, worked, and had tests, but there was no caller anywhere for weeks.
SkillTool and /skill opened the shelf
The first consumer was SkillTool, a plain Tool that lets the model load a skill's instructions into context. Its name is "skill". Its description begins with "Load a skill's instructions into context. Available skills:" and lists IDs and descriptions from the registry. Its riskLevel returns RiskLevel.SAFE.
The tool takes a name argument. If that argument is missing, it returns "Error: missing 'name' argument". If the skill is unknown, it returns "Error: skill not found: $skillName". If the requested card has children, the result includes the card body plus "Available in this domain:" and sibling descriptions.
SkillTool implements sophi-core's Tool and holds a sophi-skills SkillRegistry. That combination could only compile in sophi-sdk, the only module with an edge to both sides. It could not live in sophi-skills, because the skills module was deliberately kept ignorant of what a Tool even is. It also could not stay parked in sophi-cli forever. ADR-028, dated August 25th, gave sophi-companion the same tool set as the terminal, so a class only sophi-cli could see could not serve a second host.
Registration is conditional. If skillRegistry.topLevel().isNotEmpty(), the harness registers SkillTool(skillRegistry, topK = harnessConfig?.topKSkills). A second front door, /skill <id>, skips the model decision entirely. It injects the card with session.append(EntryRole.TOOL_RESULT, skill.body) and outputs "Injected skill: $sub".
The shelf also grew organization. SkillRegistry now distinguishes a domain's root card through topLevel() from its members through childrenOf(domainId). Asking SkillTool for site-github-com today returns that card plus a list of sibling cards filed under it, turning one flat stack into a binder.
Self-written cards arrived with safety gates
Reading cards was the earlier milestone. Later, the box gained a way to fill itself. write_skill lets the agent record a new site-specific card after it works out how a website behaves, including names such as site-github-com or a domain member like site-maidplus-de/companies. install_skill pulls a Claude-Code-shaped SKILL.mdin from a local path or git URL and normalizes its frontmatter to match.
ADR-030, dated August 27th, is what made that writable state safe enough to leave running. Static content checks block a write before a single byte lands. They scan for secrets and credentials, and they scan for prompt-injection phrases in anything arriving from outside the codebase.
Both tools also use the door built in article-06: riskLevel returns RiskLevel.DESTRUCTIVE. A card that can change what a future turn believes about the world does not get to be SAFE just because the storage format started out inert. install_skill goes one step further. Its ruleVerdict returns HIGH_RISK unconditionally, so content arriving from a git URL always gets a human's eyes on it, with no exception a classifier gets to grant.
Writing a card and judging whether it helped are separate moments on separate clocks. No eval suite runs inside write_skill's own execute(). A written card lands as a trial version, not a promoted one. Reading it back to check whether it actually helped is a separate command, sophi skill verify, run on a separate day. That is deliberate. Running an eval suite inside the tool call would stall the turn for minutes while waiting on a judgment nobody asked for yet.
The verification-and-promotion machinery is its own later story: what the eval suite scores, why it runs twice, and how coverageWarning catches a suite that never actually exercised the new skill.
Who should use it / who should skip it
This pattern matters to engineers who want a skill system that can survive host changes. It paid off twice. Months later, a Tool and a slash command needed nothing from sophi-skills itself. Then, about a year after that, the consuming side moved buildings entirely, from sophi-cli to sophi-sdk, and was reused unmodified by a second host app that did not exist when the skeleton was shipped. sophi-skills's own code never noticed, because it was never depended on for anything more than Skill and SkillRegistry.
The instinct is the same as riskLevel's boring SAFE default from article-06: build the boring, general-purpose thing, leave room, and let whoever moves in next decide what goes in the room. Even when that whoever turns out to be a module and a host app that had not been designed yet.
sophi-extensions, the other half of the previous milestone, is a different kind of rough-in. It wires observers into the agent loop instead of storing instructions for it, and it remains a future story.
Engineers building agent harnesses should study this when they need Markdown-defined instructions, tool loading, and safe self-modifying skills. Readers who only want a finished prompt library may skip the architecture detail.
The next article covers building sub-agents, described in the series as Calling in a subcontractor: subagents as just another Tool. The author invites comments from people working on agent-based systems and the build-vs-buy divide in the JVM ecosystem. The original story was published in Towards AI on Medium, and the full source is available on GitHub with a LinkedIn connection.

Comments (0)