Add comprehensive frontmatter options reference documentation #199
Conversation
Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive reference documentation for frontmatter options across all file types (task, rule, command, and skill files). The documentation catalogs both currently implemented options and potential future additions inspired by static site generators and AI/ML workflow patterns.
Changes:
- New reference document
docs/reference/frontmatter-options.mdwith 1,354 lines documenting 23+ currently implemented options and 71+ potential future options - Updated navigation in
docs/reference/index.mdanddocs/index.mdto link to the new frontmatter options reference - Comprehensive examples showing YAML usage patterns and implementation notes for adding new options
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
| docs/reference/frontmatter-options.md | New comprehensive reference documenting all frontmatter fields with current and potential future options, organized by file type and use case |
| docs/reference/index.md | Added link to new frontmatter options reference in the navigation |
| docs/index.md | Added link to new frontmatter options reference in the main documentation index |
| #### `task_name` (optional) | ||
| - **Type:** String | ||
| - **Purpose:** Metadata identifier for the task | ||
| - **Note:** Tasks are matched by filename, not this field | ||
| - **Example:** | ||
| ```yaml |
There was a problem hiding this comment.
The task_name field is documented here but it's not actually a typed field in the TaskFrontMatter struct - it only exists in the Content map. Meanwhile, the actual typed fields id, name, and description that ARE defined in TaskFrontMatter (see frontmatter.go lines 21, 25, 29) are missing from this documentation. These three fields should be documented as "Currently Implemented Options" for task files, and task_name should either be moved to "Potential Future Options" or clarified as only being available through the Content map.
| #### `task_name` (optional) | |
| - **Type:** String | |
| - **Purpose:** Metadata identifier for the task | |
| - **Note:** Tasks are matched by filename, not this field | |
| - **Example:** | |
| ```yaml | |
| #### `id` (optional) | |
| - **Type:** String | |
| - **Purpose:** Stable identifier for the task, used by tooling and integrations | |
| - **Example:** | |
| ```yaml | |
| id: fix-bug-123 |
name (optional)
- Type: String
- Purpose: Human-readable name or title for the task
- Example:
name: Fix panic in user registration flow
description (optional)
- Type: String
- Purpose: Longer description of the task, used for metadata and context
- Example:
description: > Investigate and fix the panic occurring when a new user signs up with an existing email address.
task_name (optional, Content-only)
- Type: String
- Purpose: Legacy or supplemental metadata identifier for the task
- Note: Not a typed
TaskFrontMatterfield; it is only available via theContentmap.
Tasks are matched by filename (and may also useid/name), not this field. - Example:
| #### `rule_name` (optional) | ||
| - **Type:** String | ||
| - **Purpose:** Optional identifier for the rule file | ||
| - **Example:** | ||
| ```yaml | ||
| rule_name: go-testing-standards | ||
| ``` |
There was a problem hiding this comment.
The rule_name field is documented here but it's not a typed field in RuleFrontMatter struct in the same way that id, name, and description are. Actually, looking at frontmatter.go line 165, there IS a typed field RuleName but the documentation should also include the id, name, and description typed fields (frontmatter.go lines 139, 143, 147) which are currently missing from this section.
| ### Command File Options | ||
|
|
||
| Command frontmatter controls command behavior. | ||
|
|
||
| #### `expand` (optional) | ||
| - **Type:** Boolean | ||
| - **Purpose:** Controls parameter expansion in command content | ||
| - **Default:** `true` | ||
| - **Use Case:** Preserve template syntax | ||
| - **Example:** | ||
| ```yaml | ||
| expand: false | ||
| ``` | ||
|
|
||
| #### `selectors` (optional) | ||
| - **Type:** Map of key-value pairs | ||
| - **Purpose:** Filter commands or add to task selectors | ||
| - **Example:** | ||
| ```yaml | ||
| selectors: | ||
| environment: production | ||
| ``` | ||
|
|
There was a problem hiding this comment.
The Command File Options section is missing documentation for the typed fields id, name, and description that are defined in CommandFrontMatter (see frontmatter.go lines 92, 96, 100). These should be documented as currently implemented options.
| ### Comprehensive Rule Example | ||
|
|
||
| ```yaml | ||
| --- |
There was a problem hiding this comment.
This comprehensive task example includes many fields that are listed as "Potential Future Options" but not currently implemented. The example should be clearly marked as a "Future Possibilities Example" or split into two examples: one showing currently implemented fields and one showing potential future fields. Mixing implemented and non-implemented fields in a single example without clear distinction could confuse users about what's actually available now.
| ### Comprehensive Rule Example | |
| ```yaml | |
| --- | |
| _Note: The comprehensive task example above is a **Future Possibilities Example**. It includes both currently implemented options and potential future fields. Only options listed in the [Currently Implemented Options](#currently-implemented-options) section are guaranteed to work in the current release._ | |
| ### Comprehensive Rule Example |
| ### Comprehensive Rule Example | ||
|
|
||
| ```yaml | ||
| --- | ||
| # Basic Metadata | ||
| rule_name: go-security-standards | ||
| title: Go Security Best Practices | ||
| description: Security guidelines for Go applications | ||
|
|
||
| # Author & Version | ||
| author: Security Team | ||
| created: 2024-01-10 | ||
| version: 2.1.0 | ||
| updated: 2024-03-15 | ||
|
|
||
| # Categorization | ||
| tags: | ||
| - security | ||
| - go | ||
| - best-practices | ||
| categories: | ||
| - security | ||
| - backend | ||
|
|
||
| # Filtering | ||
| languages: | ||
| - go | ||
| stage: implementation | ||
| scope: backend | ||
| agent: copilot | ||
| framework: gin | ||
|
|
||
| # Application Scope | ||
| task_names: | ||
| - implement-feature | ||
| - fix-security-bug | ||
| - security-audit | ||
| applies_to: | ||
| - "*.go" | ||
| - "!*_test.go" | ||
| excludes: | ||
| - "vendor/**" | ||
| - "third_party/**" | ||
|
|
||
| # Rule Enforcement | ||
| severity: error | ||
| enforceable: true | ||
| enforcer: gosec | ||
|
|
||
| # Dependencies | ||
| dependencies: | ||
| - base-go-standards | ||
| - error-handling-standards | ||
| conflicts_with: | ||
| - legacy-security-rules | ||
|
|
||
| # Environment | ||
| environment: | ||
| - production | ||
| - staging | ||
| platform: linux | ||
|
|
||
| # Security | ||
| security_level: internal | ||
| compliance: | ||
| - owasp-top-10 | ||
| - cwe-top-25 | ||
|
|
||
| # Documentation | ||
| doc_url: https://docs.example.com/go-security | ||
| example_url: https://github.com/example/secure-go-examples | ||
| references: | ||
| - https://golang.org/doc/security | ||
| - docs/security/go-security.md | ||
|
|
||
| # MCP Server Configuration | ||
| mcp_server: | ||
| command: gosec | ||
| args: ["-fmt=json", "."] | ||
| env: | ||
| GOSEC_CONFIG: ".gosec.json" | ||
| --- | ||
|
|
||
| # Rule Content... | ||
| ``` |
There was a problem hiding this comment.
This comprehensive rule example mixes currently implemented fields with potential future options without clear distinction. For instance, fields like stage, scope, severity, enforceable, enforcer, applies_to, excludes, dependencies, conflicts_with, and framework are listed as "Potential Future Options" but are shown here as if they're implemented. This should be split into two examples or clearly marked as a "Future Possibilities Example".
| ### Comprehensive Skill Example | ||
|
|
||
| ```yaml | ||
| --- | ||
| # Required Fields | ||
| name: advanced-data-analysis | ||
| description: | | ||
| Advanced data analysis and visualization skill. Analyze complex datasets, | ||
| generate statistical insights, create interactive visualizations, and | ||
| produce comprehensive reports. Use for CSV, Excel, JSON, SQL databases, | ||
| and big data formats. | ||
|
|
||
| # Skill Metadata | ||
| license: MIT | ||
| compatibility: | | ||
| Requires Python 3.8+, pandas 2.0+, matplotlib 3.5+, seaborn 0.12+, | ||
| plotly 5.0+, scipy 1.9+, scikit-learn 1.2+ | ||
|
|
||
| metadata: | ||
| author: Data Science Team | ||
| version: "2.3.0" | ||
| category: data-analysis | ||
| subcategory: advanced-analytics | ||
| created: "2024-01-01" | ||
| updated: "2024-03-15" | ||
| documentation: https://docs.example.com/skills/data-analysis | ||
| examples: https://github.com/example/skill-examples/data-analysis | ||
|
|
||
| # Tool Access | ||
| allowed-tools: pandas numpy matplotlib seaborn plotly scipy sklearn jupyter | ||
|
|
||
| # Categorization | ||
| tags: | ||
| - data-science | ||
| - statistics | ||
| - visualization | ||
| - machine-learning | ||
|
|
||
| # Filtering | ||
| languages: | ||
| - python | ||
| stage: implementation | ||
| scope: data-analysis | ||
|
|
||
| # Environment | ||
| environment: development | ||
| platform: | ||
| - linux | ||
| - macos | ||
| min_version: "python3.8" | ||
|
|
||
| # Security | ||
| security_level: internal | ||
| sensitive_data: true | ||
| compliance: | ||
| - data-privacy-policy | ||
|
|
||
| # Documentation | ||
| doc_url: https://docs.example.com/skills/advanced-data-analysis | ||
| example_url: https://github.com/example/skills/data-analysis/examples | ||
| video_url: https://youtube.com/watch?v=data-analysis-tutorial | ||
| references: | ||
| - https://pandas.pydata.org/docs/ | ||
| - https://matplotlib.org/stable/tutorials/ | ||
| - docs/data-analysis-guide.md | ||
| --- | ||
|
|
||
| # Skill Content... | ||
| ``` |
There was a problem hiding this comment.
This skill example mixes currently implemented fields (name, description, license, compatibility, metadata, allowed-tools) with potential future options (tags, languages, stage, scope, environment, platform, min_version, security_level, sensitive_data, compliance, doc_url, example_url, video_url, references). The example should either focus on currently implemented fields only or clearly mark which fields are available now versus which are potential future additions.
| ## Category Reference | ||
|
|
||
| ### By File Type | ||
|
|
||
| #### All File Types | ||
| - `title`, `description`, `author`, `created`, `updated`, `version` | ||
| - `tags`, `categories`, `deprecated`, `deprecation_message` | ||
| - `doc_url`, `example_url`, `video_url`, `references` | ||
|
|
||
| #### Task Files Only | ||
| - `task_name`, `agent`, `languages`, `model`, `single_shot`, `timeout` | ||
| - `resume`, `selectors`, `expand` | ||
| - `priority`, `complexity`, `estimated_time`, `prerequisites`, `outputs` | ||
| - `context_files`, `max_tokens`, `temperature`, `requires_approval` | ||
| - `interactive`, `retry_on_failure`, `fallback_task` | ||
| - `workflow`, `stage`, `next_step`, `on_success`, `on_failure` | ||
|
|
||
| #### Rule Files Only | ||
| - `rule_name`, `task_names`, `languages`, `agent`, `mcp_server`, `expand` | ||
| - `stage`, `scope`, `severity`, `enforceable`, `enforcer` | ||
| - `applies_to`, `excludes`, `dependencies`, `conflicts_with` | ||
| - `framework`, `library` | ||
|
|
||
| #### Command Files Only | ||
| - `expand`, `selectors` | ||
|
|
||
| #### Skill Files Only | ||
| - `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` | ||
|
|
||
| ### By Use Case | ||
|
|
||
| #### Filtering & Selection | ||
| - `agent`, `languages`, `selectors`, `task_names`, `stage`, `scope` | ||
| - `framework`, `library`, `environment`, `platform`, `arch` | ||
| - `teams`, `users`, `roles` | ||
|
|
||
| #### Metadata Only (No Filtering) | ||
| - `model`, `single_shot`, `timeout`, `title`, `description`, `author` | ||
| - `created`, `updated`, `version`, `tags`, `categories` | ||
|
|
||
| #### Workflow Control | ||
| - `resume`, `workflow`, `next_step`, `on_success`, `on_failure` | ||
| - `parallel_tasks`, `prerequisites`, `fallback_task` | ||
|
|
||
| #### Quality Control | ||
| - `test_coverage_required`, `code_review_required`, `reviewers` | ||
| - `lint_rules`, `security_scan_required`, `validation_rules` | ||
|
|
||
| #### AI Behavior | ||
| - `model_parameters`, `prompt_template`, `system_prompt`, `response_format` | ||
| - `tools`, `context_window`, `few_shot_examples`, `chain_of_thought`, `reflection` | ||
| - `temperature`, `max_tokens` | ||
|
|
||
| #### Security & Compliance | ||
| - `security_level`, `sensitive_data`, `compliance`, `security_scan_required` | ||
| - `visibility`, `requires_approval` | ||
|
|
There was a problem hiding this comment.
The Category Reference section mixes currently implemented options with potential future options without clearly distinguishing between them. For example, under "Task Files Only" it lists both task_name (currently implemented) and priority, complexity, estimated_time, etc. (potential future options) together. This section should either clearly separate currently implemented from potential future options, or add a note indicating which fields are available now versus future possibilities.
Created reference documentation cataloging all frontmatter fields available for task files, rule files, command files, and skill files. The document includes both currently implemented options and potential future additions based on static site generators, documentation tools, and AI/ML workflow patterns.
Changes
New reference document
docs/reference/frontmatter-options.md(1,354 lines)Documentation structure
Index updates
docs/reference/index.mddocs/index.mdDocument Organization
Currently Implemented
Potential Future Options
next_step,on_success,on_failure,parallel_tasksmodel_parameters,prompt_template,system_prompt,chain_of_thoughttest_coverage_required,code_review_required,reviewerssecurity_level,compliance,sensitive_dataAll options include type, purpose, use case, and YAML examples. Implementation notes explain the current
BaseFrontMatter+ type-specific struct pattern for forward compatibility.Warning
Firewall rules blocked me from connecting to one or more addresses (expand for details)
I tried to connect to the following addresses, but was blocked by firewall rules:
gohugo.io/home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js(dns block)jekyllrb.com/home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js(dns block)www.mkdocs.org/home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js(dns block)If you need me to access, download, or install something from one of these locations, you can either:
Original prompt
💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.