diff --git a/plugins/kyberforge/skills/agent-audit/SKILL.md b/plugins/kyberforge/skills/agent-audit/SKILL.md index b0a58cd..dbac5b7 100644 --- a/plugins/kyberforge/skills/agent-audit/SKILL.md +++ b/plugins/kyberforge/skills/agent-audit/SKILL.md @@ -56,6 +56,11 @@ If a description finding is borderline, read `references/description-quality.md` - Direct role instruction: system prompt opens with `You are a [role]. When invoked, [action].` — SUGGESTION if absent - One job per agent: system prompt describes a single bounded task — SUGGESTION if scope appears unbounded +**Body/Frontmatter comments:** +- Inspect each comment block in the YAML frontmatter. For each comment, apply: *"Would the agent get this wrong without this comment?"* Flag any that answer "no" as padding. +- Look for patterns like `# Optional. ` or extensive inline guidance (more than 1–2 lines per field) that should be condensed or removed before shipping. +- This mirrors skill-audit's body-discipline check but applies to template documentation in the frontmatter — template guidance belongs in development; agent-ready files should have minimal comments. + **Pair consistency (cross-file):** - Both files exist — FAIL if counterpart is missing (kyberforge project convention; not a platform requirement from either CC or Copilot — label as such) - The following checks are covered automatically by `validate.sh`; apply them manually only when the script cannot run: both system prompt bodies non-empty — FAIL if either is empty @@ -65,7 +70,7 @@ If a description finding is borderline, read `references/description-quality.md` Open with a coverage line: ```text -Checked: structure · provider-safety · description · body · pair-consistency · provenance +Checked: structure · provider-safety · description · body · comment-discipline · pair-consistency · provenance ``` Then output only dimensions that have findings, grouped under H3 headings, FAILs before SUGGESTIONs within each dimension. Omit clean dimensions entirely. `### Provenance` findings are sourced verbatim from `validate-provenance.sh` output — copy them without rephrasing. diff --git a/plugins/kyberforge/skills/agent-author/SKILL.md b/plugins/kyberforge/skills/agent-author/SKILL.md index 6dea901..1b61ee2 100644 --- a/plugins/kyberforge/skills/agent-author/SKILL.md +++ b/plugins/kyberforge/skills/agent-author/SKILL.md @@ -85,7 +85,7 @@ The script is file-by-file no-op — it skips any file that already exists. ### Step 2 — Fill in the Claude Code agent file (`.md`) -Open the scaffolded Claude Code file. Replace every `FILL IN:` placeholder. +Open the scaffolded Claude Code file. Replace every `FILL IN:` placeholder. **Remove all template documentation comments from the YAML frontmatter after filling in required fields** — these are marked with `` and must be deleted before shipping. **`name`** — lowercase letters and hyphens only. Must be unique within the scope. @@ -141,6 +141,8 @@ There are **two distinct Copilot agent formats** with different paths and field **`source_keys`** — add the same top-level list as the CC file when research sources were used. Omit when no research was used. +**Remove all template documentation comments from the YAML frontmatter after filling in required fields** — these are marked with `` and must be deleted before shipping. + The system prompt body should match the Claude Code version — the agent's task definition is the same across providers. ### Step 4 — Populate or delete `agents/sources.md` (plugin scope only) diff --git a/plugins/kyberforge/skills/agent-author/assets/templates/claude-code.md b/plugins/kyberforge/skills/agent-author/assets/templates/claude-code.md index 411c16c..70eab33 100644 --- a/plugins/kyberforge/skills/agent-author/assets/templates/claude-code.md +++ b/plugins/kyberforge/skills/agent-author/assets/templates/claude-code.md @@ -1,71 +1,72 @@ --- -# Claude Code agent definition -# Fill in all FILL IN: placeholders. Remove or uncomment optional fields as needed. + name: AGENT_NAME -# Required. Lowercase letters and hyphens only. Must be unique within the scope. -# Duplicate names are silently discarded — no warning is emitted. + description: FILL IN: Action-first description of what this agent does and when to invoke it. -# Required. The primary signal for autonomous delegation. -# Start with a verb: "Reviews...", "Analyzes...", "Generates..." -# Include "Use proactively" to trigger automatic invocation. -# Be specific about the triggering condition and domain. -# Example: "Reviews pull request diffs for security issues. Use proactively after code changes." + -# tools: Read Bash Grep -# Optional. Space-separated allowlist. Omit to inherit all tools from parent. -# Use Agent(type1,type2) to restrict which subagent types this agent can spawn. -# Omit Agent entirely to prevent this agent from spawning subagents. -# Never available to subagents regardless of tools field: -# AskUserQuestion, EnterPlanMode, ExitPlanMode, ScheduleWakeup, WaitForMcpServers -# Exception: ExitPlanMode IS available when parent session runs in permissionMode: plan + -# model: sonnet -# Optional. Aliases: sonnet, opus, haiku, fable. Or full model ID. -# Omit to inherit from the main session. -# Resolution order: CLAUDE_CODE_SUBAGENT_MODEL env var → per-invocation param → this field → session model. + -# effort: medium -# Optional. low / medium / high / xhigh / max. Overrides session effort level for this agent. + -# maxTurns: 20 -# Optional. Integer cap on agentic turns. Prevents runaway on bounded tasks. + -# memory: project -# Optional. user / project / local. Enables cross-session MEMORY.md (first 200 lines loaded at startup). -# Auto-enables Read/Write/Edit tools. + -# isolation: worktree -# Optional. Set to "worktree" to run in an isolated temporary git worktree. -# Auto-cleaned if no changes are made. + -# color: blue -# Optional. UI color: red, blue, green, yellow, purple, orange, pink, cyan. + -# background: false -# Optional. Set true to force background execution. + -# disallowedTools: mcp__filesystem__write_file -# Optional. Space-separated denylist, applied before the tools allowlist. -# Supports mcp__* glob patterns (e.g. mcp__filesystem__* to block all filesystem tools). + -# skills: -# - skill-name -# Optional. Skill names preloaded into this agent's context at startup. -# Different from the source_keys metadata field (which is provenance-only). + -# initialPrompt: "Start by reading the README." -# Optional. Auto-submitted as the first turn when this agent activates as the main session thread. -# Only set when this agent is intended for main-thread (not subagent) activation. + -# source_keys: -# - slug-name -# Development-only. Add when research sources informed this agent (slugs must match agents/sources.md). -# Omit when no research was used. Not a runtime field — silently ignored by Claude Code. + -# NOTE: hooks, mcpServers, and permissionMode are silently ignored for plugin agents. -# Those fields only work in .claude/agents/ or ~/.claude/agents/. + --- FILL IN: System prompt body. Write as a direct role instruction. diff --git a/plugins/kyberforge/skills/agent-author/assets/templates/copilot.agent.md b/plugins/kyberforge/skills/agent-author/assets/templates/copilot.agent.md index 4faf333..4fb2803 100644 --- a/plugins/kyberforge/skills/agent-author/assets/templates/copilot.agent.md +++ b/plugins/kyberforge/skills/agent-author/assets/templates/copilot.agent.md @@ -1,44 +1,45 @@ --- -# GitHub Copilot CLI agent definition (CLI format — path: .github/agents/.agent.md) -# File extension MUST be .agent.md — a plain .md file is not picked up by Copilot CLI. -# Fill in all FILL IN: placeholders. Remove or uncomment optional fields as needed. -# Body length limit: 30,000 characters — content beyond this is silently truncated. -# -# NOTE: This template is for the CLI format. The cloud/IDE format (path: .github/copilot/agents/.md, -# extension: .md) supports additional fields: target, user-invocable, disable-model-invocation, mcp-servers. -# Do not add those fields here — they are silently ignored by the CLI runtime. + name: AGENT_NAME -# Required. Kebab-case identifier. Home-directory version wins on name collision. + description: FILL IN: Action-first description of what this agent does and when to invoke it. -# Required. Used by the runtime for automatic agent selection — quality matters. -# Start with a verb: "Reviews...", "Analyzes...", "Generates..." -# Example: "Reviews pull request diffs for security issues." + -# tools: ["read", "search", "edit"] -# Optional. Array of tool names. Omit = all available tools. [] = no tools. -# Copilot tool aliases (use these, not Claude Code names): -# execute — run shell commands (aliases: shell, Bash, powershell) -# read — read file contents (aliases: Read, NotebookRead) -# edit — modify files (aliases: Edit, MultiEdit, Write, NotebookEdit) -# search — search files (aliases: Grep, Glob) -# agent — invoke sub-agents (aliases: custom-agent, Task) -# web — web search and fetch (aliases: WebSearch, WebFetch) -# For MCP tools: "server-name/tool-name" or "server-name/*" + -# model: claude-sonnet-4-5 -# Optional. Model to run this agent on. -# Cloud/IDE-only fields (target, user-invocable, disable-model-invocation, mcp-servers) -# are not valid in this CLI format — use the .github/copilot/agents/.md path for those. + -# source_keys: -# - slug-name -# Development-only. Add when research sources informed this agent (slugs must match agents/sources.md). -# Omit when no research was used. Not a Copilot runtime field — silently ignored. + -# DO NOT include these Claude Code-only fields: -# maxTurns, isolation, memory, permissionMode, effort, hooks, mcpServers + --- FILL IN: System prompt body. Should match the Claude Code version — the agent's task is the same across providers.