Why AI agents need a structured skill repository
As AI coding agents become more capable, the instructions and context they need to do their work are growing harder to manage. Developers building multi-agent workflows run into the same problem: skill definitions scattered across projects, duplicated across folders, and loaded in full even when only a fraction of the content is relevant. Skillgesture is a local MCP server that solves this by centralizing skills into a structured repository and loading them on demand only when an agent requests them.
The tool stores skills as Markdown files organized in a group, skill, subskill hierarchy. A catalog, associations, and session data live as JSON. Skills can be global, available to every agent, or scoped to specific directory paths. When an agent opens a session, it provides the folders it works in, and Skillgesture returns only the skills applicable to those paths. The agent reads individual skill content only when it needs it, keeping context windows focused on what matters.
How the storage model works
The repository lives at ~/.skillgesture by default, with an alternative path available through the SKILLGESTURE_HOME environment variable. The catalog.json file tracks all known groups, skills, and subskills along with their active versions. Associations.json maps directory paths to the skills that apply to them. Sessions are stored individually under a sessions directory, keyed by UUID.
Skill content lives in versioned directories under a skills folder. Each version contains a SKILL.md file and an optional resources directory for supporting files. Markdown versions are immutable. The catalog points to the active version, which means reads never observe partially updated content during a write. This atomic design matters because multiple MCP processes can use the same repository simultaneously, and mutations are serialized through a cross-process lock to prevent conflicts.
Sessions and folder associations
An agent creates a session by calling session.open with a label and one or more folders. The server returns a UUID that the agent must retain and reuse across restarts. If the agent provides an unknown session ID, Skillgesture does not create a new session implicitly. Sessions can be reconfigured with session.configure, which accepts modes for replace, add, or remove to adjust the set of folders a session watches.
Associations connect specific directory paths to specific skills. An association with /projects/api does not automatically apply to /projects/api/packages/web. Folders must exist when loaded or associated. A session containing multiple folders receives the deduplicated union of their associated skills. This path-精确 design means a Node.js project and a Python project in the same session each get only the skills relevant to their stack, without overlap or manual curation.
Reading skills on demand
The skill_tree action returns a lightweight index of applicable skills for a session. It includes metadata and provenance but not the Markdown content itself. This keeps the initial response small and lets the agent decide which skills to load based on what it is actually working on. The skill_read action then fetches the Markdown for a single skill or subskill. If the skill contains imported supporting files, the first read also returns a resource index. Passing one of those paths as resourcePath reads only that file without loading the entire bundle into the context.
This two-step design addresses a practical problem with long-context agents. Loading every relevant skill in full at session start wastes tokens on content the agent may never need. Skillgesture lets agents defer that cost until the moment of use, loading only the specific subskill or reference file that applies to the current task. Text resources are returned as UTF-8, binary resources as Base64.
Managing skills and handling conflicts
The server provides actions for creating and modifying groups, skills, and subskills through upsert operations. Groups contain skills, skills can contain subskills, and subskills inherit the scope of their parent. A group or skill can be disabled, which prevents its descendants from being readable and removes them from the default skill_tree output. The includeDisabled parameter lets an agent see the full tree including disabled nodes when needed.
Update operations accept an expectedVersion parameter, and association.set accepts expectedRevision. If another agent has already changed the data, Skillgesture returns a VERSION_CONFLICT error instead of silently overwriting the change. This optimistic concurrency model prevents one agent from stomping on another's edits in a shared repository, which is the kind of problem that shows up immediately once multiple agents run against the same skill set.
What this means for agent developers
Skillgesture fills a gap that becomes obvious once you start building workflows with multiple AI agents. The agents need shared context, but dumping everything into a single prompt wastes tokens and dilutes focus. A structured repository with path-based scoping and on-demand loading gives agents the right instructions at the right time without the overhead of loading everything upfront. The cross-process locking and conflict detection mean it works in environments where multiple agents run concurrently, which is increasingly the norm in automated coding workflows.
The tool requires Node.js 24 or later and npm 12 or later. Installation is a standard npm install followed by npm link to make the command globally available during development. Tests run against temporary directories and do not touch the user's real repository. The project is licensed under ISC.