Extensibility

The framework is designed to be extended. Six mechanisms are available, each with different activation models, context costs, and complexity.

Tip

Not sure which extension mechanism to use? Run @devsquad.extend in Copilot Chat for interactive guidance that walks you through the decision.

Extension Mechanisms

Mechanism	Activation	Context Cost	Size
Instructions	Deterministic (file glob)	Always loaded in scope	< 50 lines
Skills	Semantic (description)	On demand	50-200 lines
Agents	Explicit (invocation)	Isolated	> 200 lines
Hooks	Automatic (lifecycle)	Zero (external)	Any
MCP Servers	Per tool call	On demand	Any
Tool Extensions	Per sync	Same as base agent	YAML patch

Decision Tree

flowchart TD
  start["I need to add specific<br/>knowledge to the framework"]

  start --> q1{"Does the knowledge apply<br/>whenever a specific file<br/>type is edited?"}
  q1 -->|Yes| instruction["Instruction<br/>(applyTo: file glob)"]
  q1 -->|No| q2{"Is the knowledge<br/>reusable by<br/>multiple agents?"}

  q2 -->|Yes| q3{"Is it over 200 lines<br/>or needs its own tools?"}
  q3 -->|Yes| agent["Agent<br/>(specialized sub-agent)"]
  q3 -->|No| skill["Skill<br/>(loaded by relevance)"]

  q2 -->|No| q4{"Is it a deterministic<br/>post-action<br/>validation?"}
  q4 -->|Yes| hook["Hook<br/>(lifecycle script)"]
  q4 -->|No| q5{"Does it need access<br/>to an external system<br/>via API?"}
  q5 -->|Yes| q6{"Should existing plugin agents<br/>use these tools?"}
  q6 -->|Yes| toolext["Tool Extension<br/>(overlay generation)"]
  q6 -->|No| mcp["MCP Server<br/>(standalone config)"]
  q5 -->|No| agent2["Agent or Skill<br/>(depends on volume)"]

Creating Extensions

Instructions

Path-scoped rules applied when editing matching files.

• Use applyTo glob in frontmatter
• Keep under 50 lines
• Concise, actionable rules (not documentation)
• One per artifact type

Example:

.github/instructions/python.instructions.md

---
applyTo: "**/*.py"
---
# Python - Project Conventions

- Type hints required on every public signature
- Domain errors inherit from `AppError` (src/core/errors.py)
- Async by default for I/O (httpx, asyncpg)
- Tests with pytest; shared fixtures in conftest.py
- Imports organized: stdlib, third-party, local

Skills

Reusable knowledge packages loaded on demand.

• Directory name = frontmatter name (kebab-case)
• Description optimized for semantic trigger (include keywords, use/don’t-use scenarios)
• Maximum 500 lines

Example:

.github/skills/resilience-patterns/SKILL.md

---
name: resilience-patterns
description: Retry, circuit breaker, and fallback patterns.
  Use when implementing external service calls, HTTP
  clients, or database connections. Do not use for
  in-memory operations.
---
# Resilience Patterns

## Retry
- Exponential backoff with jitter
- Maximum 3 retries for transient failures

## Circuit Breaker
- Failure threshold: 5 consecutive failures
- Half-open after 30 seconds

Agents

Specialized workflows with isolated context.

• Naming: devsquad.<phase>.agent.md
• Required frontmatter: description, tools
• Modalities: Direct (user selects), Sub-agent (programmatic), Both
• Nested sub-agent invocation supported up to 5 levels in VS Code 1.113+
• Internal workers should set user-invocable: false and keep tool sets minimal

Example frontmatter:

---
description: Python implementation specialist. Invoked by
  devsquad.implement for task execution in Python projects.
tools:
  - edit/editFiles
  - edit/createFile
  - execute/runInTerminal
  - search/codebase
---

Hooks

External scripts triggered by lifecycle events.

• Bash scripts with shebang
• JSON output on single line
• 30-second default timeout
• Register in hooks.json
• Events: sessionStart, preToolUse, postToolUse, sessionEnd

Example:

#!/bin/bash
# validate-python-imports.sh (postToolUse)

FILE="$1"
if [[ "$FILE" != *.py ]]; then
  echo '{"status":"skipped"}'
  exit 0
fi
RESULT=$(ruff check "$FILE" --select I 2>&1)
if [ $? -eq 0 ]; then
  echo '{"status":"pass"}'
else
  echo '{"status":"fail","details":"import issues"}'
fi

Tool Extensions

Inject any MCP server tools into existing plugin agents via YAML patches. (Preview, ADR 0010)

• Consumer creates .github/devsquad/tool-extensions/*.yml
• Sync script generates workspace-level agent overrides in .github/agents/
• sessionStart hook detects when extensions are stale or unsynced

Example:

.github/devsquad/tool-extensions/jira.yml

name: jira
description: Jira integration for work items
mcp:
  server: "@atlassian/jira-mcp"
  transport: stdio
agents:
  - devsquad.kickoff
  - devsquad.decompose

Extension File Locations

• Directory.github/

  • Directoryinstructions/ (deterministic, by file glob)

    • …
  • Directoryskills/ (semantic, on demand)

    • Directoryresilience-patterns/

      • SKILL.md
  • Directoryagents/ (explicit invocation)

    • devsquad.implement-python.agent.md
  • Directoryplugins/devsquad/

    • Directoryhooks/ (lifecycle scripts)

      • hooks.json
  • Directorydevsquad/

    • Directorytool-extensions/ (MCP tool injection)

      • …

Tip

Use @devsquad.extend to get interactive guidance for creating any extension type.

Next Steps

Extension Recipes Step-by-step examples for creating instructions, skills, agents, and hooks.

Skills Reference All 18 built-in skills with activation model.

Core Components Built-in instructions, hooks, MCP servers, and context management.

---

What to Read Next

• Extension Recipes for step-by-step examples
• Contributing for contribution guidelines

Coming from a Different Angle?

For Developers Install the plugin and run your first guided workflow.

For Architects Design principles, decision records, and technical design structure.

For Leadership How guardrails keep delivery predictable and traceable.