diff --git a/plugins/kyberforge/docs/research/docs/agentskillsio/overview.md b/plugins/kyberforge/docs/research/docs/agentskillsio/overview.md index 69a4c61..87411b5 100644 --- a/plugins/kyberforge/docs/research/docs/agentskillsio/overview.md +++ b/plugins/kyberforge/docs/research/docs/agentskillsio/overview.md @@ -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. diff --git a/plugins/kyberforge/docs/research/docs/claude-code-plugins/decision-criteria.md b/plugins/kyberforge/docs/research/docs/claude-code-plugins/decision-criteria.md new file mode 100644 index 0000000..9d56cd9 --- /dev/null +++ b/plugins/kyberforge/docs/research/docs/claude-code-plugins/decision-criteria.md @@ -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. diff --git a/plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md b/plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md index 2329363..ca1ead7 100644 --- a/plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md +++ b/plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md @@ -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 diff --git a/plugins/kyberforge/docs/research/docs/github-copilot-plugins/decision-criteria.md b/plugins/kyberforge/docs/research/docs/github-copilot-plugins/decision-criteria.md new file mode 100644 index 0000000..89fc9f0 --- /dev/null +++ b/plugins/kyberforge/docs/research/docs/github-copilot-plugins/decision-criteria.md @@ -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. diff --git a/plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md b/plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md index 1d3f5be..6425fff 100644 --- a/plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md +++ b/plugins/kyberforge/docs/research/docs/github-copilot-plugins/sources.md @@ -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