Skip to content

NetFabric/intelligentium / .agents/skills/copilot-sdk

copilot-sdk

Verified

Embed the GitHub Copilot agent runtime into your own application using the Copilot SDK. USE FOR: CopilotClient/createSession setup, streaming responses, custom tools, permission handlers, hooks (pre/post-tool-use, session-start), custom agents and sub-agent delegation, MCP servers, skill and plugin directories, session persistence, fleet mode, steering/queueing, calling the SDK from skill scripts/ to run one bounded non-deterministic AI step inside an otherwise deterministic script, and choosing an auth/deployment path (CLI setup, backend services, multi-tenancy, GitHub OAuth, BYOK). Covers Node.js/TypeScript (@github/copilot-sdk), Python (github-copilot-sdk), Go (github.com/github/copilot-sdk/go), Rust (github-copilot-sdk crate), .NET (GitHub.Copilot.SDK), and Java (copilot-sdk-java). DO NOT USE FOR: authoring SKILL.md files consumed by VS Code Copilot (use create-skill instead); using the Copilot IDE extension or chat UI directly; general LLM/chat API integration unrelated to the Copilot SDK.

references/advanced-features.md

View on GitHub
# Advanced Features

## Hooks

Hooks intercept session lifecycle points. Register via the `hooks` field on session config.

| Hook | Trigger | Typical use |
|---|---|---|
| `onPreToolUse` | Before a tool executes | Approve/deny/modify args, add context, suppress output |
| `onPostToolUse` | After a successful tool execution | Transform/redact results, logging |
| `onPostToolUseFailure` | After a tool execution that failed | Inject retry guidance, log failures |
| `onUserPromptSubmitted` | User sends a message | Modify or filter the prompt |
| `onUserPromptTransformed` | After runtime prompt transformation | Inspect/replace the model-facing content |
| `onSessionStart` | Session begins | Inject `additionalContext`, configure session |
| `onSessionEnd` | Session ends | Cleanup, analytics |
| `onErrorOccurred` | An error happens | Custom error handling |
| `onAgentStop` | Top-level agent naturally stops | Validate completion or request another turn |

`onPreToolUse` returns `{ permissionDecision: "allow" | "deny" | "ask", permissionDecisionReason?, modifiedArgs?, additionalContext?, suppressOutput? }` (or `null`/`undefined` to allow unchanged).

## Custom agents (sub-agent delegation)

Pass `customAgents` on session config; each needs `name` + `prompt`, plus optionally `displayName`, `description`, `tools` (scoped tool allowlist), and its own `mcpServers`. The runtime auto-delegates a user request to the best-matching agent, runs it in an isolated context, and streams `subagent.*` lifecycle events back to the parent session. For dispatching many sub-agents in parallel instead of one delegated match, see Fleet Mode below.

```typescript
customAgents: [{
    name: "researcher",
    tools: ["grep", "glob", "view"],
    prompt: "You are a research assistant. Analyze code and answer questions. Do not modify any files.",
}]
```

## MCP servers

Wire external tool providers via `mcpServers` on session config, keyed by name.

| Type | Transport | Fields |
|---|---|---|
| `local` (stdio) | Subprocess | `command`, `args`, `env`, `cwd`, `tools` (`["*"]`/`[]`/list), `timeout` |
| `http` | Remote HTTP/SSE | `url`, `headers`, `tools` |

```typescript
mcpServers: {
    "github": { type: "http", url: "https://api.githubcopilot.com/mcp/", headers: { Authorization: "Bearer ${TOKEN}" }, tools: ["*"] },
}
```

## Skill directories

`skillDirectories: ["./skills/code-review"]` loads every `SKILL.md`-containing folder into session context — same skill format this repo's `create-skill` skill teaches you to author, just consumed at runtime instead of by an IDE agent.

## Plugin directories

A plugin bundles skills + hooks + MCP servers + custom agents behind one manifest, loaded once instead of wired per-extension:

```text
my-plugin/
├── plugin.json          # manifest (or use a root SKILL.md alone)
├── hooks.json
├── .mcp.json
├── agents/<name>.md
└── skills/<name>/SKILL.md
```

Load with `--plugin-dir <path>` passed as an extra CLI arg via the language's `RuntimeConnection` (repeat the flag for multiple plugins). Use plugin directories once you have 3+ related extensions shipping together; for one-off additions just use `mcpServers`/`hooks`/`customAgents` directly. Manifest may also live at `.github/plugin.json`.

## Fleet mode

Experimental: dispatches multiple sub-agents **in parallel** for decomposable work (multi-file refactors, per-module reviews, independent research). Start via the session RPC namespace: `session.rpc.fleet.start({ prompt })`. Avoid for sequential/dependent steps or small tasks a single agent finishes quickly.

## Session persistence

Pass an explicit `sessionId` when creating a session to make it resumable later (`client.resumeSession(sessionId, ...)`); without one, the SDK assigns a random ID and the session can't be resumed. State (history, tool state, planning context) is persisted to disk automatically once a `sessionId` is set.

## Session limits

Set `sessionLimits: { maxAiCredits: N }` on create/resume to cap AI Credit spend for the session's current accounting window. Enforcement checks after each model call returns, so one response can still exceed the cap before the *next* call is blocked.

## Steering & queueing

`send(prompt, { mode: "immediate" })` steers the agent mid-turn (course-correct without aborting); `send(prompt, { mode: "enqueue" })` queues the message for after the current turn completes. Default `sendAndWait` has no mode option — it's for one-shot, non-overlapping prompts.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall