Implement Agent Skills discovery with progressive disclosure

[Copilot]

Agent Skills Implementation - Final

All feedback addressed:

Latest Changes

1. Include location in XML output (3033327)

   • Changed Location field to use xml:"location" instead of xml:"-"
   • Location (absolute path to SKILL.md) now appears in XML output
   • Matches prompt instruction: "reading the SKILL.md file at the location provided"
   • Tests updated to expect location in XML

2. Added Skills section to prompt (972c561)

   • Skills section added to Result.Prompt after rules and before task content
   • Includes explanation: "You have access to the following skills. Skills are specialized capabilities that provide domain expertise, workflows, and procedural knowledge. When a task matches a skill's description, you can load the full skill content by reading the SKILL.md file at the location provided."
   • Shows available skills in XML format directly in the prompt
   • Only added when skills are discovered

3. Simplified validation logic (c9b8959)

   • Removed redundant len() < 1 checks (empty string check already covers this)
   • Only check maximum length (name ≤ 64, description ≤ 1024)
   • Empty string check remains for required fields

4. Improved error handling (c9b8959)

   • Return error instead of warning when filepath.Abs fails
   • Consistent error handling throughout skill discovery

5. Removed redundant guards (c9b8959)

   • Removed if skillsXML != "" check in main.go (cannot be empty if skills exist)
   • Removed if len(a.Skills) == 0 check in AsXML() (always return XML)
   • Empty skills now returns <available_skills></available_skills>

Implementation

• Skill Discovery: discoverSkills() searches .agents/skills/, parses SKILL.md frontmatter, validates required fields, and filters by selectors
• Progressive Disclosure: Loads only metadata (name/description/location) at startup
• Skills Package: pkg/codingcontext/skills with Skill and AvailableSkills types
• Field Validation: Name 1-64 chars, description 1-1024 chars (returns error if invalid)
• Selector Optimization: Selector filtering before validation
• Output Format: XML via encoding/xml package with proper escaping
• Error Handling: Returns errors for all validation failures and path resolution issues
• Prompt Integration: Skills section added to prompt with usage instructions and location paths for agents

Example Output

Skills appear in two places with location included:

1. Standalone XML output (for parsing/processing):

<available_skills>
  <skill>
    <name>pdf-processing</name>
    <description>Extract text and tables from PDF files, fill forms, merge documents.</description>
    <location>/path/to/.agents/skills/pdf-processing/SKILL.md</location>
  </skill>
  <skill>
    <name>data-analysis</name>
    <description>Analyze datasets, generate charts, and create summary reports.</description>
    <location>/path/to/.agents/skills/data-analysis/SKILL.md</location>
  </skill>
</available_skills>

2. In the prompt (for agent context):

[rules content...]

# Skills

You have access to the following skills. Skills are specialized capabilities that provide domain expertise, workflows, and procedural knowledge. When a task matches a skill's description, you can load the full skill content by reading the SKILL.md file at the location provided.

<available_skills>
  <skill>
    <name>pdf-processing</name>
    <description>Extract text and tables from PDF files, fill forms, merge documents.</description>
    <location>/path/to/.agents/skills/pdf-processing/SKILL.md</location>
  </skill>
  <skill>
    <name>data-analysis</name>
    <description>Analyze datasets, generate charts, and create summary reports.</description>
    <location>/path/to/.agents/skills/data-analysis/SKILL.md</location>
  </skill>
</available_skills>

[task content...]

Testing

• All existing tests passing
• Tests updated for simplified validation
• Empty skills test updated to expect XML output
• Tests updated to expect location in XML output
• Manual testing confirms Skills section appears in prompt with proper instructions and locations

Original prompt

Your task is to implement Agent Skills. Skills will live in .agents/skills. Skill should be selectable. (just like rules).

---

Overview

Copy page

A simple, open format for giving agents new capabilities and expertise.

Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently.
​
Why Agent Skills?
Agents are increasingly capable, but often don’t have the context they need to do real work reliably. Skills solve this by giving agents access to procedural knowledge and company-, team-, and user-specific context they can load on demand. Agents with access to a set of skills can extend their capabilities based on the task they’re working on.
For skill authors: Build capabilities once and deploy them across multiple agent products.
For compatible agents: Support for skills lets end users give agents new capabilities out of the box.
For teams and enterprises: Capture organizational knowledge in portable, version-controlled packages.
​
What can Agent Skills enable?
Domain expertise: Package specialized knowledge into reusable instructions, from legal review processes to data analysis pipelines.
New capabilities: Give agents new capabilities (e.g. creating presentations, building MCP servers, analyzing datasets).
Repeatable workflows: Turn multi-step tasks into consistent and auditable workflows.
Interoperability: Reuse the same skill across different skills-compatible agent products.
​

What are skills?

Copy page

Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows.

At its core, a skill is a folder containing a SKILL.md file. This file includes metadata (name and description, at minimum) and instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, templates, and reference materials.
my-skill/
├── SKILL.md # Required: instructions + metadata
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
└── assets/ # Optional: templates, resources
​
How skills work
Skills use progressive disclosure to manage context efficiently:
Discovery: At startup, agents load only the name and description of each available skill, just enough to know when it might be relevant.
Activation: When a task matches a skill’s description, the agent reads the full SKILL.md instructions into context.
Execution: The agent follows the instructions, optionally loading referenced files or executing bundled code as needed.
This approach keeps agents fast while giving them access to more context on demand.
​
The SKILL.md file
Every skill starts with a SKILL.md file containing YAML frontmatter and Markdown instructions:

