security-copilot-plugin-builder

name: security-copilot-plugin-builder description: Generates custom plugins and agents for Microsoft Security Copilot. Produces correct, validated YAML manifests for KQL, API, GPT, LogicApp, MCP, and Agent skill formats — including multi-format plugins and interactive agents. license: MIT compatibility:

• microsoft-security-copilot metadata: version: "1.0" author: mariocuomo tags:
  • security-copilot
  • plugins
  • agents
  • kql
  • yaml allowed-tools:
• FetchAdvancedHuntingTablesOverview
• FetchAdvancedHuntingTablesDetailedSchema
• search_tables
• search_for_tools
• get_evaluation

Security Copilot Custom Plugins & Agents Builder

Build correct, production-ready YAML manifest files for Microsoft Security Copilot custom plugins and agents.

What This Skill Does

This skill guides an AI agent through the complete lifecycle of generating Security Copilot custom plugins and agents:

1. Gather requirements from the user
2. Select the appropriate format(s) (KQL, API, GPT, LogicApp, MCP, Agent)
3. Discover and validate schemas (live tools when targeting KQL)
4. Generate the YAML manifest
5. Validate the output against checklists

Supported Formats

A single manifest can combine multiple formats in different SkillGroups. See MIXED_FORMAT_PLUGINS.md for examples.

Core Concepts

Plugin Structure

Every plugin has a Descriptor (identity + auth) and one or more SkillGroups (each with its own Format). See YAML_FORMAT.md for the complete manifest schema.

Agent Structure

Agents add AgentDefinitions (triggers, required skillsets) and use Format: Agent skills with Instructions (natural language) and ChildSkills. ChildSkills can include KQL, API, GPT, MCP, LogicApp, already available skills, and other Agent skills — enabling agent-to-agent communication. See AGENT_PLUGINS.md.

Authentication

API plugins require authentication configuration. Supported types: None, Basic, ApiKey, AAD, AADDelegated, OAuth flows. See AUTHENTICATION.md.

Generation Workflow

When asked to create a plugin or agent, follow these steps:

Step 0: Check Already Available Tools First

Before building anything, use search_for_tools followed by get_evaluation to check whether Security Copilot already has available skills, agents, or MCP tools that can satisfy the user's request.

This is a two-step process:

Step 0a: Submit the search

Call search_for_tools with the user's query or intent (e.g., "Analyze Defender incidents", "Get threat intelligence for an IP").

search_for_tools is an asynchronous operation. It submits the query to the Security Copilot evaluation engine and returns an evaluation receipt containing evaluationId, sessionId, and promptId — but not the actual results.

Step 0b: Retrieve the results

Call get_evaluation passing the evaluationID, sessionID, and promptID from the receipt returned by search_for_tools.

get_evaluation returns the completed evaluation with:

• result.outputComponents: the list of matching already available skills (SkillName, SkillsetName, DescriptionForModel, Inputs)
• result.suggestedPrompts: additional suggested skills with their inputs and descriptions

IMPORTANT: Always call get_evaluation after search_for_tools. The search_for_tools response alone does NOT contain the discovered skills — it only confirms the evaluation was created. The actual skill discovery results are only available via get_evaluation.

search_for_tools(userQuery) → receipt {evaluationId, sessionId, promptId}
        ↓
get_evaluation(evaluationID, sessionID, promptID) → full results with discovered skills

Decision logic

Use your judgment: if an already available tool does 90% of what the user needs, suggest it first. Only build custom plugins when they add clear value beyond what's already available.

Step 1: Gather Requirements

Ask the user:

1. Type: Plugin, agent, or both?
2. Format(s): KQL, API, GPT, LogicApp, MCP, Agent? (can mix multiple)
3. Purpose: What should it do?
4. Target (KQL): Defender, Sentinel, ADX, LogAnalytics?
5. Endpoint (API): Service URL, which endpoints?
6. Authentication (API): None, Basic, ApiKey, AAD, AADDelegated, OAuth?
7. Parameters: Any user inputs needed?
8. Agent workflow (Agent): Mission, steps, child skills?
9. Agent type (Agent): Standard (scheduled) or Interactive (chat)?

