Skip to content

Codex project skill discovery ignores canonical .agents/skills path #1105

Description

@woxnapp

⚠ Agent-generated: This issue was drafted by an AI agent after reproducing the behavior against bb 0.35.1 and inspecting the current bb and OpenAI Codex sources. Please verify details before acting on them.

Summary

bb's Codex skill discovery scans .codex/skills for repository-local skills but does not scan the canonical .agents/skills locations used and documented by current Codex.

As a result, repository skills can be available to the Codex provider itself while remaining absent from bb's Skills catalog and composer skill autocomplete.

Environment

  • bb 0.35.1
  • Codex CLI 0.146.1
  • macOS / Apple Silicon

Reproduction

In a bb project backed by a repository containing project skills:

<repo>/.agents/skills/<skill-name>/SKILL.md

Confirm the files exist, then inspect bb's discovery surfaces:

find .agents/skills -maxdepth 2 -name SKILL.md
bb skill list --environment <environment-id> --json
bb project commands <project-id> --provider codex --environment <environment-id> --json

Actual behavior

  • Codex loads the repository skills and exposes them to the active provider session.
  • bb skill list returns no codex-project entries for those files.
  • bb project commands --provider codex omits the repository skills from composer autocomplete.

The current implementation adds only:

path.join(resolution.cwd, ".codex", "skills")

See:
https://github.com/get-bb/bb/blob/main/apps/host-daemon/src/command-handlers/list-commands.ts#L1102-L1110

The Skills management classifier likewise recognizes only project roots under .claude/skills or .codex/skills:
https://github.com/get-bb/bb/blob/main/apps/host-daemon/src/command-handlers/list-skills.ts

Expected behavior

For the Codex provider, bb should discover repository skills from the same canonical locations as Codex:

  • $CWD/.agents/skills
  • ancestor .agents/skills directories up to the repository root
  • $REPO_ROOT/.agents/skills

OpenAI's current skills documentation lists .agents/skills for repository skills and $HOME/.agents/skills for user skills:
https://learn.chatgpt.com/docs/build-skills

bb may continue scanning .codex/skills as a compatibility path, but it should not use that path instead of .agents/skills.

Suggested direction

  • Add Codex repository .agents/skills roots to resolveCommandScanRoots.
  • Classify those roots as provider-project in classifySkillRoot.
  • Mirror Codex's ancestor traversal from CWD to repository root, or obtain the authoritative list from Codex if a provider API is available.
  • Preserve de-duplication when the same skill is reachable through canonical and compatibility roots.
  • Add regression coverage for both host.list_commands and host.list_skills.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions