[BUG]: Built-in customize-opencode skill is outdated — missing tools field, MCP permission handling, and * catch-all #31982

Description

The built-in customize-opencode skill (embedded in the binary, registered in packages/core/src/plugin/skill.ts) contains several inaccuracies relative to the current JSON Schema (https://opencode.ai/config.json) and the Permissions docs (https://opencode.ai/docs/permissions).

Issues

1. tools field omitted from frontmatter documentation

The skill lists allowed frontmatter fields as:

name, model, variant, description, mode, hidden, color, steps, options, permission, disable, temperature, top_p

The JSON Schema (AgentConfig) includes a tools field:

"tools": {
  "type": "object",
  "additionalProperties": { "type": "boolean" },
  "description": "@deprecated Use 'permission' field instead"
}

The skill does not mention tools at all, and additionally claims:

Any unknown field is silently routed into options.

This is incorrect for tools — it IS a recognized (though deprecated) field and is not routed to options.

2. No documentation of MCP permission behavior

The skill's permission section lists known permission keys but does not explain how MCP tools interact with the permission system. Users attempting to restrict MCP tools per-agent via:

permission:
  mcp: deny

…will find it silently ineffective, because mcp is not a recognized permission key (confirmed in the Permissions docs: the available keys are read, edit, glob, grep, list, bash, task, skill, lsp, question, webfetch, websearch, external_directory, doom_loop).

The skill should clarify that MCP tools cannot be controlled via a mcp permission key, and document the working approach (e.g., "*": deny catch-all with specific allows).

3. "*" catch-all permission pattern not documented

The Permissions docs show:

{ "permission": { "*": "ask", "bash": "allow", "edit": "deny" } }

The "*" key at the top level of the permission object is a catch-all that matches any tool (including MCP tools). This is not mentioned in the skill, which makes it difficult for users to figure out how to create locked-down agents (e.g., read-only agents that also block all MCP tools).

Impact

Users following the skill's guidance will:

• Not know tools exists (even as deprecated)
• Assume permission.mcp: deny blocks MCP tools (it does not)
• Not discover the "*": deny pattern needed to actually lock down an agent

Suggested fix

Update the skill content in packages/core/src/plugin/skill.ts to:

1. Include tools in the frontmatter field list, marked as @deprecated
2. Correct the "silently routed into options" claim for known fields
3. Add a note that mcp is not a valid permission key and MCP tools are controlled via "*" catch-all or individual tool name patterns
4. Document the "*": deny permission pattern for locking down agents