`opencode agent create` uses wrong folder `.opencode/agent/` instead of `.opencode/agents/` (docs mismatch)

[d-oit]

Description

What happened?

The opencode agent create CLI command creates agent markdown files in .opencode/agent/ (singular), but the official documentation at https://opencode.ai/docs/agents/ specifies the correct path as .opencode/agents/ (plural).

This means agents created via the CLI are silently ignored at runtime because the loader reads from .opencode/agents/ (plural) and never finds the files placed in .opencode/agent/ (singular).

Steps to reproduce

1. Run opencode agent create in a project directory
2. Observe that the CLI creates the agent file under .opencode/agent/<name>.md
3. Open opencode — the agent does not appear in the agent list
4. Manually move the file to .opencode/agents/<name>.md
5. Open opencode again — the agent now appears correctly

Expected behavior

The opencode agent create command should create files in .opencode/agents/ (plural) to match:

• The official documentation: https://opencode.ai/docs/agents/
• The actual runtime loader path

Actual behavior

Files are created in .opencode/agent/ (singular), causing agents to be silently ignored. There is no error or warning to indicate the path mismatch.

Related

This is the same class of singular/plural path mismatch bug as the skills vs skill issue. The docs say agents/ (plural), the CLI writes to agent/ (singular).

Plugins

No response

OpenCode version

latest

Steps to reproduce

No response

Screenshot and/or share link

No response

Operating System

debian

Terminal

bash

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Inconsistency between docs and opencode agent create command #12302: Reports the same singular/plural path mismatch for opencode agent create writing to .opencode/agent/ (singular) instead of .opencode/agents/ (plural), including the docs inconsistency.

[kunzaatko]

 This means agents created via the CLI are silently ignored at runtime because the loader reads from .opencode/agents/ (plural) and never finds the files placed in .opencode/agent/ (singular).

This is a mismatch with the docs but both of the directories .opencode/agent/ and .opencode/agents/ are included for the agent resolution so this should not interfere with finding the agent at runtime.

opencode/packages/opencode/src/config/config.ts

Lines 422 to 459 in b9f6b40

	async function loadAgent(dir: string) {
	const result: Record<string, Agent> = {}
	for (const item of await Glob.scan("{agent,agents}/**/*.md", {
	cwd: dir,
	absolute: true,
	dot: true,
	symlink: true,
	})) {
	const md = await ConfigMarkdown.parse(item).catch(async (err) => {
	const message = ConfigMarkdown.FrontmatterError.isInstance(err)
	? err.data.message
	: `Failed to parse agent ${item}`
	const { Session } = await import("@/session")
	Bus.publish(Session.Event.Error, { error: new NamedError.Unknown({ message }).toObject() })
	log.error("failed to load agent", { agent: item, err })
	return undefined
	})
	if (!md) continue
	const patterns = ["/.opencode/agent/", "/.opencode/agents/", "/agent/", "/agents/"]
	const file = rel(item, patterns) ?? path.basename(item)
	const agentName = trim(file)
	const config = {
	name: agentName,
	...md.data,
	prompt: md.content.trim(),
	}
	const parsed = Agent.safeParse(config)
	if (parsed.success) {
	result[config.name] = parsed.data
	continue
	}
	throw new InvalidError({ path: item, issues: parsed.error.issues }, { cause: parsed.error })
	}
	return result
	}

There are two possibilities to solve this:

1. Update the documentation to include both of the directories
2. Use only the one that is included in the documentation (which would be a harsh breaking change)

I lean towards the first one. Should I PR (anyone from the maintainers?). Assign me 😉