docs: add advanced per-agent configuration guide

[nucliweb]

Adds a draft reference doc consolidating the per-agent configuration discussion from #272 and #36.

The goal is a single place that documents how to keep shared SKILL.md files portable (spec frontmatter only) while applying the vendor-specific runtime controls each agent offers as an opt-in:

• Principles for where vendor fields belong (spec fields top-level, vendor metadata under metadata, runtime orchestration in per-agent adapter files).
• Claude Code: context: fork and allowed-tools in .claude/commands/.
• Gemini CLI / Antigravity: subagent definitions in .gemini/agents/*.md, model routing, tool restrictions, turn limits, plus Gemini 3.x thinking_level guidance.
• Automating with scripts: generating per-agent output from a single source of truth, with semantic validation.

The doc is explicitly marked as a draft, and the script-based automation is a proposal pending agreement before any implementation.

[addyosmani]

This is the right architecture, @nucliweb, and a cleaner answer than the inline approach in #272. Keeping SKILL.md portable (spec fields top-level, vendor config under metadata or in per-agent adapter files) is exactly how the shared skills should stay tool-agnostic. The generator idea is the part that makes it sustainable: a per-skill config map that emits the adapter files and leaves SKILL.md untouched, so we never hand-maintain vendor fields across 24+ skills.

Two things to take it out of draft:

1. Say explicitly that this supersedes the inline-frontmatter approach, so there's no ambiguity for contributors (or for feat: Add advanced Antigravity metadata to skills #272). As written, a reader could still think top-level model/temperature on a skill is fine.
2. The "prefer thinking_level over hardcoded temperature for 3.x models" guidance is a good catch. Worth a one-line example so it's copy-pasteable.

Once it graduates, I'd make this the canonical reference.

[nucliweb]

Addressed both points in 8b34e6f and took it out of draft:

• Supersedes the inline approach (explicit). Added a statement up front: this is the canonical reference, and kind/model/temperature/max_turns/tools/context must not appear at the top level of a skill, they belong under metadata or in a per-agent adapter file. No ambiguity for contributors.
• thinking_level example. Added a copy-pasteable .gemini/agents/*.md snippet using thinking_level: high with a # not: temperature: 0.1 note.
• Updated Status: feat: Add advanced Antigravity metadata to skills #272 and feat: add context: fork to all skills and commands #36 are now closed in favor of this doc.

Ready for review. Happy to co-write the generator follow-up whenever you want to take that on.

[nucliweb]

Pushed 7948a1a addressing review follow-ups and the four refinements from a fresh pass over the doc:

1. Consolidated feat: use content: fork in Claude Code slash commands for isolated skill execution #35. Added it to the Status list alongside feat: Add advanced Antigravity metadata to skills #272 and feat: add context: fork to all skills and commands #36 (now closed in favor of this doc), so no open issue on the fork topic is left unlinked.
2. Documented the agent field. context: fork now notes its optional agent companion that selects the subagent type (e.g. agent: Plan, default general-purpose).
3. Clarified the commands/skills framing. Since custom commands and skills share the same frontmatter, the doc now states context and allowed-tools work in both .claude/commands/*.md and .claude/skills/*/SKILL.md, and keeps the "shared SKILL.md stays spec-only" as a portability recommendation rather than a technical limit.
4. Linked the spec. First mention of the Agent Skills specification now points to agentskills.io, backing the normative "must not appear at the top level" claim.

Verified the context: fork/agent and allowed-tools fields against the current Claude Code docs before writing. Docs-only change, CI green. Ready for another look.

[nucliweb]

Hi @addyosmani @federicobartoli, could you take a look when you have a moment?

[addyosmani]

Good direction and well-written, but it commits us to an architecture I'm still deciding on, specifically whether per-agent config lives in the skill files or in adapter files. I don't want to publish the doc until that call is made, or we end up documenting one answer while an open PR argues the other. Let me settle the config-location question and this slots right in.