Skill

The Skill system provides a mechanism for injecting reusable, specialized knowledge into agent context. Skills use trigger-based activation to determine when they should be included in the agent's prompt.

Source: faheemcode/sdk/context/skills/

Core responsibilities

The Skill system has five primary responsibilities:

1. Context Injection - Add specialized prompts to agent context based on triggers
2. Trigger Evaluation - Determine when skills should activate (always, keyword, task, path)
3. Dynamic Content Rendering - Execute inline shell commands for dynamic context injection
4. MCP Integration - Load MCP tools associated with repository skills
5. Third-Party Support - Parse .cursorrules, agents.md, and other skill formats

Architecture

Key components

Component	Purpose	Design
Skill	Core skill model	Pydantic model with name, content, trigger
KeywordTrigger	Keyword-based activation	String matching on user messages
TaskTrigger	Task-based activation	Special type of KeywordTrigger for skills with user inputs
PathTrigger	Path-based activation ("rules")	Glob match on a touched file path; injected into the tool result, not model-invocable
InputMetadata	Task input parameters	Defines user inputs for task skills
render_content_with_commands	Dynamic content	Executes inline !command`` patterns
Skill Loader	File parsing	Reads markdown with frontmatter, validates schema

Skill types

Repository skills

Always-active, repository-specific guidelines.

Recommended: put these permanent instructions in AGENTS.md (and optionally GEMINI.md / CLAUDE.md) at the repo root.

Characteristics:

• Trigger: None (always active)
• Purpose: Project conventions, coding standards, architecture rules
• MCP Tools: Can include MCP tool configuration
• Location: AGENTS.md (recommended) and/or .agents/skills/*.md (supported)

Example Files (permanent context):

• AGENTS.md - General agent instructions
• GEMINI.md - Gemini-specific instructions
• CLAUDE.md - Claude-specific instructions

Other supported formats:

• .cursorrules - Cursor IDE guidelines
• agents.md / agent.md - General agent instructions

Knowledge skills

Keyword-triggered skills for specialized domains:

Characteristics:

• Trigger: KeywordTrigger with regex patterns
• Purpose: Domain-specific knowledge (e.g., "kubernetes", "machine learning")
• Activation: Keywords detected in user messages
• Location: System or user-defined knowledge base

Trigger Example:

---
name: kubernetes
trigger:
  type: keyword
  keywords: ["kubernetes", "k8s", "kubectl"]
---

Task skills

Keyword-triggered skills with structured inputs for guided workflows:

Characteristics:

• Trigger: TaskTrigger (a special type of KeywordTrigger for skills with user inputs)
• Activation: Keywords/triggers detected in user messages (same matching logic as KeywordTrigger)
• Purpose: Guided workflows (e.g., bug fixing, feature implementation)
• Inputs: User-provided parameters (e.g., bug description, acceptance criteria)
• Location: System-defined or custom task templates

Trigger Example:

---
name: bug_fix
triggers: ["/bug_fix", "fix bug", "bug report"]
inputs:
  - name: bug_description
    description: "Describe the bug"
    required: true
---

Note: TaskTrigger uses the same keyword matching mechanism as KeywordTrigger. The distinction is semantic - TaskTrigger is used for skills that require structured user inputs, while KeywordTrigger is for knowledge-based skills.

Path skills (rules)

Skills that are injected deterministically when the agent touches a matching file, modeled on Claude Code "rules":

Characteristics:

• Trigger: PathTrigger with gitignore-style paths globs (matched against the workspace-relative POSIX path)
• Activation: The agent reads, edits, or creates a file whose path matches a glob (fires on create too)
• Injection point: Folded into the ObservationEvent tool result (extended_content) as an <EXTRA_INFO> block — not the user message
• Baseline cost: Zero — excluded from <available_skills> and <REPO_CONTEXT>; disable_model_invocation is forced, so rules are never model-invocable
• Dedup: Each rule is injected only once per conversation (tracked via ConversationState.activated_path_rules)
• Location: Any skills directory (e.g. .agents/skills/*.md) — a rule is just a skill with paths: frontmatter

Trigger Example:

---
paths:
  - "src/api/**/*.ts"
  - "**/*.route.ts"
---

Note: A skill is either path-triggered or model-invocable, not both — if a file declares both paths: and triggers:, paths: wins. Path-rule injection applies to local conversations; ACP-backed conversations do not inject rules because the ACP server owns tool execution.

Trigger evaluation

Skills are evaluated at different points in the agent lifecycle:

Evaluation Rules:

Trigger Type	Evaluation Point	Activation Condition
None	Every step	Always active
KeywordTrigger	On user message	Keyword/string match in message
TaskTrigger	On user message	Keyword/string match in message (same as KeywordTrigger)
PathTrigger	On tool observation	Glob match on the touched file's path (read/edit/create)

Note: Both KeywordTrigger and TaskTrigger use identical string matching logic. TaskTrigger is simply a semantic variant used for skills that include user input parameters.

MCP tool integration

Repository skills can include MCP tool configurations:

MCP Configuration Format:

Skills can embed MCP server configuration following the FastMCP format:

---
name: repo_skill
mcp_tools:
  mcpServers:
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
---

Workflow:

1. Load Skill: Parse markdown file with frontmatter
2. Extract MCP Config: Read mcp_tools field
3. Spawn MCP Servers: Create MCP clients for each server
4. Register Tools: Add MCP tools to agent's tool registry
5. Inject Context: Add skill content to agent prompt

Dynamic content rendering

Skills support inline command execution for injecting dynamic context at render time:

1. Parse content for !`cmd` patterns outside code blocks
2. Execute each command via subprocess
3. Replace pattern with stdout (or error marker)
4. Return rendered content

Syntax:

• !`command` - Executes command and replaces with stdout
• \!`command` - Escapes to literal !`command` text
• Fenced (```) and inline (`) code blocks are never executed

Safety:

• Unclosed fenced blocks (odd ``` count) extend to EOF, protecting trailing content
• Failed commands return [Error: ...] markers
• Output truncated at 50KB per command

See Dynamic Command Execution for usage details.

Skill file format

Skills are defined in markdown files with YAML frontmatter:

---
name: skill_name
trigger:
  type: keyword
  keywords: ["pattern1", "pattern2"]
---

# Skill Content

This is the instruction text that will be added to the agent's context.
Dynamic values: !`git branch --show-current`

Frontmatter Fields:

Field	Required	Description
name	Yes	Unique skill identifier
trigger	Yes*	Activation trigger (null for always active)
paths	No	Glob patterns that make the skill a path-triggered rule (PathTrigger); takes precedence over triggers
mcp_tools	No	MCP server configuration (repo skills only)
inputs	No	User input metadata (task skills only)

*Repository skills use trigger: null (or omit trigger field)

Component relationships

How skills integrate

Relationship Characteristics:

• Skills → Agent Context: Active skills contribute their content to system prompt
• Skills → MCP: Repository skills can spawn MCP servers and register tools
• Context → Agent: Combined skill content becomes part of agent's instructions
• Skills Lifecycle: Loaded at conversation start, evaluated each step

See also

• Agent Architecture - How agents use skills for context
• Tool System - MCP tool spawning and client management
• Context Management Guide - Using skills in applications