docs: refine SKILL.md and references for package-first discovery

[xjacka]

• Prioritize package introspection over documentation for imports.
• Add -qq flag to pip installation commands for cleaner output.
• Include rules for polling secrets and trajectory yielding.
• Update Source-of-Truth precedence in SKILL.md.

Summary

Linked Issues

Documentation

• No Docs Needed:

If this PR adds new feature or changes existing. Make sure documentation is adjusted accordingly. If the docs is not needed, please explain why.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refines the guidelines for wrapping Python agents by establishing a 'package-first' approach for resolving import paths and types, prioritizing runtime introspection over documentation. It clarifies the roles of various information sources, ensuring that documentation focuses on architectural patterns and behavior while code introspection handles exact implementation details. The changes also introduce specific instructions for handling secrets and trajectory extensions, and improve the clarity of dependency installation commands.

Highlights

• Package-First Discovery for Imports: Revised documentation to establish runtime package introspection as the primary source of truth for discovering exact import paths, class names, and types, shifting priority away from static documentation for these details.
• New Guidelines for Secrets and Trajectories: Introduced explicit instructions for polling secrets when they are not immediately present and clarified that trajectory steps must be yielded, not emitted synchronously.
• Streamlined Dependency Installation: Updated pip install commands in the dependency reference to include the -qq flag for quieter, cleaner output during installation.
• Updated Source-of-Truth Precedence: Adjusted the hierarchy of information sources in SKILL.md to reflect the new package-first approach, placing installed package introspection at the highest priority for implementation details.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• skills/agentstack-wrapper/SKILL.md
  • Updated checklist items C6, C7, and C8 to reflect the new package-first source of truth for imports and the secondary role of documentation.
  • Added new checklist items C14 and C15 (now C20 and C21 due to renumbering) providing guidance on polling secrets and yielding trajectory steps.
  • Re-numbered existing checklist items from C9 to C22.
  • Modified the 'Source of Truth' precedence list to place installed package introspection as the absolute primary authority.
  • Removed the 'Every import resolves to a real, installed module' item from the 'Code Quality' checklist.
• skills/agentstack-wrapper/references/dependencies.md
  • Modified pip install commands to include the -qq flag for quiet output.
  • Revised the 'Source-of-truth rule' to explicitly state that installed package inspection is the absolute authority for imports, class names, and types.
  • Restructured and clarified the sections on 'Import Recovery Sequence' and 'Discovering Exact Import Paths', making inline package search the primary method for import discovery.
  • Removed the redundant a2a package search snippet.
• skills/agentstack-wrapper/references/llm-services.md
  • Updated the example for SecretsExtensionSpec.single_demand() to include the name="..." parameter for improved clarity.

Activity

• No specific activity (comments, reviews, etc.) was detected for this pull request.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request refines the SKILL.md and related reference documentation to emphasize a "package-first" approach for discovering import paths, class names, and types, shifting priority from documentation to direct package introspection. It updates the source-of-truth precedence rules, adds new anti-patterns for handling secrets and trajectory output, and incorporates the -qq flag for pip installation commands to ensure cleaner output. These changes align with the goal of streamlining the agent wrapping process by leveraging runtime introspection for accurate implementation details.

_{Note: Security Review has been skipped due to the limited scope of the PR.}

[kapetr]

This is quite a turn around to previous approach (that worked well for me, for Codex and Claude Opus at least), but let's put it to the test!