diff --git a/skills/console-rendering/SKILL.md b/.github/skills/console-rendering/SKILL.md similarity index 100% rename from skills/console-rendering/SKILL.md rename to .github/skills/console-rendering/SKILL.md diff --git a/skills/custom-agents/SKILL.md b/.github/skills/custom-agents/SKILL.md similarity index 98% rename from skills/custom-agents/SKILL.md rename to .github/skills/custom-agents/SKILL.md index 506aeb5e16f..552067e2efc 100644 --- a/skills/custom-agents/SKILL.md +++ b/.github/skills/custom-agents/SKILL.md @@ -1,13 +1,6 @@ --- name: custom-agents description: GitHub Custom Agent File Format -Brief description of agent's purpose -> # Multi-line description of agent's purpose -Repository-wide coding standards -Frontend development guidelines -Agent specializing in creating and improving README files -Specialized agent for writing comprehensive test suites -Agent specialized in performing code reviews --- diff --git a/skills/developer/SKILL.md b/.github/skills/developer/SKILL.md similarity index 100% rename from skills/developer/SKILL.md rename to .github/skills/developer/SKILL.md diff --git a/skills/error-messages/SKILL.md b/.github/skills/error-messages/SKILL.md similarity index 100% rename from skills/error-messages/SKILL.md rename to .github/skills/error-messages/SKILL.md diff --git a/skills/error-pattern-safety/SKILL.md b/.github/skills/error-pattern-safety/SKILL.md similarity index 100% rename from skills/error-pattern-safety/SKILL.md rename to .github/skills/error-pattern-safety/SKILL.md diff --git a/skills/error-recovery-patterns/SKILL.md b/.github/skills/error-recovery-patterns/SKILL.md similarity index 94% rename from skills/error-recovery-patterns/SKILL.md rename to .github/skills/error-recovery-patterns/SKILL.md index ad21b071ac9..2c4372b111e 100644 --- a/skills/error-recovery-patterns/SKILL.md +++ b/.github/skills/error-recovery-patterns/SKILL.md @@ -1,3 +1,7 @@ +--- +description: This skill provides comprehensive guidance on error handling patterns, recovery strategies, and debugging techniques in GitHub Agentic Workflows (gh-aw). +--- + # Error Recovery Patterns Skill This skill provides comprehensive guidance on error handling patterns, recovery strategies, and debugging techniques in GitHub Agentic Workflows (gh-aw). diff --git a/skills/gh-agent-session/SKILL.md b/.github/skills/gh-agent-session/SKILL.md similarity index 100% rename from skills/gh-agent-session/SKILL.md rename to .github/skills/gh-agent-session/SKILL.md diff --git a/skills/gh-agent-task/SKILL.md b/.github/skills/gh-agent-task/SKILL.md similarity index 100% rename from skills/gh-agent-task/SKILL.md rename to .github/skills/gh-agent-task/SKILL.md diff --git a/skills/github-copilot-agent-tips-and-tricks/SKILL.md b/.github/skills/github-copilot-agent-tips-and-tricks/SKILL.md similarity index 100% rename from skills/github-copilot-agent-tips-and-tricks/SKILL.md rename to .github/skills/github-copilot-agent-tips-and-tricks/SKILL.md diff --git a/skills/github-discussion-query/SKILL.md b/.github/skills/github-discussion-query/SKILL.md similarity index 100% rename from skills/github-discussion-query/SKILL.md rename to .github/skills/github-discussion-query/SKILL.md diff --git a/skills/github-discussion-query/query-discussions.py b/.github/skills/github-discussion-query/query-discussions.py similarity index 100% rename from skills/github-discussion-query/query-discussions.py rename to .github/skills/github-discussion-query/query-discussions.py diff --git a/skills/github-discussion-query/query-discussions.sh b/.github/skills/github-discussion-query/query-discussions.sh similarity index 100% rename from skills/github-discussion-query/query-discussions.sh rename to .github/skills/github-discussion-query/query-discussions.sh diff --git a/skills/github-issue-query/SKILL.md b/.github/skills/github-issue-query/SKILL.md similarity index 100% rename from skills/github-issue-query/SKILL.md rename to .github/skills/github-issue-query/SKILL.md diff --git a/skills/github-issue-query/query-issues.sh b/.github/skills/github-issue-query/query-issues.sh similarity index 100% rename from skills/github-issue-query/query-issues.sh rename to .github/skills/github-issue-query/query-issues.sh diff --git a/skills/github-mcp-server/SKILL.md b/.github/skills/github-mcp-server/SKILL.md similarity index 100% rename from skills/github-mcp-server/SKILL.md rename to .github/skills/github-mcp-server/SKILL.md diff --git a/skills/github-pr-query/SKILL.md b/.github/skills/github-pr-query/SKILL.md similarity index 100% rename from skills/github-pr-query/SKILL.md rename to .github/skills/github-pr-query/SKILL.md diff --git a/skills/github-pr-query/query-prs.sh b/.github/skills/github-pr-query/query-prs.sh similarity index 100% rename from skills/github-pr-query/query-prs.sh rename to .github/skills/github-pr-query/query-prs.sh diff --git a/skills/github-script/SKILL.md b/.github/skills/github-script/SKILL.md similarity index 100% rename from skills/github-script/SKILL.md rename to .github/skills/github-script/SKILL.md diff --git a/skills/http-mcp-headers/SKILL.md b/.github/skills/http-mcp-headers/SKILL.md similarity index 100% rename from skills/http-mcp-headers/SKILL.md rename to .github/skills/http-mcp-headers/SKILL.md diff --git a/skills/javascript-refactoring/SKILL.md b/.github/skills/javascript-refactoring/SKILL.md similarity index 100% rename from skills/javascript-refactoring/SKILL.md rename to .github/skills/javascript-refactoring/SKILL.md diff --git a/skills/messages/SKILL.md b/.github/skills/messages/SKILL.md similarity index 100% rename from skills/messages/SKILL.md rename to .github/skills/messages/SKILL.md diff --git a/skills/otel-queries/SKILL.md b/.github/skills/otel-queries/SKILL.md similarity index 100% rename from skills/otel-queries/SKILL.md rename to .github/skills/otel-queries/SKILL.md diff --git a/skills/reporting/SKILL.md b/.github/skills/reporting/SKILL.md similarity index 100% rename from skills/reporting/SKILL.md rename to .github/skills/reporting/SKILL.md diff --git a/skills/skillz-integration/SKILL.md b/.github/skills/skillz-integration/SKILL.md similarity index 98% rename from skills/skillz-integration/SKILL.md rename to .github/skills/skillz-integration/SKILL.md index 56b6aea3d5b..679a91e4052 100644 --- a/skills/skillz-integration/SKILL.md +++ b/.github/skills/skillz-integration/SKILL.md @@ -1,7 +1,5 @@ --- -name: skills description: Using Skillz MCP Server with Docker -Summarize documentation files --- diff --git a/skills/temporary-id-safe-output/SKILL.md b/.github/skills/temporary-id-safe-output/SKILL.md similarity index 100% rename from skills/temporary-id-safe-output/SKILL.md rename to .github/skills/temporary-id-safe-output/SKILL.md diff --git a/skills/documentation/SKILL.md b/skills/documentation/SKILL.md deleted file mode 100644 index 0f76a69e18b..00000000000 --- a/skills/documentation/SKILL.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -name: documentation -description: Documentation Brief description for SEO and navigation ---- - -### Documentation - -The documentation for this project is available in the `docs/` directory. It uses GitHub-flavored markdown with Astro Starlight for rendering and follows the Diátaxis framework for systematic documentation. - -## Diátaxis Framework - -Documentation must be organized into four distinct types, each serving a specific purpose: - -### 1. Tutorials (Learning-Oriented) -**Purpose**: Guide beginners through achieving a specific outcome to build confidence. - -- Start with what the user will build or achieve -- Provide a clear, step-by-step path from start to finish -- Include concrete examples and working code -- Assume minimal prior knowledge -- Focus on the happy path (avoid edge cases and alternatives) -- End with a working result the user can see and use -- Use imperative mood: "Create a file", "Run the command" - -**Avoid**: Explaining concepts in depth, multiple options, troubleshooting - -### 2. How-to Guides (Goal-Oriented) -**Purpose**: Show how to solve a specific real-world problem or accomplish a particular task. - -- Title format: "How to [accomplish specific goal]" -- Assume the user knows the basics -- Focus on practical steps to solve one problem -- Include necessary context but stay focused -- Show multiple approaches only when genuinely useful -- End when the goal is achieved -- Use imperative mood: "Configure the setting", "Add the following" - -**Avoid**: Teaching fundamentals, explaining every detail, being exhaustive - -### 3. Reference (Information-Oriented) -**Purpose**: Provide accurate, complete technical descriptions of the system. - -- Organized by structure (CLI commands, configuration options, API endpoints) -- Comprehensive and authoritative -- Consistent format across all entries -- Technical accuracy is paramount -- Include all parameters, options, and return values -- Use descriptive mood: "The command accepts", "Returns a string" -- Minimal narrative or explanation - -**Avoid**: Instructions, tutorials, opinions on usage - -### 4. Explanation (Understanding-Oriented) -**Purpose**: Clarify and illuminate topics to deepen understanding. - -- Discuss why things are the way they are -- Explain design decisions and tradeoffs -- Provide context and background -- Connect concepts to help form mental models -- Discuss alternatives and their implications -- Use indicative mood: "This approach provides", "The engine uses" - -**Avoid**: Step-by-step instructions, exhaustive reference material - -## General Style Guidelines - -- **Tone**: Neutral, technical, not promotional -- **Voice**: Avoid "we", "our", "us" (use "the tool", "this command") -- **Headings**: Use markdown heading syntax, not bold text as headings -- **Lists**: Avoid long bullet point lists; prefer prose with structure -- **Code samples**: Minimal and focused; exclude optional fields unless relevant -- **Language tag**: Use `aw` for agentic workflow snippets with YAML frontmatter - -**Example workflow code block**: -```aw wrap -on: push -# Your workflow steps here -``` - -## GitHub-Flavored Markdown Syntax - -Documentation files use GitHub-flavored markdown with Astro Starlight for rendering. Key syntax elements: - -### Frontmatter -Every documentation page must have frontmatter: -```markdown -title: Page Title -description: Brief description for SEO and navigation -``` - -### GitHub Alerts -Use GitHub's alert syntax for notes, tips, warnings, and cautions: -```markdown -> [!NOTE] -> Important information the reader should notice. - -> [!TIP] -> Helpful advice for the reader. - -> [!WARNING] -> Warning about potential issues or pitfalls. - -> [!CAUTION] -> Critical warning about dangerous operations. - -> [!IMPORTANT] -> Key information users need to know. -``` - -### Code Blocks -- Use syntax highlighting with language tags -- Add `title` attribute for file names: ` ```yaml title=".github/workflows/example.yml" ` -- Use `aw` language for agentic workflow files with YAML frontmatter -- Add `wrap` for line wrapping: ` ```aw wrap ` - -### Links -- Internal links: Use relative paths between documentation pages -- External links: Open in new tab automatically -- Link text: Use descriptive text, avoid "click here" - -### Tabs -Use tabs for showing alternatives (e.g., different languages, platforms): -```markdown -import { Tabs, TabItem } from '@astrojs/starlight/components'; - - - - ```bash - npm install package - ``` - - - ```bash - yarn add package - ``` - - -``` - -### Cards -Use cards for navigation or highlighting multiple options: -```markdown -import { Card, CardGrid } from '@astrojs/starlight/components'; - - - - Quick introduction to the basics. - - - Deep dive into advanced features. - - -``` - -**Remember**: Keep components minimal. Prefer standard markdown when possible. - -## Content to Avoid - -- "Key Features" sections -- Marketing language or selling points -- Excessive bullet points (prefer structured prose) -- Overly verbose examples with all optional parameters -- Mixing documentation types (e.g., tutorials that become reference) - -## Avoiding Documentation Bloat - -Documentation bloat reduces clarity and makes content harder to navigate. Common types of bloat include: - -### Types of Documentation Bloat - -1. **Duplicate content**: Same information repeated in different sections -2. **Excessive bullet points**: Long lists that could be condensed into prose or tables -3. **Redundant examples**: Multiple examples showing the same concept -4. **Verbose descriptions**: Overly wordy explanations that could be more concise -5. **Repetitive structure**: The same "What it does" / "Why it's valuable" pattern overused - -### Writing Concise Documentation - -When editing documentation, focus on: - -**Consolidate bullet points**: -- Convert long bullet lists into concise prose or tables -- Remove redundant points that say the same thing differently - -**Eliminate duplicates**: -- Remove repeated information -- Consolidate similar sections - -**Condense verbose text**: -- Make descriptions more direct and concise -- Remove filler words and phrases -- Keep technical accuracy while reducing word count - -**Standardize structure**: -- Reduce repetitive "What it does" / "Why it's valuable" patterns -- Use varied, natural language - -**Simplify code samples**: -- Remove unnecessary complexity from code examples -- Focus on demonstrating the core concept clearly -- Eliminate boilerplate or setup code unless essential for understanding -- Keep examples minimal yet complete -- Use realistic but simple scenarios - -### Example: Before and After - -**Before (Bloated)**: -```markdown -### Tool Name -Description of the tool. - -- **What it does**: This tool does X, Y, and Z -- **Why it's valuable**: It's valuable because A, B, and C -- **How to use**: You use it by doing steps 1, 2, 3, 4, 5 -- **When to use**: Use it when you need X -- **Benefits**: Gets you benefit A, benefit B, benefit C -- **Learn more**: [Link](url) -``` - -**After (Concise)**: -```markdown -### Tool Name -Description of the tool that does X, Y, and Z to achieve A, B, and C. - -Use it when you need X by following steps 1-5. [Learn more](url) -``` - -### Documentation Quality Guidelines - -1. **Preserve meaning**: Never lose important information -2. **Be surgical**: Make precise edits, don't rewrite everything -3. **Maintain tone**: Keep the neutral, technical tone -4. **Test locally**: Verify links and formatting are still correct - -## Structure by File Type - -- **Getting Started**: Tutorial format -- **How-to Guides**: Goal-oriented, one task per guide -- **CLI Reference**: Reference format, complete command documentation -- **Concepts**: Explanation format, building understanding -- **API Reference**: Reference format, complete API documentation