name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.

PDF Processing

When to use this skill

Use this skill when the user needs to work with PDF files...

How to extract text

1. Use pdfplumber for text extraction...

How to fill forms

...
The following frontmatter is required at the top of SKILL.md:
name: A short identifier
description: When to use this skill
The Markdown body contains the actual instructions and has no specific restrictions on structure or content.
This simple format has some key advantages:
Self-documenting: A skill author or user can read a SKILL.md and understand what it does, making skills easy to audit and improve.
Extensible: Skills can range in complexity from just text instructions to executable code, assets, and templates.
Portable: Skills are just files, so they’re easy to edit, version, and share.

---

pecification

Copy page

The complete format specification for Agent Skills.

This document defines the Agent Skills format.
​
Directory structure
A skill is a directory containing at minimum a SKILL.md file:
skill-name/
└── SKILL.md # Required
You can optionally include additional directories such as scripts/, references/, and assets/ to support your skill.
​
SKILL.md format
The SKILL.md file must contain YAML frontmatter followed by Markdown content.
​
Frontmatter (required)

name: skill-name
description: A description of what this skill does and when to use it.

With optional fields:

name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
metadata:
author: example-org
version: "1.0"

Field Required Constraints
name Yes Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen.
description Yes Max 1024 characters. Non-empty. Describes what the skill does and when to use it.
license No License name or reference to a bundled license file.
compatibility No Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.).
metadata No Arbitrary key-value mapping for additional metadata.
allowed-tools No...

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[alexec]

@copilot

[alexec]

@copilot move this filtering before the name and description checks.

[Copilot]

Done in 9ac54d1. Selector filtering now happens before name and description validation checks.

[alexec]

Don't include the skills as Markdown. Instead lets have some new package for skills use the encoding/xml package in main.go to render them.

• skills.AvailalableSkills
• skills.Name
• skills.Description
• skills.Location - the absolute path to the skill

skills.AvailalableSkills.String() should produce the XML output.

[Copilot]

Done in 9ac54d1. Created new pkg/codingcontext/skills package with:

• skills.AvailableSkills collection type
• skills.Skill with Name, Description, and Location (absolute path) fields
• skills.String() method that produces XML output with proper escaping
• Result.Skills is now skills.AvailableSkills instead of markdown slice

[alexec]

This will be

Suggested change

	skills []markdown.Markdown[markdown.SkillFrontMatter] // Discovered skills (metadata only)
	skills skills.AvailableSkills

[Copilot]

Done in 9ac54d1. Context.skills field is now skills.AvailableSkills type.

[alexec]

@copilot Use encoding/xml to produce the XML output. If that returns an error, change String() to AsXML()

[Copilot]

@copilot Use encoding/xml to produce the XML output. If that returns an error, change String() to AsXML()

Done in 904db7c. Changed to use encoding/xml with xml.MarshalIndent() for proper XML encoding. Method renamed to AsXML() that returns (string, error). Also updated per new requirement: validation failures now return errors instead of logging warnings.

[alexec]

@copilot You don't need to check for empty, then check for length < 1. You can just check empty.

[Copilot]

@copilot You don't need to check for empty, then check for length < 1. You can just check empty.

Done in c9b8959. Removed redundant len() < 1 checks - empty string validation already covers this case.

[alexec]

@copilot The Result contains a Prompt field. Add a "Skills" section after the rules with an explanation to agent on how to use skills and the skills.

[Copilot]

@copilot The Result contains a Prompt field. Add a "Skills" section after the rules with an explanation to agent on how to use skills and the skills.

Done in 972c561. Added "Skills" section to the Prompt field after rules with explanation on how agents can use skills. The section includes instructions and displays available skills in XML format. Only appears when skills are discovered.

[Copilot]

Pull request overview

This PR implements Agent Skills discovery with progressive disclosure, allowing agents to discover and load specialized capabilities on demand. The implementation adds skill discovery from .agents/skills/ directories, loads only metadata (name and description) at startup, and integrates skill information into the agent prompt.

Key Changes

• Added skills package with Skill and AvailableSkills types supporting XML serialization
• Implemented skill discovery in discoverSkills() that parses SKILL.md frontmatter, validates required fields, and applies selector filtering
• Integrated skills into the prompt with usage instructions and XML-formatted metadata

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pkg/codingcontext/skills/skills.go	Defines Skill and AvailableSkills types with XML marshaling support
pkg/codingcontext/skills/skills_test.go	Table-driven tests for XML serialization including edge cases
pkg/codingcontext/context.go	Implements skill discovery, validation, and prompt integration
pkg/codingcontext/context_test.go	Comprehensive tests for skill discovery, validation, and selector filtering
pkg/codingcontext/markdown/frontmatter.go	Adds SkillFrontMatter struct with required and optional fields
pkg/codingcontext/result.go	Extends Result struct to include discovered skills
pkg/codingcontext/paths.go	Adds skillSearchPaths function for .agents/skills directory
main.go	Adds XML output for discovered skills in normal mode
examples/agents/skills/*/SKILL.md	Example skills demonstrating the format (pdf-processing, data-analysis)
examples/agents/skills/README.md	Documentation explaining the Agent Skills format and usage
.gitignore	Excludes test workspace from version control