fix: align SKILL.md with writing-skills quality standard

[CybotTM]

Summary

• Restructure SKILL.md to comply with writing-skills quality standard
• Move detailed verification guide, scripts documentation, AI tool compatibility, and output structure to references/
• Fix description to use "Use when..." format without workflow summary
• Reduce from ~2,500 words to <500 words

Addresses netresearch/claude-code-marketplace#32

[gemini-code-assist]

Summary of Changes

Hello @CybotTM, 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 refactors the AGENTS.md generator skill documentation to enhance its quality, conciseness, and utility for AI coding agents. By adhering to a new writing standard, the main documentation is now streamlined, with detailed guides and technical specifications modularized into separate reference files. This change aims to improve the efficiency with which AI agents can process and utilize the documentation, while also making it more manageable for human readers.

Highlights

• Documentation Restructuring: The primary AGENTS.md skill documentation has been significantly restructured to align with a 'writing-skills quality standard', improving clarity and conciseness.
• Content Modularization: Extensive, detailed sections such as verification guides, script documentation, AI tool compatibility, and output structure have been moved into dedicated reference files within a new 'references/' directory.
• Description Format Update: The skill's main description now uses a 'Use when...' format, removing a previous workflow summary for better focus.
• Reduced Document Length: The main SKILL.md file has been drastically reduced in length, from approximately 2,500 words to under 500 words, enhancing readability and agent efficiency.

Changelog

• skills/agents/SKILL.md
  • Restructured the entire document to comply with writing-skills quality standards.
  • Updated the skill description to a 'Use when...' format, removing the workflow summary.
  • Removed detailed sections on verification, scripts, AI tool compatibility, and output structure, relocating them to new reference files.
  • Significantly reduced the overall word count for improved conciseness.
• skills/agents/references/ai-tool-compatibility.md
  • Added a new reference document detailing how AGENTS.md integrates with various AI coding tools like Claude Code, OpenAI Codex, and GitHub Copilot.
• skills/agents/references/output-structure.md
  • Added a new reference document explaining the structure of generated AGENTS.md files, including root and scoped files, and guidelines for customization versus auto-generation.
• skills/agents/references/scripts-guide.md
  • Added a new reference document providing a comprehensive guide to all AGENTS.md generator scripts, including their options and usage.
• skills/agents/references/verification-guide.md
  • Added a new reference document outlining mandatory verification steps, critical considerations for name matching and command verification, and anti-patterns to avoid when working with AGENTS.md.

Activity

• No human activity (comments, reviews) has been recorded on this pull request yet.

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 significantly improves the structure and readability of the SKILL.md documentation by refactoring a very large file into a more concise overview and moving detailed information into separate files under the references/ directory. This is a great change for maintainability.

My review includes one suggestion for the main SKILL.md file to improve navigation by making file references in the 'References' table clickable links, and to address some references to files that do not appear to exist in the repository.