docs(kyberforge): add skill-vs-agent decision criteria for Claude Code and Copilot
Fills a gap needed for the planned forge orchestrator skill: neither doc set previously stated when to build a skill vs a subagent/custom agent. Sourced via context7 against the same libraries already recorded in each sources.md. Also confirms agentskills.io's spec is runtime-agnostic and defines no agent concept, so it has no bearing on this decision by design.
This commit is contained in:
@@ -4,6 +4,7 @@ source_keys:
|
||||
- agentskills-home
|
||||
- agentskills-spec
|
||||
- agentskills-quickstart
|
||||
- agentskills-best-practices
|
||||
---
|
||||
|
||||
## What Agent Skills is
|
||||
@@ -30,6 +31,10 @@ Agents load skills in three stages:
|
||||
|
||||
Full instructions load only when a task calls for them, so agents can keep many skills on hand with only a small context footprint.
|
||||
|
||||
## Scope: no concept of "agent"
|
||||
|
||||
The spec is runtime-agnostic and defines only the skill format — it does not define "agent," "subagent," or any delegation/orchestration concept, and neither the specification nor the best-practices guide contains criteria for choosing a skill over a separate agent process. Skill-vs-agent selection is a decision made by whichever runtime consumes the skill (see the Claude Code and GitHub Copilot decision-criteria docs for their respective answers), not something the Agent Skills format itself addresses.
|
||||
|
||||
## Canonical directory
|
||||
|
||||
The canonical location for skills is `.agents/skills/` at the project root. Tool-specific locations (`.claude/skills/` for Claude Code, `~/.codex/skills/` for Codex) are thin adapters that map to this canonical path. Putting skills at `.agents/skills/` maximizes cross-tool portability.
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
topic: decision-criteria
|
||||
source_keys:
|
||||
- context7-websites-code-claude
|
||||
---
|
||||
|
||||
## Skill vs Subagent
|
||||
|
||||
Official comparison (`Compare similar features > Skill vs Subagent`): skills add to the main context window and are best for reference material or invocable workflows; subagents use a separate context window with their own input/output tokens, making them ideal for tasks that read many files, run in parallel, or need a specialized worker — especially when the main context window is getting full.
|
||||
|
||||
Restated: skills are reusable content (instructions, knowledge, workflows) loaded into any context, benefiting from content sharing across the conversation. Subagents are isolated workers with their own context, designed for context isolation — work happens separately and only a summary returns to the main conversation.
|
||||
|
||||
## Combining skills and subagents
|
||||
|
||||
The two are not mutually exclusive — Claude Code documents two explicit combination mechanisms, inverses of each other:
|
||||
|
||||
- **`skills:` field on a subagent** — preloads specific skill content into that subagent's own system prompt. The subagent controls the prompt; skill content is injected into it at startup.
|
||||
- **`context: fork` field on a skill** — runs the skill's own body in an isolated agent context instead of the calling conversation. The `agent` field selects which subagent type executes it (built-in `Explore`, `Plan`, `general-purpose`, or a custom subagent); defaults to `general-purpose` if omitted. The skill's content becomes the task prompt injected into that agent.
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: deep-research
|
||||
description: Research a topic thoroughly
|
||||
context: fork
|
||||
agent: Explore
|
||||
---
|
||||
Research $ARGUMENTS thoroughly:
|
||||
1. Find relevant files using Glob and Grep
|
||||
2. Read and analyze the code
|
||||
3. Summarize findings with specific file references
|
||||
```
|
||||
|
||||
This means a single skill file can declare that it should always execute in isolation, without needing a separate agent definition file — useful when the isolation need is inherent to the task (e.g., broad file search) rather than something the caller decides per-invocation.
|
||||
@@ -3,8 +3,8 @@
|
||||
## context7-websites-code-claude
|
||||
|
||||
- **URL:** context7:/websites/code_claude
|
||||
- **Description:** Official Claude Code documentation site indexed by Context7 — plugin manifest schema, subagent definition types, marketplace JSON format, agent markdown file format, plugin update lifecycle, interactive plugin manager UI, private marketplace authentication, `commands` vs `skills/` distinction
|
||||
- **Contributing files:** overview.md, agent-definition.md, configuration.md, examples.md, api-reference.md, marketplace.md, installation.md
|
||||
- **Description:** Official Claude Code documentation site indexed by Context7 — plugin manifest schema, subagent definition types, marketplace JSON format, agent markdown file format, plugin update lifecycle, interactive plugin manager UI, private marketplace authentication, `commands` vs `skills/` distinction, skill-vs-subagent decision guidance and combination mechanisms (`skills:` field, `context: fork`)
|
||||
- **Contributing files:** overview.md, agent-definition.md, configuration.md, examples.md, api-reference.md, marketplace.md, installation.md, decision-criteria.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## claude-code-plugins-docs
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
topic: decision-criteria
|
||||
source_keys:
|
||||
- context7-github-en-copilot
|
||||
---
|
||||
|
||||
## Skill vs custom agent vs subagent
|
||||
|
||||
GitHub's own framing: "Skills enable Copilot to perform specialized tasks, while custom agents enhance Copilot with assistance tailored to your specific needs."
|
||||
|
||||
The CLI features comparison doc is more concrete about when *not* to use each:
|
||||
|
||||
- **Avoid a custom agent** if you only need guidance text — a skill is the lighter-weight solution — or if the default agent already performs the task well and no specialization is needed.
|
||||
- **Avoid a skill** when the guidance should apply universally (use custom instructions instead), or when the task needs new capabilities rather than more guidance — that calls for an MCP server or a custom agent.
|
||||
|
||||
The customization cheat sheet draws a three-way distinction:
|
||||
|
||||
| Primitive | Best fit | Trigger |
|
||||
|---|---|---|
|
||||
| Custom agent | Projects/processes with distinct stages needing specialized capabilities or strict handoffs | Manual — selected from a dropdown |
|
||||
| Subagent | Complex subtasks that must run isolated from the main agent | Automatic or by direct prompt reference |
|
||||
| Agent skill | Multi-step workflows with bundled assets (scripts, references, templates) | Automatic — Copilot matches it to the prompt when relevant (e.g. debugging GitHub Actions failures) |
|
||||
|
||||
Custom agents and subagents both isolate context and restrict tools, but differ in invocation: custom agents are a deliberate, user-selected mode switch; subagents are spawned automatically mid-task to offload work without cluttering the main agent's context (confirmed by the SDK example pattern of excluding a `heavyContextTool` from the default agent and giving it only to a dedicated `researcher` custom agent, "so the default agent remains clean").
|
||||
|
||||
Skills vs. custom instructions (a related but separate boundary): use custom instructions for general information like coding standards; use skills for detailed instructions Copilot should only access when relevant to the specific task.
|
||||
@@ -3,8 +3,8 @@
|
||||
## context7-github-en-copilot
|
||||
|
||||
- **URL:** context7:/websites/github_en_copilot
|
||||
- **Description:** Official GitHub Copilot documentation indexed by Context7; covers CLI plugins, custom agents, SDK, and marketplace
|
||||
- **Contributing files:** overview.md, agent-definition.md, configuration.md, installation.md, marketplace.md, api-reference.md, examples.md, sdk.md
|
||||
- **Description:** Official GitHub Copilot documentation indexed by Context7; covers CLI plugins, custom agents, SDK, marketplace, and skill-vs-agent-vs-subagent decision guidance
|
||||
- **Contributing files:** overview.md, agent-definition.md, configuration.md, installation.md, marketplace.md, api-reference.md, examples.md, sdk.md, decision-criteria.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## github-custom-agents-configuration
|
||||
|
||||
Reference in New Issue
Block a user