evizi-kit 1.0.0

package/kits/github/.github/skills/claude-code-subagent-creator/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: claude-code-subagent-creator
+description: Create Claude Code custom subagent profiles (Markdown files with YAML frontmatter stored in .claude/agents/) that use corresponding skills. Use when asked to create a Claude Code subagent for a skill, generate a subagent file, build a custom agent for Claude Code, or wire up skills to a Claude Code subagent. Triggers on requests like "create a Claude Code subagent for skill X", "make a Claude Code agent that uses skill Y", "generate subagent profile for these skills", or "set up a subagent for X task". Use proactively whenever someone mentions .claude/agents/, Claude Code automation, or wants a dedicated Claude agent for any repeatable task — even without explicitly saying "subagent". NOT for GitHub Copilot agents (.agent.md) — use copilot-subagent-creator for those.
+---
+
+# Claude Code Subagent Creator
+
+Create Claude Code subagent profiles — Markdown files with YAML frontmatter stored in `.claude/agents/` (project-level) or `~/.claude/agents/` (user-level). Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.
+
+The created subagent uses the `skills` frontmatter field to preload user-provided skill content at startup, so the subagent receives the full skill knowledge as part of its context without needing to read files at runtime.
+
+## Key Concepts
+
+- Subagents receive **only** their markdown body as the system prompt (plus basic environment details). They do **not** receive the full Claude Code system prompt.
+- The `skills` frontmatter field **injects the full content** of each listed skill into the subagent's context at startup. Subagents don't inherit skills from the parent conversation — you must list them explicitly.
+- The system prompt should be direct and actionable — never include meta-instructions like "go read SKILL.md". The skill content is already injected.
+- Each subagent should excel at **one specific task**.
+- Subagents can be **project-scoped** (`.claude/agents/`) for team use or **user-scoped** (`~/.claude/agents/`) for personal use across all projects. Determine scope before writing the file — ask the user if not specified.
+
+## Subagent Creation Workflow
+
+1. Identify and analyze the target skills
+2. Design the subagent configuration
+3. Write the system prompt
+4. Generate the subagent file
+5. Verify and test
+
+### Step 1: Identify and Analyze the Target Skills
+
+The user provides one or more skills that the subagent should use. Locate and read each skill's `SKILL.md` to understand what it does:
+- Check `skills/<skill-name>/SKILL.md` (workspace convention)
+- Check `.github/skills/<skill-name>/SKILL.md` (Copilot convention)
+
+For each skill, extract:
+1. **Skill name** — from frontmatter `name` (this goes into the `skills` list)
+2. **Skill description** — from frontmatter `description`
+3. **Workflow summary** — key steps the skill performs
+4. **Tool requirements** — what tools the skill needs (file read/write, search, shell, etc.)
+5. **Output format** — what the skill produces
+
+If the user describes a task without naming a skill, search the skills directories for a matching skill by reading available `SKILL.md` frontmatter descriptions. If no matching skill exists, inform the user and suggest creating one first using the `skill-creator` skill.
+
+### Step 2: Design the Subagent Configuration
+
+Derive the subagent configuration from the analyzed skills. For the full configuration reference, see [references/claude-code-subagent-configuration.md](references/claude-code-subagent-configuration.md).
+
+#### Name (required)
+Derive from the skill name(s). Use lowercase letters and hyphens:
+- Skill `pr-review` → Subagent `pr-reviewer`
+- Skill `increase-unit-test-coverage` → Subagent `test-coverage`
+- Skill `web-auto-coding` → Subagent `web-auto-coder`
+- Multiple skills → name by the primary responsibility (e.g., skills `api-conventions` + `error-handling-patterns` → `api-developer`)
+
+#### Description (required)
+Combine the skill descriptions into a concise subagent description (1-2 sentences) explaining **what the subagent does** and **when Claude should delegate to it**. Claude uses this to decide when to delegate, so be specific. Include "use proactively" for subagents that should be auto-triggered.
+
+Good: `"Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code."`
+
+Bad: `"Reviews code"` (too vague for Claude to know when to delegate)
+
+#### Skills (required)
+List all user-provided skills in the `skills` frontmatter field. The full content of each skill is injected into the subagent's context at startup.
+
+```yaml
+skills:
+  - skill-name-1
+  - skill-name-2
+```
+
+#### Tools
+Derive from the union of tool requirements across all provided skills. Grant only the tools the skills actually need. Omit `tools` to inherit all.
+
+| Tool | Description |
+|------|-------------|
+| `Read` | Read file contents |
+| `Write` | Write/create files |
+| `Edit` | Edit existing files |
+| `Bash` | Execute shell commands |
+| `Grep` | Search text in files |
+| `Glob` | Find files by pattern |
+
+Common patterns:
+- **Read-only subagent**: `tools: Read, Grep, Glob, Bash` + `disallowedTools: Write, Edit`
+- **Full access subagent**: Omit `tools` entirely
+- **Limited execution**: `tools: Read, Grep, Glob` (no Bash, no file modification)
+
+#### Model
+- `haiku` — fast, low-latency (codebase exploration, simple lookups)
+- `sonnet` — balanced capability and speed (most subagents)
+- `opus` — most capable (complex reasoning, architecture decisions)
+- `inherit` — same as main conversation (default if omitted)
+
+#### Scope
+Determine whether the subagent should be project-scoped or user-scoped **before** writing the file:
+- **Project** (`.claude/agents/`): Codebase-specific agents, checked into VCS for team sharing. Use this as the default.
+- **User** (`~/.claude/agents/`): Personal agents available in all projects (e.g., a general-purpose reviewer or formatter).
+
+If the user hasn't specified, ask: *"Should this be a project agent (team-shared) or a personal agent (available across all your projects)?"*
+
+#### Optional Fields
+Only add these when the subagent genuinely needs them:
+
+- **`memory`**: Enable persistent cross-session learning. Scopes: `user` (all projects), `project` (project-specific, shareable via VCS), `local` (project-specific, not in VCS).
+- **`hooks`**: Lifecycle hooks for validation or side effects. Use `PreToolUse` to validate, `PostToolUse` for post-processing, `Stop` for cleanup.
+- **`permissionMode`**: `default`, `acceptEdits`, `dontAsk`, `plan` (read-only), or `bypassPermissions` (use with extreme caution).
+- **`background`**: Set `true` to always run concurrently without blocking the main conversation. Useful for long-running monitors or background analysis tasks.
+- **`maxTurns`**: Cap the number of agentic turns. Useful for safety-sensitive or cost-sensitive subagents.
+- **`isolation`**: Set `worktree` for isolated git worktree execution — good for experiments or risky refactors.
+- **`mcpServers`**: MCP servers available to this subagent. Only list the MCP servers the skill actually needs — this applies least-privilege access. Example: a web-scraping skill might need the `browser` MCP server, while a database skill might need the `postgres` MCP server.
+
+### Step 3: Write the System Prompt
+
+The markdown body below the frontmatter becomes the subagent's **entire system prompt**. Since the skills are preloaded via the `skills` frontmatter field, the system prompt should **direct the subagent to use the preloaded skill knowledge** — not re-explain it. Follow these best practices from the official Claude Code documentation:
+
+#### Structure Pattern
+
+```
+1. Role statement — who the subagent is
+2. Skill reference — tell the subagent to follow the preloaded skills
+3. "When invoked" block — immediate action steps (numbered)
+4. Domain-specific guidance — checklist, key practices, or process (derived from the skills)
+5. Output format — how to present results
+```
+
+#### Prompt Writing Guidelines
+
+**Reference the preloaded skills by name.** Since skill content is injected at startup, tell the subagent: "Follow the conventions and patterns from the preloaded skills." or "Follow the workflow defined in the [skill-name] skill."
+
+**Be direct and actionable.** The subagent should know exactly what to do when invoked. Start with "When invoked:" followed by numbered steps derived from the skill workflow.
+
+**Derive domain guidance from the skills.** Extract the key checklists, criteria, or process steps from the skill and include them (or summarize them) in the prompt to reinforce the skill's workflow.
+
+**Be specific about output format.** Tell the subagent how to organize and present its results (e.g., "organized by priority: Critical → Warnings → Suggestions").
+
+**Keep it focused.** Each subagent should do one thing well. Don't combine multiple unrelated responsibilities.
+
+**Keep prompts concise.** Trust the skill injection — don't restate what the skill already explains. The prompt body should orient and direct the subagent, not re-teach the skill. Aim for 150–400 words; if you need more, the skill is doing the work, not the prompt.
+
+**Coordinate multiple skills explicitly.** When listing more than one skill, tell the subagent the order or relationship: *"Apply the api-conventions skill first to establish structure, then apply error-handling-patterns to add resilience."* This prevents the subagent from blending concerns randomly.
+
+**Include memory instructions when using `memory`.** Tell the subagent what to remember: `"Update your agent memory as you discover codepaths, patterns, library locations, and key architectural decisions."`
+
+**Do NOT include meta-instructions to read files.** Never tell the subagent to "go read SKILL.md for instructions". The skill content is already injected via the `skills` field. The prompt should complement the skill, not redirect to it.
+
+### Step 4: Generate the Subagent File
+
+**Confirm scope before writing.** If you haven't already confirmed with the user, do so now: *"Should this subagent go into `.claude/agents/` (project, shared with the team) or `~/.claude/agents/` (personal, available everywhere)?"* Default to `.claude/agents/` for codebase-specific agents.
+
+**File location by scope:**
+- **Project**: `.claude/agents/<agent-name>.md` — check into version control for team use
+- **User**: `~/.claude/agents/<agent-name>.md` — personal, available in all projects
+
+Use the template at [templates/subagent-profile.template.md](templates/subagent-profile.template.md) as a starting point, replacing `{{PLACEHOLDER}}` values.
+
+#### Example: Subagent with a Single Skill (pr-review)
+
+```markdown
+---
+name: pr-reviewer
+description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+skills:
+  - pr-review
+---
+
+You are a senior code reviewer ensuring high standards of code quality and security.
+
+Follow the review workflow defined in the pr-review skill.
+
+When invoked:
+1. Run git diff to see recent changes
+2. Focus on modified files
+3. Begin review following the skill's process
+
+Provide feedback organized by priority:
+- Critical issues (must fix)
+- Warnings (should fix)
+- Suggestions (consider improving)
+
+Include specific examples of how to fix issues.
+```
+
+#### Example: Subagent with Multiple Skills
+
+```markdown
+---
+name: api-developer
+description: Implement API endpoints following team conventions and error handling standards.
+tools: Read, Edit, Write, Bash, Grep, Glob
+model: sonnet
+skills:
+  - api-conventions
+  - error-handling-patterns
+---
+
+Implement API endpoints. Follow the conventions and patterns from the preloaded skills.
+
+When invoked:
+1. Understand the endpoint requirement
+2. Check existing patterns in the codebase
+3. Implement the endpoint following api-conventions skill
+4. Add error handling per the error-handling-patterns skill
+5. Write or update tests
+```
+
+#### Example: Subagent with Skills, Memory, and Hooks
+
+```markdown
+---
+name: db-reader
+description: Execute read-only database queries. Use when analyzing data or generating reports.
+tools: Bash, Read
+model: sonnet
+skills:
+  - database-schema
+memory: project
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/validate-readonly-query.sh"
+---
+
+You are a database analyst with read-only access. Use the table schemas and query patterns from the database-schema skill.
+
+When asked to analyze data:
+1. Identify which tables contain the relevant data using preloaded schema knowledge
+2. Write efficient SELECT queries with appropriate filters
+3. Present results clearly with context
+
+You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.
+
+Update your agent memory as you discover common queries, data patterns, and optimization insights.
+```
+
+#### Example: Read-Only Subagent with Skills
+
+```markdown
+---
+name: debugger
+description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
+tools: Read, Edit, Bash, Grep, Glob
+skills:
+  - fix-automation-tests
+---
+
+You are an expert debugger specializing in root cause analysis. Follow the debugging workflow from the fix-automation-tests skill.
+
+When invoked:
+1. Capture error message and stack trace
+2. Identify reproduction steps
+3. Isolate the failure location
+4. Implement minimal fix following the skill's patterns
+5. Verify solution works
+
+For each issue, provide:
+- Root cause explanation
+- Evidence supporting the diagnosis
+- Specific code fix
+- Testing approach
+- Prevention recommendations
+
+Focus on fixing the underlying issue, not the symptoms.
+```
+
+### Step 5: Verify and Test
+
+Before finalizing, verify:
+
+- [ ] `name` uses only lowercase letters and hyphens
+- [ ] `description` clearly states what the subagent does AND when to delegate
+- [ ] `skills` lists all user-provided skills and names match existing skills
+- [ ] `tools` grants only what the skills need (principle of least privilege)
+- [ ] `model` is appropriate for the task complexity
+- [ ] System prompt references the preloaded skills by name
+- [ ] System prompt starts with a role statement and "When invoked:" steps
+- [ ] System prompt does NOT tell the subagent to "go read" any files — skills are already injected
+- [ ] System prompt is concise (150–400 words) and does not restate skill content
+- [ ] Output format is specified in the prompt
+- [ ] File is in the correct scope location: `.claude/agents/` (project) or `~/.claude/agents/` (user)
+- [ ] If using `memory`, prompt includes instructions on what to remember
+- [ ] If using `hooks`, validation scripts exist and are executable
+- [ ] If using `mcpServers`, each listed server is available in the target environment
+- [ ] If using `background: true`, the task is genuinely long-running and non-blocking
+- [ ] If using `isolation: worktree`, understand that the subagent operates in a separate git worktree
+
+After saving, the subagent is available immediately in new sessions (or use `/agents` to load it in the current session).
+
+## Rules
+
+### DO:
+- Always include user-provided skills in the `skills` frontmatter field
+- Read each skill's SKILL.md to understand its workflow before designing the subagent
+- Derive the subagent's name, description, tools, and prompt from the skill analysis
+- Design focused subagents — each should excel at one specific task
+- Write detailed descriptions — Claude uses them to decide when to delegate
+- Limit tool access — grant only what the skills need
+- Reference preloaded skills by name in the system prompt
+- Follow the "When invoked:" numbered steps pattern from official examples
+
+### DO NOT:
+- Create a subagent without listing the user-provided skills in `skills` frontmatter
+- Write meta-instructions like "go read SKILL.md" in the prompt body — skill content is already injected
+- Grant more tools than the skills actually need
+- Combine multiple unrelated responsibilities into one subagent
+- Use `bypassPermissions` without explicit user request and understanding of risks
+- Omit the description field — it's required and drives delegation decisions
+- Write vague descriptions — Claude won't know when to delegate

