[UPDATE PROMPTS] Migrate deprecated mode: agent frontmatter to description (#37)

Copilot · felickz · data-douser · web-flow · commit 344b82acd365 · 2026-04-22T21:10:20.000Z
* Initial plan * Migrate deprecated mode: agent frontmatter to description in all prompt files Replace deprecated `mode: agent` / `mode: 'agent'` YAML frontmatter with `description` field in all 58 .prompt.md files. Also update instruction files that referenced the old format, and fix anomalous ````prompt` prefix in codeql_execute_query-server2.prompt.md. Agent-Logs-Url: https://github.com/advanced-security/codeql-development-template/sessions/e77050f9-eef7-468c-a4fd-67ab816ab889 Co-authored-by: felickz <1760475+felickz@users.noreply.github.com> * Tidy codeql_execute_query-server2.prompt.md * Another lint/format fix --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: felickz <1760475+felickz@users.noreply.github.com> Co-authored-by: Nathan Randall <70299490+data-douser@users.noreply.github.com> Co-authored-by: Nathan Randall <data-douser@github.com>
diff --git a/.github/instructions/ql_dev_prompts.instructions.md b/.github/instructions/ql_dev_prompts.instructions.md
@@ -21,7 +21,7 @@ For additional guidance on repository development workflows, refer to the langua
 
 ALWAYS do the following when creating or editing any `languages/<language>/tools/dev/*.prompt.md` file:
 
-- ALWAYS add YAML frontmatter with `mode: agent` at the top of the file, with `---` lines before and after the frontmatter
+- ALWAYS add YAML frontmatter with a `description` field at the top of the file, with `---` lines before and after the frontmatter
 - ALWAYS use valid markdown syntax, with the exception of the YAML frontmatter at the top of the `.prompt.md` file
 - ALWAYS demonstrate CodeQL syntax usage with code blocks that start with three backticks followed by `ql` (i.e. "```ql")
 - ALWAYS leave an empty line before and after each code block, as well as at the end of the file
diff --git a/.github/instructions/resources_cli_prompts.instructions.md b/.github/instructions/resources_cli_prompts.instructions.md
@@ -22,7 +22,7 @@ For additional guidance on repository development workflows, refer to:
 
 ALWAYS do the following when creating or editing any `resources/cli/**/*.prompt.md` file
 
-- ALWAYS add YAML frontmatter with `mode: agent` at the top of the file, with `---` lines before and after the frontmatter
+- ALWAYS add YAML frontmatter with a `description` field at the top of the file, with `---` lines before and after the frontmatter
 - ALWAYS use valid markdown syntax, with the exception of the YAML frontmatter at the top of the `.prompt.md` file
 - ALWAYS demonstrate the `bash` usage of the 'Primary use of <command>' section with a code block that starts with three backticks followed by `bash` (i.e. "```bash")
 - ALWAYS leave an empty line before and after each code block, as well as at the end of the file
diff --git a/.github/prompts/actions_query_development.prompt.md b/.github/prompts/actions_query_development.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guidance for developing CodeQL queries targeting GitHub Actions workflows
 ---
 
 # Actions Query Development
diff --git a/.github/prompts/cli_resources.prompt.md b/.github/prompts/cli_resources.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Summary and links to CLI tool resource prompts used in CodeQL development
 ---
 
 # CLI Resources Reference
diff --git a/.github/prompts/codeql_action_log_performance_review.prompt.md b/.github/prompts/codeql_action_log_performance_review.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Review CodeQL log output for performance issues and optimization opportunities
 ---
 
 You are reviewing CodeQL log output for performance issues.
diff --git a/.github/prompts/cpp_query_development.prompt.md b/.github/prompts/cpp_query_development.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guidance for developing CodeQL queries targeting C++ code
 ---
 
 # C++ Query Development
diff --git a/.github/prompts/csharp_query_development.prompt.md b/.github/prompts/csharp_query_development.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guidance for developing CodeQL queries targeting C# code
 ---
 
 # C# Query Development
diff --git a/.github/prompts/git_hooks.prompt.md b/.github/prompts/git_hooks.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Suggested git hooks for commit and push guidelines in this repository
 ---
 
 # Suggested git hooks for this repository
diff --git a/.github/prompts/go_query_development.prompt.md b/.github/prompts/go_query_development.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guidance for developing CodeQL queries targeting Go code
 ---
 
 # Go Query Development
diff --git a/.github/prompts/java_query_development.prompt.md b/.github/prompts/java_query_development.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guidance for developing CodeQL queries targeting Java code
 ---
 
 # Java Query Development
diff --git a/.github/prompts/javascript_query_development.prompt.md b/.github/prompts/javascript_query_development.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guidance for developing CodeQL queries targeting JavaScript and TypeScript code
 ---
 
 # JavaScript Query Development
diff --git a/.github/prompts/python_query_development.prompt.md b/.github/prompts/python_query_development.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guidance for developing CodeQL queries targeting Python code
 ---
 
 # Python Query Development
diff --git a/.github/prompts/ql_query_development.prompt.md b/.github/prompts/ql_query_development.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guidance for developing CodeQL queries targeting QL code
 ---
 
 # QL Query Development
diff --git a/.github/prompts/query_development.prompt.md b/.github/prompts/query_development.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Common guidance for developing CodeQL queries across all supported languages
 ---
 
 # CodeQL Query Development
diff --git a/.github/prompts/ruby_query_development.prompt.md b/.github/prompts/ruby_query_development.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guidance for developing CodeQL queries targeting Ruby code
 ---
 
 # Ruby Query Development
diff --git a/.github/prompts/test_driven_ql_development.prompt.md b/.github/prompts/test_driven_ql_development.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Test-driven development workflow for writing and testing CodeQL queries
 ---
 
 # Test-Driven Development (TDD) of `ql` Code
diff --git a/languages/actions/tools/dev/actions_ast.prompt.md b/languages/actions/tools/dev/actions_ast.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  CodeQL AST node reference for GitHub Actions
 ---
 
 ## CodeQL's core AST classes for `actions` language
diff --git a/languages/cpp/tools/dev/cpp_ast.prompt.md b/languages/cpp/tools/dev/cpp_ast.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  CodeQL AST node reference for the C++ language
 ---
 
 # CodeQL AST nodes for `cpp` language
diff --git a/languages/cpp/tools/dev/cpp_security_query_guide.prompt.md b/languages/cpp/tools/dev/cpp_security_query_guide.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guide for implementing C++ security queries in CodeQL with data flow analysis
 ---
 
 # CodeQL C++ Security Query Implementation Guide
diff --git a/languages/csharp/tools/dev/csharp_ast.prompt.md b/languages/csharp/tools/dev/csharp_ast.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  CodeQL AST node reference for the C# language
 ---
 
 # CodeQL AST nodes for `csharp` language
diff --git a/languages/csharp/tools/dev/csharp_security_query_guide.prompt.md b/languages/csharp/tools/dev/csharp_security_query_guide.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guide for implementing C# security queries in CodeQL
 ---
 
 # CodeQL C# Security Query Implementation Guide
diff --git a/languages/go/tools/dev/go_ast.prompt.md b/languages/go/tools/dev/go_ast.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  CodeQL AST class reference for Go programs
 ---
 
 # CodeQL AST Classes for Go Programs
diff --git a/languages/go/tools/dev/go_basic_queries.prompt.md b/languages/go/tools/dev/go_basic_queries.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Basic CodeQL query examples and patterns for Go programs
 ---
 
 # Basic CodeQL Query Examples for Go
diff --git a/languages/go/tools/dev/go_dataflow.prompt.md b/languages/go/tools/dev/go_dataflow.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guide to data flow and taint tracking analysis for Go in CodeQL
 ---
 
 # Analyzing Data Flow in Go
diff --git a/languages/go/tools/dev/go_library_modeling.prompt.md b/languages/go/tools/dev/go_library_modeling.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guide to customizing library models for Go using data extensions and model packs
 ---
 
 # Customizing Library Models for Go
diff --git a/languages/go/tools/dev/go_printast_customization.prompt.md b/languages/go/tools/dev/go_printast_customization.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guide for customizing the PrintAST query for Go
 ---
 
 # Go PrintAST Customization
diff --git a/languages/go/tools/dev/go_security_query_guide.prompt.md b/languages/go/tools/dev/go_security_query_guide.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guide for developing security-focused CodeQL queries for Go
 ---
 
 # Go Security Query Development Guide
diff --git a/languages/java/tools/dev/java_ast.prompt.md b/languages/java/tools/dev/java_ast.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  CodeQL AST node reference for the Java language
 ---
 
 # CodeQL AST nodes for `java` language
diff --git a/languages/javascript/tools/dev/javascript_ast.prompt.md b/languages/javascript/tools/dev/javascript_ast.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  CodeQL AST node reference for JavaScript and TypeScript
 ---
 
 # CodeQL AST nodes for `javascript` language
diff --git a/languages/javascript/tools/dev/javascript_security_query_guide.prompt.md b/languages/javascript/tools/dev/javascript_security_query_guide.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guide for implementing JavaScript security queries in CodeQL
 ---
 
 # CodeQL JavaScript Security Query Implementation Guide
diff --git a/languages/python/tools/dev/python_ast.prompt.md b/languages/python/tools/dev/python_ast.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  CodeQL AST node reference for the Python language
 ---
 
 # CodeQL AST nodes for `python` language
diff --git a/languages/python/tools/dev/python_security_query_guide.prompt.md b/languages/python/tools/dev/python_security_query_guide.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Guide for implementing Python framework models and security queries in CodeQL
 ---
 
 # CodeQL Python Framework and Query Implementation Guide
diff --git a/languages/ql/tools/dev/ql_ast.prompt.md b/languages/ql/tools/dev/ql_ast.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  CodeQL AST node reference for the QL language
 ---
 
 # CodeQL AST nodes for `ql` language
diff --git a/languages/ruby/tools/dev/ruby_ast.prompt.md b/languages/ruby/tools/dev/ruby_ast.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  CodeQL AST node reference for the Ruby language
 ---
 
 # CodeQL AST nodes for `ruby` language
diff --git a/resources/cli/codeql/codeql_bqrs_decode.prompt.md b/resources/cli/codeql/codeql_bqrs_decode.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: 'agent'
+description: >-
+  Reference for the codeql bqrs decode command
 ---
 
 # Command Resource for `codeql bqrs decode`
diff --git a/resources/cli/codeql/codeql_bqrs_info.prompt.md b/resources/cli/codeql/codeql_bqrs_info.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: 'agent'
+description: >-
+  Reference for the codeql bqrs info command
 ---
 
 # Command Resource for `codeql bqrs info`
diff --git a/resources/cli/codeql/codeql_database_analyze.prompt.md b/resources/cli/codeql/codeql_database_analyze.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: 'agent'
+description: >-
+  Reference for the codeql database analyze command
 ---
 
 # Command Resource for `codeql database analyze`
diff --git a/resources/cli/codeql/codeql_database_create.prompt.md b/resources/cli/codeql/codeql_database_create.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: 'agent'
+description: >-
+  Reference for the codeql database create command
 ---
 
 # Command Resource for `codeql database create`
diff --git a/resources/cli/codeql/codeql_execute_query-server2.prompt.md b/resources/cli/codeql/codeql_execute_query-server2.prompt.md
@@ -1,6 +1,6 @@
-````prompt
 ---
-mode: agent
+description: >-
+  Reference for the codeql execute query-server2 command
 ---
 
 # Command Resource for `codeql execute query-server2`
@@ -47,6 +47,7 @@ Template variables are passed through the query-server2 JSON protocol, not via C
 ```
 
 Example contextual query pattern:
+
 ```ql
 /**
  * @name Find References
@@ -95,18 +96,21 @@ codeql execute query-server2 --save-cache --max-disk-cache=4096
 ## Advanced configuration options
 
 ### Memory and threading
+
 - `--threads=<num>`: Number of evaluation threads (0 = one per core)
 - `--timeout=<seconds>`: Query evaluation timeout
 - `--heap-ram=<MB>`: Java heap memory allocation
 - `--off-heap-ram=<MB>`: Additional off-heap memory
 
 ### Caching and performance
+
 - `--save-cache`: Aggressively cache intermediate results
 - `--max-disk-cache=<MB>`: Maximum disk cache size
 - `--keep-full-cache`: Don't clean up cache after evaluation
 - `--tuple-counting`: Display tuple counts for performance analysis
 
 ### Debug and logging
+
 - `--debug`: Include additional debugging information
 - `--evaluator-log=<file>`: Output structured performance logs
 - `--evaluator-log-minify`: Minimize JSON log size
@@ -124,12 +128,14 @@ The query-server2 uses a JSON-based protocol over stdin/stdout for communication
 ## When to use query-server2 vs query run
 
 **Use `codeql execute query-server2` when:**
+
 - Building IDE integrations or tools that execute many queries
 - Need efficient handling of contextual queries with templates
 - Require quick evaluation of query fragments via JSON protocol
 - Want to minimize query execution latency in IDE environments
 
 **Use `codeql query run` when:**
+
 - Running single queries from command line
 - Following TDD methodology for query development
 - Scripting or automation scenarios
@@ -157,4 +163,3 @@ Run `codeql execute query-server2 --help --verbose` for much more information.
 
 - [`codeql query run`](./codeql_query_run.prompt.md) - Execute single CodeQL queries (alternative for simple use cases)
 - [`codeql query compile`](./codeql_query_compile.prompt.md) - Compile queries before execution
-````
diff --git a/resources/cli/codeql/codeql_generate_log-summary.prompt.md b/resources/cli/codeql/codeql_generate_log-summary.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Reference for the codeql generate log-summary command
 ---
 
 # Command Resource for `codeql generate log-summary`
diff --git a/resources/cli/codeql/codeql_generate_query-help.prompt.md b/resources/cli/codeql/codeql_generate_query-help.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: 'agent'
+description: >-
+  Reference for the codeql generate query-help command
 ---
 
 # Command Resource for `codeql generate query-help`
diff --git a/resources/cli/codeql/codeql_pack_install.prompt.md b/resources/cli/codeql/codeql_pack_install.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: 'agent'
+description: >-
+  Reference for the codeql pack install command
 ---
 
 # Command Resource for `codeql pack install`
diff --git a/resources/cli/codeql/codeql_pack_ls.prompt.md b/resources/cli/codeql/codeql_pack_ls.prompt.md
@@ -1,5 +1,6 @@
 ---
-mode: agent
+description: >-
+  Reference for the codeql pack ls command
 ---
 
 # Command Resource for `codeql pack ls`
diff --git a/resources/cli/codeql/codeql_query_compile.prompt.md b/resources/cli/codeql/codeql_query_compile.prompt.md
diff --git a/resources/cli/codeql/codeql_query_format.prompt.md b/resources/cli/codeql/codeql_query_format.prompt.md
diff --git a/resources/cli/codeql/codeql_query_run.prompt.md b/resources/cli/codeql/codeql_query_run.prompt.md
diff --git a/resources/cli/codeql/codeql_resolve_database.prompt.md b/resources/cli/codeql/codeql_resolve_database.prompt.md
diff --git a/resources/cli/codeql/codeql_resolve_languages.prompt.md b/resources/cli/codeql/codeql_resolve_languages.prompt.md
diff --git a/resources/cli/codeql/codeql_resolve_library-path.prompt.md b/resources/cli/codeql/codeql_resolve_library-path.prompt.md
diff --git a/resources/cli/codeql/codeql_resolve_metadata.prompt.md b/resources/cli/codeql/codeql_resolve_metadata.prompt.md
diff --git a/resources/cli/codeql/codeql_resolve_qlref.prompt.md b/resources/cli/codeql/codeql_resolve_qlref.prompt.md
diff --git a/resources/cli/codeql/codeql_resolve_queries.prompt.md b/resources/cli/codeql/codeql_resolve_queries.prompt.md
diff --git a/resources/cli/codeql/codeql_resolve_tests.prompt.md b/resources/cli/codeql/codeql_resolve_tests.prompt.md
diff --git a/resources/cli/codeql/codeql_test_accept.prompt.md b/resources/cli/codeql/codeql_test_accept.prompt.md
diff --git a/resources/cli/codeql/codeql_test_extract.prompt.md b/resources/cli/codeql/codeql_test_extract.prompt.md
diff --git a/resources/cli/codeql/codeql_test_run.prompt.md b/resources/cli/codeql/codeql_test_run.prompt.md
diff --git a/resources/cli/qlt/qlt_query_generate_new-query.prompt.md b/resources/cli/qlt/qlt_query_generate_new-query.prompt.md
diff --git a/resources/cli/qlt/qlt_query_run_install-packs.prompt.md b/resources/cli/qlt/qlt_query_run_install-packs.prompt.md
diff --git a/resources/cli/qlt/qlt_test_run_execute-unit-tests.prompt.md b/resources/cli/qlt/qlt_test_run_execute-unit-tests.prompt.md
diff --git a/resources/cli/qlt/qlt_test_run_validate-unit-tests.prompt.md b/resources/cli/qlt/qlt_test_run_validate-unit-tests.prompt.md
