Merged
Conversation
Replace fabricated skill.json references with actual SKILL.md format used by the SDK. The previous doc described a skill.json manifest, prompts/ directory, and tools/ directory that don't exist in the implementation. Changes: - Replace skill.json with SKILL.md format (YAML frontmatter + markdown) - Fix directory structure to match actual layout (skill-name/SKILL.md) - Add onPermissionRequest to all code examples (required by SDK) - Remove fabricated prompts/ and tools/ directory concepts - Fix troubleshooting and best practices to reference SKILL.md - Remove speculative skill conflict precedence claims Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR fixes significant documentation inaccuracies in the Skills guide. The previous documentation incorrectly described skills as using a skill.json manifest with separate prompts/ and tools/ directories, when skills are actually defined via SKILL.md markdown files with optional YAML frontmatter. The PR corrects this fundamental misunderstanding and adds required onPermissionRequest handlers that were missing from all code examples.
Changes:
- Replaced fabricated
skill.jsonformat with actualSKILL.mdformat (markdown with optional YAML frontmatter) - Corrected directory structure documentation to show the real
skill-name/SKILL.mdlayout - Added required
onPermissionRequesthandlers to all complete code examples - Removed unverified claims about skill conflict precedence behavior
- Updated troubleshooting section to reference
SKILL.mdinstead ofskill.json
This was referenced Feb 27, 2026
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.
Summary
The
docs/guides/skills.mddocument contained significant inaccuracies — it described askill.jsonmanifest,prompts/directory, andtools/directory that don't exist in the actual implementation. Skills are defined viaSKILL.mdfiles, notskill.json.Changes
skill.jsonwithSKILL.mdformat — Document the actual YAML frontmatter + markdown format used by all E2E tests and scenario samplesskill-name/SKILL.mdlayout instead of fabricatedskill.json/prompts//tools/treeonPermissionRequestto all code examples — Required by the SDK; previous examples would throwSKILL.mdinstead ofskill.jsonValidation
npm run extract && npm run validate:tspasses (all 174 code blocks valid across all 4 languages)