package/kits/github/.github/skills/claude-code-subagent-creator/references/claude-code-subagent-configuration.md

@@ -0,0 +1,158 @@
+# Claude Code Subagent Configuration Reference
+
+Source: https://code.claude.com/docs/en/sub-agents
+
+## Subagent File Format
+
+Subagent files are Markdown files with YAML frontmatter. The body becomes the system prompt.
+
+```markdown
+---
+name: my-agent
+description: What the agent does and when to use it
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are a specialist. When invoked, do X, Y, Z.
+```
+
+## Subagent Scope (File Locations)
+
+| Location | Scope | Priority |
+|----------|-------|----------|
+| `--agents` CLI flag | Current session only | 1 (highest) |
+| `.claude/agents/` | Current project | 2 |
+| `~/.claude/agents/` | All user projects | 3 |
+| Plugin's `agents/` directory | Where plugin is enabled | 4 (lowest) |
+
+- **Project subagents** (`.claude/agents/`): Ideal for codebase-specific agents. Check into version control for team sharing.
+- **User subagents** (`~/.claude/agents/`): Personal agents available in all projects.
+
+## YAML Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique identifier using lowercase letters and hyphens |
+| `description` | Yes | When Claude should delegate to this subagent |
+| `tools` | No | Tools the subagent can use. Inherits all tools if omitted |
+| `disallowedTools` | No | Tools to deny, removed from inherited or specified list |
+| `model` | No | Model: `sonnet`, `opus`, `haiku`, or `inherit`. Defaults to `inherit` |
+| `permissionMode` | No | `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, or `plan` |
+| `maxTurns` | No | Maximum agentic turns before the subagent stops |
+| `skills` | No | Skills to preload into the subagent's context at startup |
+| `mcpServers` | No | MCP servers available to this subagent |
+| `hooks` | No | Lifecycle hooks scoped to this subagent |
+| `memory` | No | Persistent memory scope: `user`, `project`, or `local` |
+| `background` | No | Set `true` to always run as a background task. Default: `false` |
+| `isolation` | No | Set to `worktree` for isolated git worktree execution |
+
+## Available Tools
+
+Subagents can use any of Claude Code's internal tools. Common tools:
+
+| Tool | Description |
+|------|-------------|
+| `Read` | Read file contents |
+| `Write` | Write/create files |
+| `Edit` | Edit existing files |
+| `Bash` | Execute shell commands |
+| `Grep` | Search text in files |
+| `Glob` | Find files by pattern |
+| `Agent` | Spawn other subagents (main thread only) |
+
+Use `tools` for an allowlist or `disallowedTools` for a denylist:
+
+```yaml
+tools: Read, Grep, Glob, Bash
+disallowedTools: Write, Edit
+```
+
+### Restricting Subagent Spawning
+
+Use `Agent(worker, researcher)` syntax to allowlist which subagents can be spawned:
+
+```yaml
+tools: Agent(worker, researcher), Read, Bash
+```
+
+## Permission Modes
+
+| Mode | Behavior |
+|------|----------|
+| `default` | Standard permission checking with prompts |
+| `acceptEdits` | Auto-accept file edits |
+| `dontAsk` | Auto-deny permission prompts (explicitly allowed tools still work) |
+| `bypassPermissions` | Skip all permission checks (use with caution) |
+| `plan` | Plan mode (read-only exploration) |
+
+## Preloading Skills
+
+```yaml
+skills:
+  - api-conventions
+  - error-handling-patterns
+```
+
+Full skill content is injected at startup. Subagents don't inherit skills from the parent.
+
+## Persistent Memory
+
+```yaml
+memory: user
+```
+
+| Scope | Storage Location | Use When |
+|-------|-----------------|----------|
+| `user` | `~/.claude/agent-memory/<name>/` | Knowledge should persist across all projects |
+| `project` | `.claude/agent-memory/<name>/` | Knowledge is project-specific and shareable via VCS |
+| `local` | `.claude/agent-memory-local/<name>/` | Project-specific but should not be checked into VCS |
+
+When enabled, the subagent can read/write to its memory directory. Include memory instructions in the prompt:
+
+```
+Update your agent memory as you discover codepaths, patterns, library locations,
+and key architectural decisions.
+```
+
+## Hooks
+
+### In Subagent Frontmatter
+
+```yaml
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/validate-command.sh"
+  PostToolUse:
+    - matcher: "Edit|Write"
+      hooks:
+        - type: command
+          command: "./scripts/run-linter.sh"
+```
+
+Supported events in frontmatter: `PreToolUse`, `PostToolUse`, `Stop`.
+
+### In Project settings.json
+
+```json
+{
+  "hooks": {
+    "SubagentStart": [
+      { "matcher": "db-agent", "hooks": [{ "type": "command", "command": "./scripts/setup.sh" }] }
+    ],
+    "SubagentStop": [
+      { "hooks": [{ "type": "command", "command": "./scripts/cleanup.sh" }] }
+    ]
+  }
+}
+```
+
+## Foreground vs Background
+
+- **Foreground**: Blocks main conversation. Permission prompts pass through.
+- **Background**: Runs concurrently. Permissions must be pre-approved before launch.
+
+Set `background: true` in frontmatter to always run in background.

package/kits/github/.github/skills/claude-code-subagent-creator/templates/subagent-profile.template.md

@@ -0,0 +1,37 @@
+---
+name: {{AGENT_NAME}}
+description: {{AGENT_DESCRIPTION}}
+tools: {{TOOLS}}
+model: {{MODEL}}
+skills:
+  - {{SKILL_NAME_1}}
+  # - {{SKILL_NAME_2}}          # Add more skills if needed
+# --- Optional fields (uncomment as needed) ---
+# disallowedTools: Write, Edit  # Deny specific tools even if tools list is broad
+# permissionMode: acceptEdits   # default | acceptEdits | dontAsk | plan | bypassPermissions
+# maxTurns: 20                  # Cap agentic turns for safety/cost control
+# memory: project               # user | project | local
+# background: false             # true = always run concurrently
+# isolation: worktree           # worktree = isolated git worktree execution
+# mcpServers:                   # MCP servers this subagent can access
+#   - {{MCP_SERVER_NAME}}
+---
+
+You are {{ROLE_DESCRIPTION}}.
+
+Follow the workflow defined in the {{SKILL_NAME_1}} skill.
+
+When invoked:
+1. {{STEP_1}}
+2. {{STEP_2}}
+3. {{STEP_3}}
+
+{{DOMAIN_GUIDANCE}}
+
+For each {{TASK_UNIT}}, provide:
+- {{OUTPUT_ITEM_1}}
+- {{OUTPUT_ITEM_2}}
+- {{OUTPUT_ITEM_3}}
+
+{{ADDITIONAL_INSTRUCTIONS}}
+# If using memory, add: "Update your agent memory as you discover codepaths, patterns, and key decisions."