microsoft / microsoft/GitHub-Copilot-for-Azure

Codex logs errors for intended nested azure-app-onboard SKILL.md files during session startup

Open
#3,109 3 comments 0 reactions 1 assignee Claimed by @vaibbavisk20 View on GitHub
assign-to-copilot bug skills telemetry
Dominant language
Python
Stars
250
Forks
204
Avg merge
1d 12h
Merged PRs (30d)
67

Description

## Summary

Codex recursively discovers the three intended internal phase documents under
`azure-app-onboard` as skills and emits `ERROR` log entries because they do not
contain YAML frontmatter.

This is a compatibility follow-up to microsoft/azure-skills#199. The earlier issue established that
the nested `SKILL.md` filenames are intentional for agents that treat them as
ordinary references. Codex, however, recursively validates every distributed
`SKILL.md`, including during spawned subagent session initialization.

## Affected files

- `.github/plugins/azure-skills/skills/azure-app-onboard/prepare/SKILL.md`
- `.github/plugins/azure-skills/skills/azure-app-onboard/scaffold/SKILL.md`
- `.github/plugins/azure-skills/skills/azure-app-onboard/deploy/SKILL.md`

The same files are also present under the marketplace `skills/` projection.

## Observed behavior

When Codex initializes a spawned subagent session, it emits one error for each
file:

```text
failed to load skill .../azure-app-onboard/prepare/SKILL.md:
missing YAML frontmatter delimited by ---

failed to load skill .../azure-app-onboard/scaffold/SKILL.md:
missing YAML frontmatter delimited by ---

failed to load skill .../azure-app-onboard/deploy/SKILL.md:
missing YAML frontmatter delimited by ---
```

The child session still starts successfully. The impact is repeated false
`ERROR` telemetry, noisy health diagnostics, and a plugin package that cannot
pass recursive `SKILL.md` validation in Codex.

## Reproduction

1. Install and enable `azure@azure-skills` in Codex.
2. Start a Codex session or spawn a subagent so the plugin skill catalogue is
loaded for a new session.
3. Inspect the Codex logs for `failed to load skill` entries.

## Environment

- Azure Skills plugin: `1.2.32`
- Azure Skills revision: `ea76537ef7f2ae4f3a3d02d26347ec5afe19068c`
- Codex CLI: `0.149.0`
- Codex Desktop: `26.818.22352`
- macOS arm64

The marketplace snapshot matched the current upstream `main` revision when
reproduced.

## Expected behavior

The intended internal phase documents should remain readable from the parent
`azure-app-onboard` workflow without being reported as malformed skills by a
client that recursively discovers `SKILL.md` files.

## Possible resolutions

- Rename the internal phase documents (for example, `PHASE.md`) and update the
parent workflow links; or
- move them under a reference structure that Codex does not treat as separately
discoverable skills; or
- add an explicit packaging/discovery exclusion if the plugin format supports
one.

Adding normal skill frontmatter would suppress validation errors, but may make
the phase documents independently discoverable, which appears contrary to the
current self-contained `azure-app-onboard` design.

It would also be useful for packaging CI to test the recursively distributed
skill tree with Codex-compatible discovery rules.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.