Document Skills feature and correct documentation omissions

[Copilot]

The Skills feature was fully implemented but completely undocumented. Additionally, MCP server configuration lacked visibility in README, and the interaction between -w and -r flags was unclear.

Changes

Skills Feature Documentation (NEW)

• docs/how-to/create-skills.md: Complete guide covering progressive disclosure pattern, frontmatter fields (name, description, license, compatibility, metadata), XML output format, selector filtering, validation rules, and examples
• docs/reference/file-formats.md: Skills file format specification with required/optional fields and validation constraints
• docs/reference/search-paths.md: Skills search paths (.agents/skills/*/SKILL.md)
• docs/reference/cli.md: Skills XML output format in stdout
• README.md: Skills overview with examples showing directory structure and frontmatter

Skills enable progressive disclosure - only metadata (name, description, location) appears in initial context; AI agents load full content on-demand:

<available_skills>
  <skill>
    <name>data-analysis</name>
    <description>Analyze datasets, generate charts...</description>
    <location>/path/to/.agents/skills/data-analysis/SKILL.md</location>
  </skill>
</available_skills>

Additional Updates

• MCP Server Configuration: Added README overview with reference link (detailed docs already existed in file-formats.md)
• Write Rules + Resume Mode: Clarified that -w -r skips writing rules file since no rules are collected in resume mode
• Documentation Indexes: Updated docs/index.md and docs/how-to/index.md to include Skills

Statistics

• 698 lines of documentation added
• 7 files modified, 1 new file created
• No code changes

Original prompt

Review the code and compare to the documentation. Update the documentation to include any corrections and omissions.

---

💡 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.

[Copilot]

Pull request overview

This PR comprehensively documents the Skills feature, which was fully implemented but previously undocumented. The documentation adds 698 lines across 8 files, explaining how skills provide progressive disclosure of specialized capabilities to AI agents, with only metadata (name, description, location) initially included in context while full skill content can be loaded on-demand.

Key Changes

• Created complete Skills documentation with usage patterns, examples, and best practices
• Clarified write rules behavior in resume mode (no rules file written when using -w -r)
• Added MCP server configuration overview to README with link to detailed reference

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/how-to/create-skills.md	New comprehensive guide covering skill creation, frontmatter fields, progressive disclosure pattern, selectors, validation, and troubleshooting
docs/reference/file-formats.md	Added Skills file format specification with required/optional fields, directory structure, progressive disclosure, XML output format, and validation rules
docs/reference/search-paths.md	Added skill file search paths documentation (.agents/skills/*/SKILL.md) with directory structure examples
docs/reference/cli.md	Added skills metadata to stdout output documentation and clarified resume mode behavior with write rules flag
README.md	Added Skills system overview with feature descriptions, directory examples, frontmatter fields, XML output format, and MCP server configuration section
docs/index.md	Added "Create Skills" link to How-To section and "Skills System" to features list
docs/how-to/index.md	Added "Create Skills" entry to how-to guides index

[Copilot]

The nested directory structure shown here will not work with the current implementation. The skill discovery code only searches immediate subdirectories of .agents/skills/, not nested subdirectories. The data/ folder containing data-analysis/ and data-visualization/ subdirectories will not be discovered. Each skill must be a direct child of .agents/skills/. The example should be flattened to show direct subdirectories only, such as:

.agents/skills/
├── web-scraping/
│   └── SKILL.md
├── api-testing/
│   └── SKILL.md
├── data-analysis/
│   └── SKILL.md
└── data-visualization/
    └── SKILL.md

Suggested change

	└── data/
	├── data-analysis/
	│ └── SKILL.md
	└── data-visualization/
	└── SKILL.md
	├── data-analysis/
	│ └── SKILL.md
	└── data-visualization/
	└── SKILL.md