Skills and MCP

Two extension planes, one runtime

This distinction keeps the architecture clean. You do not need to fork the runtime to teach it a reusable workflow, and you do not need to rewrite the prompt system to connect a database, GitHub, or any other MCP-compatible surface. The runtime owns both extension planes, but it owns them differently.

1. Skills are reusable behavior modules

A skill is a Markdown file with YAML frontmatter. The frontmatter defines how the skill should be treated by the runtime, and the Markdown body becomes the injected instruction payload. In practice, a skill is a reusable task recipe that can carry triggers, allowed tools, execution context, dependency checks, shell hooks, and prompt scaffolding.

---
name: "summarise-pr"
description: "Summarise a pull request for the team."
when_to_use: "When the user asks for a PR summary or reviewer briefing."
allowed-tools:
  - bash
  - read
triggers:
  - summarise this pull request
  - review this pr
preamble-tier: standard
requires:
  - type: node
    check: "node --version"
    install-cmd: "cd ${SESHAT_SKILL_DIR}/scripts && npm install"
---

Read the diff, inspect changed files, and write a concise reviewer briefing.

• triggers enable natural-language auto-activation without a slash command.
• preamble-tier controls how much runtime context is injected ahead of the prompt body.
• requires generates a pre-flight dependency check section so the agent asks before installing anything missing.
• context lets the skill stay inline or fork into an isolated execution context.

2. Skill loading is layered and deterministic

The loader walks multiple sources and then deduplicates by skill name, so the first matching skill wins. That gives Seshat a stable override model: repo-owned behavior can beat user defaults, while bundled fallback skills stay at the bottom. It also means the same runtime can support personal skills, team skills, admin-managed skills, and cloned skill collections without inventing a second plugin system.

Another important detail is that cloned skill repositories are treated as collections. Each directory containing a SKILL.md becomes one namespaced skill, and ${SESHAT_SKILL_DIR} resolves to the collection root so the prompt can refer to repo-relative data or scripts.

3. The skill tool is itself a runtime surface

Seshat does not hardcode a fixed list of skill commands into the model prompt. The skill tool rebuilds its own definition dynamically from the currently visible skills, marks itself as deferred, and tells the model to invoke it whenever a matching slash command or task-specific skill exists.

4. MCP is how external capabilities become native runtime tools

The MCP side is much more transport- and protocol-oriented. The runtime reads config, connects to external servers, completes the MCP initialize handshake, discovers the remote surface, and then wraps it into Seshat's own tool registry.

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "docs": {
      "type": "sse",
      "url": "https://example.com/mcp"
    }
  }
}

The wrapper does more than import tools. It also wraps resources and prompts, and it always adds generic resource helpers such as mcp_list_resources and mcp_read_resource. By default, exposed MCP tool names are prefixed like mcp__github__search_issues, although aliases are also generated for easier lookup.

5. MCP configuration is layered too

MCP server definitions are loaded from runtime-root config as well as project-local config. In the current loader, enterprise config acts like an override path, while user and project-local definitions are merged when enterprise mode is not present. Environment variables inside config entries are expanded before connection.

client, err := sdk.NewClient(&sdk.ClientConfig{
    MCPServers: []sdk.MCPServerConfig{
        {
            Name:      "github",
            Transport: sdk.MCPTransportStdio,
            Command:   "npx",
            Args:      []string{"-y", "@modelcontextprotocol/server-github"},
        },
    },
})

6. Skills and MCP can reinforce each other

A strong pattern is to use a skill to define a repeatable workflow and an MCP server to provide the external systems that workflow needs. For example, a PR review skill can encode the review method while GitHub or Jira MCP servers provide the live project data.

• Skills encode reusable operating procedure.
• MCP servers expose external reality: repos, tickets, databases, browsers, internal tools.
• The prompt already instructs the runtime to prefer MCP tools over built-ins when both cover the same operation and the MCP tool is the better fit.

There is even an MCP-to-skill bridge in the codebase that can expose connected MCP tools as skill-like invocations, but the main architectural path is still direct tool wrapping into the runtime registry.

Why this matters for the larger vision

This is one of the places where Seshat starts to look less like a single assistant and more like an extensible agent runtime. Skills let communities and teams package operating knowledge. MCP lets domain systems plug in without waiting for the core runtime to reimplement them one by one. Together, they create the extension surface that a broader agent platform actually needs.

Next step

Once the extension surface is clear, the next practical layer is how people actually use it day to day in the CLI app: sessions, settings, MCP management, and runtime workflows.