[docs] Update documentation for features from 2025-10-31#2851
Merged
Conversation
This PR updates the documentation based on features merged in the last 24 hours. ## Documentation Updates ### Custom Agent Files (PR #2838, #2837) - Added comprehensive documentation for custom agent files in the AI Engines reference - Documented the new imports-based approach for agent files - Provided migration guide from deprecated `engine.custom-agent` field - Included examples of creating and using custom agents ### Permission Validation (PR #2843) - Documented new permission validation behavior in non-strict mode - Added examples of warning messages when permissions are under-provisioned - Explained the difference between non-strict and strict mode validation - Provided actionable guidance for resolving permission warnings ### Agent File Imports (PR #2838) - Updated Imports reference to explain agent file imports - Clarified that only one agent file can be imported per workflow - Cross-referenced Custom Agent Files documentation in Engines reference ## Changes Made - Updated `docs/src/content/docs/reference/engines.md`: - Added "Custom Agent Files" section with creation and usage examples - Documented agent file requirements and constraints - Provided migration guide from `engine.custom-agent` to `imports` - Updated `docs/src/content/docs/reference/frontmatter.md`: - Added "Permission Validation" subsection under Permissions - Documented non-strict mode warning behavior - Documented strict mode error behavior - Included example warning messages - Updated `docs/src/content/docs/reference/imports.md`: - Added "Agent Files" section - Updated "Frontmatter Merging" to mention agent file fields 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
github-actions
bot
added
automation
documentation
pelikhan
reviewed
Oct 31, 2025
| run: npm ci | ||
| ``` | ||
|
|
||
| ## Custom Agent Files |
Contributor
pelikhan
reviewed
Oct 31, 2025
| - **One per workflow**: Only one agent file can be imported per workflow | ||
| - **Import syntax**: Use `imports` field (not `engine.custom-agent`) | ||
|
|
||
| ## Migration from engine.custom-agent |
| --- | ||
| name: My Custom Agent | ||
| description: Specialized agent for code review tasks | ||
| tools: |
| order: 650 | ||
| --- | ||
|
|
||
| All AI engines (Copilot, Claude, Codex) support custom agent files that provide specialized instructions and behavior. Agent files are markdown documents stored in the `.github/agents/` directory and imported via the `imports` field. |
Contributor
There was a problem hiding this comment.
@copilot copilot supports agents natively, for other engine, the markdown body is injected as prompt.
Contributor
Contributor
|
@copilot format and recompile |
Contributor
pelikhan
approved these changes
Oct 31, 2025
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation Updates - 2025-10-31
This PR updates the documentation based on features merged in the last 24 hours.
Features Documented
Changes Made
AI Engines Reference (
docs/src/content/docs/reference/engines.md).github/agents/importsfieldengine.custom-agenttoimportsFrontmatter Reference (
docs/src/content/docs/reference/frontmatter.md)Imports Reference (
docs/src/content/docs/reference/imports.md)Merged PRs Referenced
Notes
The
--use-local-secretsflag from PR #2841 was already comprehensively documented in the CLI reference at lines 28, 279, 291, 303, and 318-340, so no additional documentation was needed.All documentation follows the Diátaxis framework and adheres to the style guidelines in
.github/instructions/documentation.instructions.md.