Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

feat(skills): add write-agent factory skill for cross-tool agent authoring

Browse Source 
Adds write-agent to plugins/kyberforge/skills/ — a factory skill parallel
to write-skill that authors Claude Code subagent definitions and cross-tool
plugin agents (Claude Code + GitHub Copilot CLI two-file pattern).

Includes research references (claude-code-agents.md, copilot-cli-agents.md,
cross-compat.md), three asset templates (subagent, plugin-agent-claude,
plugin-agent-copilot), eval coverage, and CATEGORIES.md updated to register
write-agent in the factory category per the conflict check finding.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Defame1297
2026-06-21 12:01:34 +00:00
parent 88f3d97d0c
commit f60b4199ce
11 changed files with 544 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
plugins/kyberforge/skills/write-agent/references/claude-code-agents.md Normal file
View File

@@ -0,0 +1,91 @@
---
topic: claude-code-agents
source_keys:
- claude-code-docs-subagents
- claude-code-docs-plugins
---
## Overview
Claude Code agents (called subagents) are Markdown files with YAML frontmatter stored in one of several scoped locations. Each runs in its own context window with a custom system prompt, specific tool access, and independent permissions. The parent conversation delegates to a subagent when its `description` matches the task.
## File format
```markdown
---
name: code-reviewer
description: Reviews code for correctness, security, and maintainability. Use proactively after code changes.
tools: Read, Grep, Glob
model: sonnet
---
You are a senior code reviewer. Review for:
1. Correctness: logic errors, edge cases
2. Security: injection, auth bypass
3. Maintainability: naming, complexity
```
The body becomes the subagent's system prompt. Subagents receive only this system prompt plus basic environment details (working directory) — not the full Claude Code system prompt and not the parent conversation history.
## Supported frontmatter fields
Only `name` and `description` are required. All others are optional.
| Field | Description |
|---|---|
| `name` | Unique identifier: lowercase letters and hyphens. Used as `agent_type` in hooks. Filename does not have to match. |
| `description` | When Claude should delegate to this subagent — determines automatic routing. Write imperatively. |
| `tools` | Allowlist of tools the subagent can use. Inherits all tools if omitted. Comma-separated or array. Use `Agent(type1, type2)` syntax to restrict which subagents this agent can spawn. |
| `disallowedTools` | Denylist — removed from inherited or specified list. If both `tools` and `disallowedTools` are set, denylist is applied first. Supports `mcp__<server>` patterns. |
| `model` | Model alias (`sonnet`, `opus`, `haiku`, `fable`) or full ID (`claude-opus-4-8`). Defaults to `inherit` (parent model). |
| `permissionMode` | `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`. Inherited from parent; parent's mode takes precedence if stricter. **Ignored for plugin agents.** |
| `maxTurns` | Maximum agentic turns before the subagent stops. |
| `skills` | Skills to preload into the subagent's context at startup (full skill content injected, not just description). |
| `mcpServers` | MCP servers scoped to this subagent. Inline definitions connect on start, disconnect on finish. String references reuse the parent session's connection. **Ignored for plugin agents.** |
| `hooks` | Lifecycle hooks scoped to this subagent. **Ignored for plugin agents.** |
| `memory` | Persistent memory scope: `user`, `project`, or `local`. Enables cross-session learning. |
| `background` | `true` to always run as a background task. Default: `false`. |
| `effort` | Reasoning effort: `low`, `medium`, `high`, `xhigh`, `max`. Overrides session effort level. |
| `isolation` | `worktree` — runs in a temporary git worktree (isolated repo copy). Auto-cleaned up if no changes. |
| `color` | Display color in the task list: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. |
| `initialPrompt` | Auto-submitted as the first user turn when this agent runs as the main session agent (via `--agent`). |
## Storage locations and scope priority
| Location | Scope | Priority |
|---|---|---|
| Managed settings `.claude/agents/` | Organization-wide | 1 (highest) |
| `--agents` CLI flag | Current session only | 2 |
| `.claude/agents/` | Current project | 3 |
| `~/.claude/agents/` | All projects (user-level) | 4 |
| Plugin `agents/` directory | Where plugin is enabled | 5 (lowest) |
When the same `name` is defined in multiple locations, the highest-priority location wins. Claude Code scans both `.claude/agents/` and `~/.claude/agents/` recursively — files can be organized into subfolders. Identity comes from the `name` frontmatter, not the filename.
## Plugin agent constraints
Plugin agents (in a plugin's `agents/` directory) have three fields ignored for security reasons:
- `hooks` — ignored
- `mcpServers` — ignored
- `permissionMode` — ignored
If any of these are needed, copy the agent file to `.claude/agents/` or `~/.claude/agents/` instead.
Plugin agents in subfolders get a scoped identifier: `plugin-name:subfolder:agent-name` (e.g., a file at `agents/review/security.md` in plugin `my-plugin` registers as `my-plugin:review:security`).
## Repo-specific placement (this repo)
Per ADR-0010, two categories of agent definitions exist in this repo:
- **Subagent definitions** (isolated context, separate context window): live in `core/agents/` — deployed to `~/.claude/agents/` by `install.sh`. These are the "true" subagents.
- **Plugin agents**: live in `plugins/<name>/agents/<name>.md`. Installed with the plugin.
- **Role skills** (inline mode switches, NOT agents): live in `.agents/skills/` with `category: roles`.
Never put role skills in `core/agents/`. Never put subagent definitions in `.agents/skills/`. The distinction is the isolation boundary — subagents get a fresh context window; role skills load inline.
## Model routing guidance (from factory §9)
- `haiku` — formatting, classification, fast lookups
- `sonnet` — most coding, review, analysis
- `opus` — adversarial reasoning, complex multi-step, security-critical
- Omit `model` to inherit from the parent session

86
plugins/kyberforge/skills/write-agent/references/copilot-cli-agents.md Normal file
View File

@@ -0,0 +1,86 @@
---
topic: copilot-cli-agents
source_keys:
- github-copilot-custom-agents-config
- github-blog-copilot-cli-agents
---
## Overview
GitHub Copilot CLI agents are defined as Markdown files with `.agent.md` extension and YAML frontmatter. They live in the `.github/agents/` directory of a repository and are version-controlled with the codebase. Users invoke them via the `/agent` slash command in the CLI.
## File format
```markdown
---
name: Accessibility Expert
description: Expert assistant for web accessibility (WCAG 2.1/2.2)
model: GPT-4.1
tools:
- codebase
- edit/editFiles
- search
---
# Accessibility Expert
You are a web accessibility expert. Focus on WCAG 2.1/2.2 compliance...
```
The body (below frontmatter) contains the agent's instructions in Markdown. Maximum 30,000 characters.
## Supported frontmatter fields
| Field | Type | Required | Description |
|---|---|---|---|
| `name` | String | Recommended | Display identifier for the agent |
| `description` | String | Required | Purpose and capabilities — what this agent does |
| `target` | String | No | `vscode`, `github-copilot`, or omit for both |
| `model` | String | No | Model to use (e.g., `GPT-4.1`, `claude-opus-4-8`). Inherits default if unset. |
| `tools` | List | No | Tools the agent can use. Defaults to all tools if omitted. |
| `disable-model-invocation` | Boolean | No | When `true`, requires manual agent selection. |
| `user-invocable` | Boolean | No | Whether user can manually select this agent. Defaults to `true`. |
| `mcp-servers` | Object | No | Additional MCP server configurations. Not used in VS Code/IDE agents. |
| `metadata` | Object | No | Key-value annotation pairs. Not applicable to IDE agents. |
## Tools field
Tools can be configured three ways:
- **All tools** (default): omit the `tools` property, or use `tools: ["*"]`
- **Specific tools**: list names, e.g. `tools: ["codebase", "edit/editFiles", "search"]`
- **No tools**: `tools: []`
Available tool aliases (case-insensitive): `execute`, `read`, `edit`, `search`, `agent`, `web`, `todo`.
MCP server tools use namespacing: `mcp-server-name/tool-name` or `mcp-server-name/*` for all tools from a server.
Some available tools: `gh`, `git`, `codebase`, `search`, `githubRepo`, `runCommands`, `runTests`, `edit/editFiles`, `terraform`, `conftest`, `jq`, `curl`, `semgrep`, `trivy`, `gitleaks`.
## File location
Copilot CLI agents live in `.github/agents/` in the repository root. The filename uses the `.agent.md` extension (e.g., `accessibility.agent.md`).
## Plugin placement (this repo)
Per the cross-compat reference, plugin agents for Copilot CLI use the `.agent.md` naming:
- Claude Code reads: `agents/<name>.md`
- Copilot CLI reads: `agents/<name>.agent.md`
Both files share the same system prompt body. Only the frontmatter differs: Copilot uses `tools:` as an array with different tool names; Claude Code uses `tools:` as comma-separated internal tool names.
## Fields not supported in Copilot CLI
These Claude Code agent fields have no Copilot CLI equivalent:
- `permissionMode`
- `maxTurns`
- `skills` (Claude-specific skill injection)
- `mcpServers` (inline per-agent MCP — not supported in VS Code/IDE)
- `hooks`
- `memory`
- `background`
- `effort`
- `isolation`
- `color`
- `initialPrompt`
- `disallowedTools`

73
plugins/kyberforge/skills/write-agent/references/cross-compat.md Normal file
View File

@@ -0,0 +1,73 @@
---
topic: cross-tool-agent-compatibility
source_keys:
- claude-code-docs-plugins
- github-copilot-custom-agents-config
- plugin-marketplace-architecture
---
## The core rule
Skills are the portable primitive — identical format in both tools. Agents diverge. The system prompt body can be shared; the frontmatter and filename cannot.
## Divergence table
| Concern | Claude Code | GitHub Copilot CLI | Portable choice |
|---|---|---|---|
| File extension | `agents/<name>.md` | `agents/<name>.agent.md` | Ship both files — same body, tool-specific frontmatter |
| Required fields | `name`, `description` | `description` | Use both `name` and `description` in both files |
| `tools` format | Comma-separated string or array; internal tool names (e.g. `Read`, `Grep`, `Bash`) | Array; Copilot tool aliases (e.g. `codebase`, `search`, `edit/editFiles`) | Different values — maintain separately |
| `model` values | `sonnet`, `opus`, `haiku`, `fable`, or full model ID | Copilot model names (e.g. `GPT-4.1`, `claude-opus-4-8`) | Maintain separately |
| `permissionMode` | Supported | Not supported | Claude-only field |
| `maxTurns` | Supported | Not supported | Claude-only field |
| `skills` | Preloads skills into context | Not supported | Claude-only field |
| `mcpServers` | Inline or reference; ignored in plugin agents | `mcp-servers` (different key); not used in IDE agents | Maintain separately if needed |
| `hooks` | Supported (ignored in plugin agents) | Not supported | Claude-only field |
| `memory` | `user`, `project`, `local` | Not supported | Claude-only field |
| `background` | `true`/`false` | Not supported | Claude-only field |
| `effort` | `low`/`medium`/`high`/`xhigh`/`max` | Not supported | Claude-only field |
| `isolation` | `worktree` | Not supported | Claude-only field |
| `color` | `red`/`blue`/etc. | Not supported | Claude-only field |
| `target` | Not supported | `vscode` or `github-copilot` | Copilot-only field |
| `disable-model-invocation` | Not supported | Boolean | Copilot-only field |
| `user-invocable` | Not supported | Boolean (default `true`) | Copilot-only field |
| `metadata` | Not supported | Key-value object | Copilot-only field |
## The two-file pattern
For every cross-tool agent in a plugin, ship two files with the same body:
```text
plugins/<plugin-name>/agents/
├── <name>.md ← Claude Code (frontmatter: name, description, tools, model, ...)
└── <name>.agent.md ← Copilot CLI (frontmatter: name, description, tools as array, ...)
```
The system prompt body (everything below the frontmatter `---`) is identical in both. Copy-fill both from the same system prompt source. Update both when the system prompt changes.
If the agent is Claude Code-only (not intended for Copilot), ship only `<name>.md` and note it explicitly.
## Plugin-specific constraints (Claude Code)
Plugin agents in Claude Code cannot use: `hooks`, `mcpServers`, `permissionMode`. These fields are silently ignored. If the agent needs them, it must be a user-level or project-level agent (`.claude/agents/`), not a plugin agent.
## Subagent vs role skill (this repo)
A common mistake: confusing role skills with subagents.
| Type | What it is | Where it goes | When to use |
|---|---|---|---|
| Role skill | Inline mode switch; loads into current conversation | `.agents/skills/` with `category: roles` | When you want Claude to adopt a cognitive mode (Architect, Reviewer) without context isolation |
| Subagent | Fresh context window, own system prompt, isolated | `core/agents/` → deployed to `~/.claude/agents/` | When a task would flood the main context (research, parallel work, long exploration) |
| Plugin agent | Installed with plugin; same isolation as subagent | `plugins/<name>/agents/<name>.md` + `.agent.md` | When the agent is part of a distributable plugin |
Write-agent creates subagents and plugin agents. Write-skill creates role skills. Do not mix the two.
## Recommended authoring stance
Claude Code is the stricter format (more fields, security restrictions for plugins). Treat it as the source of truth. For each agent:
1. Write the Claude Code `.md` file first with all relevant frontmatter.
2. Copy the system prompt body to the Copilot `.agent.md` file.
3. Translate frontmatter: keep `name`, `description`; translate `tools` to Copilot aliases; drop Claude-only fields; add Copilot-only fields if needed.
4. Note any fields that couldn't be ported (e.g., `permissionMode`, `isolation`) as Claude-only behaviors.

36
plugins/kyberforge/skills/write-agent/references/sources.md Normal file
View File

@@ -0,0 +1,36 @@
# Sources
## claude-code-docs-subagents
- **URL:** https://code.claude.com/docs/en/sub-agents
- **Description:** Official Claude Code documentation on creating and configuring custom subagents — all frontmatter fields, scope priority, tool restrictions, permission modes.
- **Contributing files:** claude-code-agents.md, cross-compat.md
- **Status:** `extracted`
## claude-code-docs-plugins
- **URL:** https://code.claude.com/docs/en/plugins-reference
- **Description:** Official Claude Code plugin reference — agent fields available in plugin context and security restrictions (hooks, mcpServers, permissionMode ignored).
- **Contributing files:** claude-code-agents.md, cross-compat.md
- **Status:** `extracted`
## github-copilot-custom-agents-config
- **URL:** https://docs.github.com/en/copilot/reference/custom-agents-configuration
- **Description:** GitHub Copilot custom agents configuration reference — all frontmatter fields, tools field format, target field, mcp-servers.
- **Contributing files:** copilot-cli-agents.md, cross-compat.md
- **Status:** `extracted`
## github-blog-copilot-cli-agents
- **URL:** https://github.blog/ai-and-ml/github-copilot/from-one-off-prompts-to-workflows-how-to-use-custom-agents-in-github-copilot-cli/
- **Description:** GitHub blog post on Copilot CLI custom agents — .agent.md format, tool names, invocation pattern.
- **Contributing files:** copilot-cli-agents.md
- **Status:** `extracted`
## plugin-marketplace-architecture
- **URL:** /root/ai-development/plugins/kyberforge/docs/plugin-marketplace-architecture.md
- **Description:** Repo-internal reference on Claude Code vs Copilot CLI divergence, two-file agent pattern, plugin constraints.
- **Contributing files:** cross-compat.md
- **Status:** `extracted`