chore: consolidate skills under .github/skills

.github/aw/context.md

@@ -173,7 +173,7 @@ Tags may appear on their own line (block form) or inline. Block form (tag on its
 
 ```markdown
 {{#if experiments.skill_hint == "enabled" }}
-Check `skills/` for SKILL.md files relevant to this task and apply their guidance.
+Check `.github/skills/` for SKILL.md files relevant to this task and apply their guidance.
 {{#endif}}
 ```
 

.github/aw/experiments.md

@@ -203,7 +203,7 @@ experiments:
 
 ```markdown
 {{#if experiments.skill_hint == "enabled" }}
-Check `skills/` for SKILL.md files relevant to this task and apply their guidance.
+Check `.github/skills/` for SKILL.md files relevant to this task and apply their guidance.
 {{#endif}}
 ```
 

.github/aw/skills.md

@@ -4,7 +4,7 @@ description: Guide for leveraging skills (SKILL.md files) in agentic workflows 
 
 # Skills in Agentic Workflows
 
-Consult this file when you want a workflow to take advantage of skills — domain-specific knowledge files (`SKILL.md`) that live in the repository under `skills/` or `.github/skills/`.
+Consult this file when you want a workflow to take advantage of skills — domain-specific knowledge files (`SKILL.md`) that live in the repository under `.github/skills/`.
 
 ---
 
@@ -29,7 +29,7 @@ The workflow prompt hints that skills exist and asks the agent to discover and a
 **Pattern**:
 
 ```markdown
-If the repository contains `SKILL.md` files under `skills/`, check which ones are
+If the repository contains `SKILL.md` files under `.github/skills/`, check which ones are
 relevant to this task. For each relevant skill, read its content and apply the
 guidance it provides.
 ```
@@ -45,7 +45,7 @@ Extract and inline **only the specific sections** of the skill content that the
 **Pattern**:
 
 ```markdown
-<!-- gh-skill-fusion: skills/github-mcp-server/SKILL.md#authentication -->
+<!-- gh-skill-fusion: .github/skills/github-mcp-server/SKILL.md#authentication -->
 
 When calling GitHub MCP tools, use the pre-configured token already injected into the
 environment. Never prompt the user for credentials.
@@ -85,7 +85,7 @@ permissions:
 
 Triage the newly opened issue.
 
-If there are relevant skills under `skills/`, read them and apply their guidance.
+If there are relevant skills under `.github/skills/`, read them and apply their guidance.
 Focus on skills related to issue classification or project conventions.
 ```
 
@@ -108,7 +108,7 @@ permissions:
 
 Review the pull request for adherence to project conventions.
 
-<!-- Fused from skills/developer/SKILL.md#code-organization -->
+<!-- Fused from .github/skills/developer/SKILL.md#code-organization -->
 Prefer many smaller files grouped by functionality. Add new files for new features
 rather than extending existing ones. Keep validators under 300 lines; split when
 a single file covers more than one domain.

.github/workflows/shared/otel-queries.md

@@ -1,3 +1,3 @@
-Read `skills/otel-queries/SKILL.md` before starting telemetry analysis and use it as the default query playbook.
+Read `.github/skills/otel-queries/SKILL.md` before starting telemetry analysis and use it as the default query playbook.
 
 Prefer the cheapest trustworthy telemetry source first, run the skill's common query set, and only propose follow-on optimization after confirming one concrete bottleneck or observability gap.

AGENTS.md

@@ -12,7 +12,7 @@ GitHub Agentic Workflows is a Go-based GitHub CLI extension for writing agentic
 
 ## Important: Using Skills
 
-**BE LAZY**: Skills in `skills/` provide detailed, specialized knowledge about specific topics. **Only reference skills when you actually need their specialized knowledge**. Do not load or reference skills preemptively.
+**BE LAZY**: Skills in `.github/skills/` provide detailed, specialized knowledge about specific topics. **Only reference skills when you actually need their specialized knowledge**. Do not load or reference skills preemptively.
 
 **When to use skills:**
 - You encounter a specific technical challenge that requires specialized knowledge
@@ -24,7 +24,7 @@ GitHub Agentic Workflows is a Go-based GitHub CLI extension for writing agentic
 - When the information is already available in this AGENTS.md file
 - For simple, straightforward changes
 
-**Available Skills Directory**: `skills/`
+**Available Skills Directory**: `.github/skills/`
 
 Each skill provides focused guidance on specific topics. Reference them only as needed rather than loading everything upfront.
 
@@ -200,7 +200,7 @@ network:
 - **Guard `list_code_scanning_alerts` calls in workflow prompts**: always include `state: open` and `severity: critical,high` to avoid oversized MCP responses
 - **`head_limit` compatibility**: do **not** send `head_limit` to the default GitHub MCP tool; use `head_limit: 20` only with custom wrappers after verifying support in wrapper docs or wrapper-specific tests
 
-See [GitHub MCP Server Documentation](skills/github-mcp-server/SKILL.md) for complete configuration details.
+See [GitHub MCP Server Documentation](.github/skills/github-mcp-server/SKILL.md) for complete configuration details.
 
 ## Merging Main Branch
 
@@ -1096,7 +1096,7 @@ When modifying JSON schemas in `pkg/parser/schemas/`:
 The documentation for this project is available in the `docs/` directory. It includes information on how to use the CLI, API references, and examples.
 It uses the Diátaxis framework and GitHub-flavored markdown with Astro Starlight for rendering.
 
-See [documentation skill](skills/documentation/SKILL.md) for details.
+See [documentation skill](.github/skills/documentation/SKILL.md) for details.
 
 ### Legacy Support
 
@@ -1263,42 +1263,42 @@ For investigating and resolving workflow issues:
 Skills provide specialized, detailed knowledge on specific topics. **Use them only when needed** - don't load skills preemptively.
 
 ### Core Development Skills
-- **[developer](skills/developer/SKILL.md)** - Developer instructions, code organization, validation architecture, security practices
-- **[console-rendering](skills/console-rendering/SKILL.md)** - Struct tag-based console rendering system for CLI output
-- **[error-messages](skills/error-messages/SKILL.md)** - Error message style guide for validation errors
-- **[error-pattern-safety](skills/error-pattern-safety/SKILL.md)** - Safety guidelines for error pattern regex
-- **[error-recovery-patterns](skills/error-recovery-patterns/SKILL.md)** - Error handling patterns, recovery strategies, and debugging techniques
+- **[developer](.github/skills/developer/SKILL.md)** - Developer instructions, code organization, validation architecture, security practices
+- **[console-rendering](.github/skills/console-rendering/SKILL.md)** - Struct tag-based console rendering system for CLI output
+- **[error-messages](.github/skills/error-messages/SKILL.md)** - Error message style guide for validation errors
+- **[error-pattern-safety](.github/skills/error-pattern-safety/SKILL.md)** - Safety guidelines for error pattern regex
+- **[error-recovery-patterns](.github/skills/error-recovery-patterns/SKILL.md)** - Error handling patterns, recovery strategies, and debugging techniques
 
 ### JavaScript & GitHub Actions
-- **[github-script](skills/github-script/SKILL.md)** - Best practices for GitHub Actions scripts using github-script
-- **[javascript-refactoring](skills/javascript-refactoring/SKILL.md)** - Guide for refactoring JavaScript code into separate .cjs files
-- **[messages](skills/messages/SKILL.md)** - Adding new message types to safe-output messages system
+- **[github-script](.github/skills/github-script/SKILL.md)** - Best practices for GitHub Actions scripts using github-script
+- **[javascript-refactoring](.github/skills/javascript-refactoring/SKILL.md)** - Guide for refactoring JavaScript code into separate .cjs files
+- **[messages](.github/skills/messages/SKILL.md)** - Adding new message types to safe-output messages system
 
 ### GitHub Integration
-- **[github-mcp-server](skills/github-mcp-server/SKILL.md)** - GitHub MCP server documentation and configuration
-- **[github-issue-query](skills/github-issue-query/SKILL.md)** - Query GitHub issues with jq filtering
-- **[github-pr-query](skills/github-pr-query/SKILL.md)** - Query GitHub pull requests with jq filtering
-- **[github-discussion-query](skills/github-discussion-query/SKILL.md)** - Query GitHub discussions with jq filtering
-- **[github-copilot-agent-tips-and-tricks](skills/github-copilot-agent-tips-and-tricks/SKILL.md)** - Tips for working with GitHub Copilot coding agent PRs
+- **[github-mcp-server](.github/skills/github-mcp-server/SKILL.md)** - GitHub MCP server documentation and configuration
+- **[github-issue-query](.github/skills/github-issue-query/SKILL.md)** - Query GitHub issues with jq filtering
+- **[github-pr-query](.github/skills/github-pr-query/SKILL.md)** - Query GitHub pull requests with jq filtering
+- **[github-discussion-query](.github/skills/github-discussion-query/SKILL.md)** - Query GitHub discussions with jq filtering
+- **[github-copilot-agent-tips-and-tricks](.github/skills/github-copilot-agent-tips-and-tricks/SKILL.md)** - Tips for working with GitHub Copilot coding agent PRs
 
 ### AI Engine & Integration
-- **[copilot-cli](skills/copilot-cli/SKILL.md)** - GitHub Copilot CLI integration for agentic workflows
-- **[custom-agents](skills/custom-agents/SKILL.md)** - GitHub custom agent file format
-- **[gh-agent-session](skills/gh-agent-session/SKILL.md)** - GitHub CLI agent session extension
+- **[copilot-cli](.github/skills/copilot-cli/SKILL.md)** - GitHub Copilot CLI integration for agentic workflows
+- **[custom-agents](.github/skills/custom-agents/SKILL.md)** - GitHub custom agent file format
+- **[gh-agent-session](.github/skills/gh-agent-session/SKILL.md)** - GitHub CLI agent session extension
 - **<a>adding-new-engines</a>** - Comprehensive guide for adding new agentic engines (AI coding agents)
-- **[otel-queries](skills/otel-queries/SKILL.md)** - Fixed OTEL query loop for gh-aw spans: use local JSONL mirrors or live backends, answer telemetry questions efficiently, and only then drive follow-on optimization when needed
+- **[otel-queries](.github/skills/otel-queries/SKILL.md)** - Fixed OTEL query loop for gh-aw spans: use local JSONL mirrors or live backends, answer telemetry questions efficiently, and only then drive follow-on optimization when needed
 
 ### Safe Outputs & Features
-- **[temporary-id-safe-output](skills/temporary-id-safe-output/SKILL.md)** - Adding temporary ID support to safe output jobs
-- **[http-mcp-headers](skills/http-mcp-headers/SKILL.md)** - HTTP MCP header secret support implementation
+- **[temporary-id-safe-output](.github/skills/temporary-id-safe-output/SKILL.md)** - Adding temporary ID support to safe output jobs
+- **[http-mcp-headers](.github/skills/http-mcp-headers/SKILL.md)** - HTTP MCP header secret support implementation
 
 ### Documentation & Communication
-- **[documentation](skills/documentation/SKILL.md)** - Documentation guidelines using Diátaxis framework and GitHub-flavored markdown
-- **[reporting](skills/reporting/SKILL.md)** - Report format guidelines using HTML details/summary tags
+- **[documentation](.github/skills/documentation/SKILL.md)** - Documentation guidelines using Diátaxis framework and GitHub-flavored markdown
+- **[reporting](.github/skills/reporting/SKILL.md)** - Report format guidelines using HTML details/summary tags
 - **[dictation](DICTATION.md)** - Fixing text-to-speech errors in dictated text
 - **[agentic-chat](.github/aw/agentic-chat.md)** - AI assistant for creating task descriptions
 
 ### MCP & Tools
-- **[skillz-integration](skills/skillz-integration/SKILL.md)** - Skillz MCP server integration with Docker
+- **[skillz-integration](.github/skills/skillz-integration/SKILL.md)** - Skillz MCP server integration with Docker
 
 **Remember**: Be LAZY - only load a skill when you actually need its specialized knowledge. Don't reference skills preemptively.

CONTRIBUTING.md

@@ -145,7 +145,7 @@ All community contributions flow through **agentic plans in GitHub issues**. A c
 
 When a core team member implements your plan, the coding agent they use will:
 
-- **Read specifications** from `scratchpad/`, `skills/`, and `.github/instructions/`
+- **Read specifications** from `scratchpad/`, `.github/skills/`, and `.github/instructions/`
 - **Follow code organization patterns** (see [scratchpad/code-organization.md](scratchpad/code-organization.md))
 - **Implement validation** following the architecture in [scratchpad/validation-architecture.md](scratchpad/validation-architecture.md)
 - **Use console formatting** from `pkg/console` for CLI output
@@ -369,7 +369,7 @@ This structure is useful context when writing your agentic plan, so the core tea
 │   ├── parser/          # Markdown frontmatter parsing
 │   └── workflow/        # Workflow compilation and processing
 ├── scratchpad/               # Technical specifications the agent reads
-├── skills/              # Specialized knowledge for agents
+├── .github/skills/              # Specialized knowledge for agents
 ├── .github/             # Instructions and sample workflows
 │   ├── instructions/    # Agent instructions
 │   └── workflows/       # Sample workflows and CI

DEVGUIDE.md

@@ -773,8 +773,8 @@ See: **[scratchpad/cli-command-patterns.md](scratchpad/cli-command-patterns.md)*
 ### Related Guidelines
 
 - **Testing**: [scratchpad/testing.md](scratchpad/testing.md) - Comprehensive testing framework
-- **Console Output**: [skills/console-rendering/SKILL.md](skills/console-rendering/SKILL.md) - Output formatting
-- **Error Messages**: [skills/error-messages/SKILL.md](skills/error-messages/SKILL.md) - Error message style
+- **Console Output**: [.github/skills/console-rendering/SKILL.md](.github/skills/console-rendering/SKILL.md) - Output formatting
+- **Error Messages**: [.github/skills/error-messages/SKILL.md](.github/skills/error-messages/SKILL.md) - Error message style
 - **Code Organization**: [scratchpad/code-organization.md](scratchpad/code-organization.md) - File structure patterns
 
 ## Debugging and Troubleshooting

SKILL.md

@@ -36,4 +36,4 @@ gh aw audit 24814681146
 ## Where to learn more in this repo
 
 - `/AGENTS.md` for development/agent workflow conventions
-- `/skills/*/SKILL.md` for focused domain guidance (GitHub MCP, docs, errors, etc.)
+- `.github/skills/*/SKILL.md` for focused domain guidance (GitHub MCP, docs, errors, etc.)

scratchpad/agent-sessions.md

@@ -62,7 +62,7 @@ The terminology for starting an agent is changing from "New Agent Task" to "New
 - `pkg/parser/schemas/main_workflow_schema.json` - Main schema definition
 
 **Documentation Files**:
-- `skills/gh-agent-task/SKILL.md` - Skill documentation
+- `.github/skills/gh-agent-task/SKILL.md` - Skill documentation
 - `docs/src/content/docs/reference/safe-outputs.md` - Safe outputs reference
 - `docs/src/content/docs/reference/frontmatter-full.md` - Frontmatter reference
 - `docs/src/content/docs/reference/auth.md` - Token reference
@@ -193,7 +193,7 @@ Since the configuration key `create-agent-session` is changing to `create-agent-
 ### Phase 4: Documentation Migration
 
 1. **Update Skills**
-   - Rename `skills/gh-agent-task/` to `skills/gh-agent-session/`
+   - Rename `.github/skills/gh-agent-task/` to `.github/skills/gh-agent-session/`
    - Update SKILL.md content throughout
 
 2. **Update Reference Docs**
@@ -324,7 +324,7 @@ During transition period:
 
 ### Documentation Changes
 - [ ] Update Skills
-  - [ ] Rename directory: `skills/gh-agent-task/` → `skills/gh-agent-session/`
+  - [ ] Rename directory: `.github/skills/gh-agent-task/` → `.github/skills/gh-agent-session/`
   - [ ] Update `SKILL.md` content throughout
 
 - [ ] Update Reference Documentation

scratchpad/cli-command-patterns.md

@@ -1071,8 +1071,8 @@ Use this checklist when developing a new command:
 ## Related Documentation
 
 - **Testing Framework**: See `scratchpad/testing.md` for testing guidelines
-- **Console Rendering**: See `skills/console-rendering/SKILL.md` for console output details
-- **Error Messages**: See `skills/error-messages/SKILL.md` for error message style guide
+- **Console Rendering**: See `.github/skills/console-rendering/SKILL.md` for console output details
+- **Error Messages**: See `.github/skills/error-messages/SKILL.md` for error message style guide
 - **Code Organization**: See `scratchpad/code-organization.md` for file organization patterns
 - **Breaking Changes**: See `scratchpad/breaking-cli-rules.md` for breaking change guidelines
 

scratchpad/error-recovery-patterns.md

@@ -1128,7 +1128,7 @@ return fmt.Errorf(
 - Explain what's expected (format, valid values, type)
 - Provide concrete example of correct usage
 
-See `skills/error-messages/SKILL.md` for the style guide.
+See `.github/skills/error-messages/SKILL.md` for the style guide.
 
 ### Runtime Error Template