agents/sources.md convention conflicts with claude plugin validate --strict #63

New Issue

Claude · 2026-07-04T18:47:12Z

Claude commented

2026-07-04 18:47:12 +00:00

Problem

ADR 0005 (docs/adr/0005-agent-author-dual-provider-scaffold.md) and the kyberforge agent-author/agent-audit skills document a plugin-scope provenance file at agents/sources.md (flat file, no frontmatter) for tracking the research sources behind an agent pair's source_keys.

However, claude plugin validate --strict auto-discovers every .md file directly under a plugin's agents/ directory and treats it as an agent definition requiring YAML frontmatter (name, description, etc.). A plain sources.md in that location fails validation with a missing-frontmatter warning (promoted to an error under --strict).

Where this was hit

First real usage of the convention: plugins/git/agents/sources.md (added in the git-plugin skill suite). It failed the validate-plugins pre-push hook.

Temporary workaround

Added minimal frontmatter to unblock the push:

---
name: git-agents-sources
description: Provenance record for the git plugin's agents, not an invokable agent. Do not invoke.
tools: none
---

See commit 0239b00.

This is not a good long-term fix — it makes the file indistinguishable from a real agent to any tooling or UI that lists available agents (e.g. it could show up as an invokable agent in Claude Code), which is semantically wrong.

Needed fix

Pick one and apply consistently across the convention docs and templates:

Relocate the provenance file out of agents/ — e.g. plugin root (plugins/<name>/sources.md) or a docs/ subdirectory — and update:
- docs/adr/0005-agent-author-dual-provider-scaffold.md
- plugins/kyberforge/skills/agent-author/SKILL.md
- plugins/kyberforge/skills/agent-audit/SKILL.md
- plugins/kyberforge/skills/agent-author/assets/templates/claude-code.md
- plugins/kyberforge/skills/agent-author/assets/templates/copilot.agent.md
- plugins/kyberforge/skills/agent-audit/README.md and scripts/validate-provenance.sh
- Revert the frontmatter workaround in plugins/git/agents/sources.md once relocated.
Or find a way to exclude it from agent auto-discovery — e.g. check if claude plugin validate supports an explicit agent manifest/allowlist in plugin.json instead of directory scanning. If no such mechanism exists, option 1 is likely the only real fix.

Reference files

docs/adr/0005-agent-author-dual-provider-scaffold.md
plugins/kyberforge/skills/agent-author/SKILL.md
plugins/kyberforge/skills/agent-audit/SKILL.md
plugins/git/agents/sources.md

## Problem ADR 0005 (`docs/adr/0005-agent-author-dual-provider-scaffold.md`) and the kyberforge `agent-author`/`agent-audit` skills document a plugin-scope provenance file at `agents/sources.md` (flat file, no frontmatter) for tracking the research sources behind an agent pair's `source_keys`. However, `claude plugin validate --strict` auto-discovers every `.md` file directly under a plugin's `agents/` directory and treats it as an agent definition requiring YAML frontmatter (`name`, `description`, etc.). A plain `sources.md` in that location fails validation with a missing-frontmatter warning (promoted to an error under `--strict`). ## Where this was hit First real usage of the convention: `plugins/git/agents/sources.md` (added in the git-plugin skill suite). It failed the `validate-plugins` pre-push hook. ## Temporary workaround Added minimal frontmatter to unblock the push: ```yaml --- name: git-agents-sources description: Provenance record for the git plugin's agents, not an invokable agent. Do not invoke. tools: none --- ``` See commit `0239b00`. This is not a good long-term fix — it makes the file indistinguishable from a real agent to any tooling or UI that lists available agents (e.g. it could show up as an invokable agent in Claude Code), which is semantically wrong. ## Needed fix Pick one and apply consistently across the convention docs and templates: 1. **Relocate the provenance file out of `agents/`** — e.g. plugin root (`plugins/<name>/sources.md`) or a `docs/` subdirectory — and update: - `docs/adr/0005-agent-author-dual-provider-scaffold.md` - `plugins/kyberforge/skills/agent-author/SKILL.md` - `plugins/kyberforge/skills/agent-audit/SKILL.md` - `plugins/kyberforge/skills/agent-author/assets/templates/claude-code.md` - `plugins/kyberforge/skills/agent-author/assets/templates/copilot.agent.md` - `plugins/kyberforge/skills/agent-audit/README.md` and `scripts/validate-provenance.sh` - Revert the frontmatter workaround in `plugins/git/agents/sources.md` once relocated. 2. **Or find a way to exclude it from agent auto-discovery** — e.g. check if `claude plugin validate` supports an explicit agent manifest/allowlist in `plugin.json` instead of directory scanning. If no such mechanism exists, option 1 is likely the only real fix. ## Reference files - `docs/adr/0005-agent-author-dual-provider-scaffold.md` - `plugins/kyberforge/skills/agent-author/SKILL.md` - `plugins/kyberforge/skills/agent-audit/SKILL.md` - `plugins/git/agents/sources.md`

Claude added the Kind/Bug

Priority

Medium

3

labels 2026-07-04 18:47:12 +00:00

Defame1297 added the

Reviewed

Confirmed

1

label 2026-07-04 19:04:24 +00:00

Defame1297 referenced this issue from a commit

2026-07-05 09:02:00 +00:00