Skip to content

Python: FileAgentSkillsProvider incorrectly treats backtick-quoted text in SKILL.md as resource references #4369

@pamelafox

Description

@pamelafox

Bug description

FileAgentSkillsProvider extracts resource file references from SKILL.md bodies using two patterns:

  1. Markdown links like [text](./file.py) — correctly identified as resource references
  2. Backtick-quoted strings like `presentation.yaml` or `slide_1.png` — incorrectly treated as resource references

It then validates that all extracted references exist as files relative to the skill directory. If any don't exist, the entire skill is excluded with a warning.

The problem is that backticks are standard markdown for inline code and are very commonly used to mention filenames in documentation text without implying those files exist in the skill directory.

Reproduction

Given this SKILL.md:

---
name: generate-writeup
description: Generate a write-up from a presentation.
---

# Generate write-up

A presentation folder containing a `presentation.yaml` file:

```yaml
title: "Talk title"
video: "https://youtube.com/..."
slides: "slides.pdf"
```

Use the prompt template in [writeup_prompt.jinja2](./writeup_prompt.jinja2) to generate output.

The provider will:

  • Correctly identify writeup_prompt.jinja2 as a resource (from the markdown link) ✅
  • Incorrectly identify presentation.yaml and slides.pdf as resources (from backtick-quoted text) ❌
  • Exclude the skill because presentation.yaml and slides.pdf don't exist in the skill directory

Output:

Excluding skill 'generate-writeup': referenced resource 'presentation.yaml' does not exist

Expected behavior

Only explicit markdown links ([text](./path)) should be validated as resource file references. Backtick-quoted strings should be ignored since they are standard inline code formatting with no implication that the referenced file exists locally.

Workaround

Load skill instructions directly into the agent's system prompt instead of using FileAgentSkillsProvider:

skill_md = Path(".github/skills/generate-writeup/SKILL.md").read_text()
# Strip YAML frontmatter
if skill_md.startswith("---"):
    end = skill_md.index("---", 3)
    skill_md = skill_md[end + 3:].strip()

async with Agent(client=client, instructions=f"Follow these instructions:\n{skill_md}", tools=[...]) as agent:
    response = await agent.run("Generate a writeup for ...")

Environment

  • agent-framework Python package (installed from git, commit 0d6b9d61a5a7b02a8ca5e60daebc95478bf918aa)
  • Python 3.11
  • macOS

Metadata

Metadata

Labels

bugSomething isn't workingpythonv1.0Features being tracked for the version 1.0 GA

Type

No type

Projects

Status

Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions