Skills

What are Skills

Skills are the curated counterpart to organic insights. Where insights are deposited automatically by agents during their work, skills are deliberately written instruction sets that encode team knowledge, standard operating procedures, or hard-won fixes. Each skill has a name, a set of instructions, and a set of triggers that determine when it should be served.

Think of skills as the “best of” layer on top of your knowledge base — distilled, reviewed, and ready to be applied by any agent on your team.

How Skills Work

When an agent calls query_insights, Surchin checks the query's tags, file context, and error signatures against every published skill's triggers. Matching skills are included in the response alongside regular insights, in a dedicated Applicable Skills section.

Matching uses a combined score: 60% semantic similarity (the skill's embedding vs. the query embedding) and 40% trigger overlap (tags, file patterns, error patterns). Skills below the minimum similarity threshold or minimum rank score are filtered out.

Creating Skills

There are two paths to create a skill:

Dashboard

Navigate to /skills/create in the dashboard. Fill in the name, description, instructions, and trigger configuration. Skills can be saved as drafts or published immediately.

MCP Tool

Use the create_skill tool to upload skills programmatically. This is idempotent by name — uploading a skill with the same name returns the existing one.

// MCP tool call
create_skill({
  name: "Fix Prisma connection pool exhaustion",
  description: "When encountering PrismaClientKnownRequestError with connection pool timeout errors",
  instructions: "## Diagnosis\n1. Check connection pool size...\n\n## Fix\n...",
  trigger_tags: ["prisma", "database", "connection-pool"],
  trigger_files: ["prisma/schema.prisma", "src/db/**"],
  trigger_errors: ["PrismaClientKnownRequestError"],
  status: "published"
})

Required fields: name, description, instructions. Triggers and status are optional (status defaults to published).

Skill Suggestions

Surchin auto-generates skill suggestions from high-performing insights. There are three trigger paths:

• Engagement threshold — an individual insight reaches 5+ positive signals across 3+ distinct sessions and has been promoted
• Pattern clustering — insights that co-occur in query results 3+ times are clustered and synthesized into a single skill draft
• Manual — select insights from the dashboard and click “Create skill” to generate a draft

Suggestions appear on the dashboard under the Suggestions tab in the Skills page. Each suggestion shows a confidence score, source signal summary, and the draft content. You can accept (which opens the skill editor pre-filled), edit, or dismiss each suggestion.

Organizations can opt into auto-promotion via org settings. When enabled, suggestions above a configurable confidence threshold (default 0.85) are automatically published as skills without manual review.

Retrieving Skills

Skills are delivered to agents in two ways:

• Automatically — via query_insights, when the query context matches skill triggers
• On demand — via the get_skill tool, by ID or name

// Retrieve by name
get_skill({ skill_name: "Fix Prisma connection pool exhaustion" })

// Retrieve by ID (from query_insights results)
get_skill({ skill_id: "550e8400-e29b-41d4-a716-446655440000" })

Managing Skills

The dashboard at /skills provides a full management interface with three tabs:

• Published — active skills being served to agents, with usage stats (times served, effectiveness rate)
• Drafts — skills in progress that are not yet being served
• Suggestions — auto-generated skill candidates awaiting review

Each skill has a detail page at /skills/[id] where you can edit the name, instructions, triggers, and status. Skills can be archived when they are no longer needed.

Usage stats track three counters per skill: times_served (delivered to an agent), times_followed (agent applied the skill), and times_dismissed (agent ignored it). Effectiveness is calculated as times_followed / (times_followed + times_dismissed).

Group Scoping

On Team tier and above, skills can be scoped to specific groups. A group-scoped skill is only served to agents querying within that group. The dashboard provides a group filter to view skills by group. Skills without a group are organization-wide.