Step 2: Discover Schema (KQL only — MANDATORY)

CRITICAL: Before writing ANY KQL query, use the live schema tools.

DISCOVER TABLES → GET DETAILED SCHEMA → WRITE QUERY → VALIDATE

If live tools are unavailable, fall back to static references in BEST_PRACTICES.md and warn the user.

Step 3: Generate YAML

Load the appropriate reference file(s) for the format:

For the base YAML structure (Descriptor, SkillGroups, AgentDefinitions fields), always refer to YAML_FORMAT.md.

Step 4: Validate

Run the validation checklists from BEST_PRACTICES.md:

• General checks: naming, descriptions, parameter syntax, YAML formatting
• KQL checks: syntactic + semantic validation, live schema cross-reference
• API checks: OpenAPI version, operationId uniqueness, auth consistency
• Agent checks: AgentDefinitions, RequiredSkillsets, ChildSkills completeness
• LogicApp/MCP checks: required settings present

Step 5: Deliver

Return the complete YAML manifest(s) to the user. If multiple files are needed (e.g., agent manifest + child skills plugin, or API manifest + OpenAPI spec), provide all files.

Step 6: Generate Plugin Card (HTML)

After delivering the YAML, generate a Plugin Card — an HTML file that provides a visual summary of the plugin/agent and its skills.

Use the template at output/plugin_card_template.html as a base. Copy the template into a new file in the output/ folder named <PluginName>_card.html (using the Descriptor Name), and fill in the PLUGIN_DATA JavaScript object at the top of the file with the actual plugin data.

How to fill PLUGIN_DATA

Map the generated YAML fields to the PLUGIN_DATA object as follows:

IMPORTANT: Always generate the Plugin Card after delivering the YAML. The HTML file is self-contained — it can be opened in any browser and requires no server.

Key Rules

1. Always check already available tools first — before creating a custom plugin, use search_for_tools followed by get_evaluation to verify whether Security Copilot already provides skills that satisfy the user's need. search_for_tools submits the query asynchronously; get_evaluation retrieves the actual results. Both calls are required. Prefer already available tools when they fully cover the requirement; build custom plugins only for gaps or net-new functionality
2. Never skip live schema discovery for KQL plugins — queries built from memory fail at runtime
3. Never include real credentials — use <YOUR-TENANT-ID>, <YOUR-API-KEY> placeholders
4. One plugin can have multiple SkillGroups with different formats
5. Agent ChildSkills must be verifiable: either inline in the same manifest or in a RequiredSkillset
6. Interactive agents need Interfaces: [InteractiveAgent], PromptSkill, UserRequest input, OrchestratorSkill: DefaultAgentOrchestrator, SuggestedPrompts (starter prompts with IsStarterAgent: true, Title, Personas + follow-up suggestions without those fields). ChildSkills can include other Agent skills for agent-to-agent communication.
7. KQL time columns: Timestamp for Defender, TimeGenerated for Sentinel/LogAnalytics
8. OpenAPI: only version 3.0 or 3.0.1 supported
9. YAML multi-line: use |- for templates, >- for long descriptions
10. Agents should not use GPT child skills for text tasks — when an agent needs to generate reports, summaries, or analysis from collected data, embed those instructions directly in the agent's Instructions field instead of creating a separate GPT skill. The agent's model already handles natural language tasks; a GPT child skill adds unnecessary overhead. Reserve GPT skills for standalone plugins (without agents) or for specialized text transformations that need to be reusable independently.
11. Always generate the Plugin Card — after delivering the YAML, generate a <PluginName>_card.html file in the output/ folder using the plugin_card_template.html template. Fill in the PLUGIN_DATA object with the actual data from the generated plugin. This gives the user a visual overview of the plugin/agent and its skills.

Reference Files

Examples Summary

Official References

• Create custom plugins
• Agent Manifest
• Build Agents with Multiple Tools
• Build Interactive Agents
• API Plugins
• KQL Plugins
• GPT Plugins
• Security Copilot GitHub