diff --git a/.github/aw/context.md b/.github/aw/context.md index ae667e21701..26946cba8f3 100644 --- a/.github/aw/context.md +++ b/.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}} ``` diff --git a/.github/aw/experiments.md b/.github/aw/experiments.md index 9c18910f502..ab704f8e46e 100644 --- a/.github/aw/experiments.md +++ b/.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}} ``` diff --git a/.github/aw/skills.md b/.github/aw/skills.md index d62e7af9674..780493923dd 100644 --- a/.github/aw/skills.md +++ b/.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 - + 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. - + 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. 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 100% rename from skills/custom-agents/SKILL.md rename to .github/skills/custom-agents/SKILL.md 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 100% rename from skills/error-recovery-patterns/SKILL.md rename to .github/skills/error-recovery-patterns/SKILL.md 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 100% rename from skills/skillz-integration/SKILL.md rename to .github/skills/skillz-integration/SKILL.md 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/.github/workflows/shared/otel-queries.md b/.github/workflows/shared/otel-queries.md index 47740199b03..98daaba2b25 100644 --- a/.github/workflows/shared/otel-queries.md +++ b/.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. \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 9f893910885..3b337105439 100644 --- a/AGENTS.md +++ b/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 - **adding-new-engines** - 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6c115db0bb0..01b109c6476 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/DEVGUIDE.md b/DEVGUIDE.md index 34bb2402d5e..a7407c27d02 100644 --- a/DEVGUIDE.md +++ b/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 diff --git a/SKILL.md b/SKILL.md index 6c4f09e6609..8566766dcd4 100644 --- a/SKILL.md +++ b/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.) diff --git a/scratchpad/agent-sessions.md b/scratchpad/agent-sessions.md index 95be49655ba..8a8d4e4c3f9 100644 --- a/scratchpad/agent-sessions.md +++ b/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 diff --git a/scratchpad/cli-command-patterns.md b/scratchpad/cli-command-patterns.md index 3800728a2fe..cba1fa9d62a 100644 --- a/scratchpad/cli-command-patterns.md +++ b/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 diff --git a/scratchpad/error-recovery-patterns.md b/scratchpad/error-recovery-patterns.md index da0c655369f..c4beee9929e 100644 --- a/scratchpad/error-recovery-patterns.md +++ b/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 diff --git a/scratchpad/github-mcp-access-control-specification.md b/scratchpad/github-mcp-access-control-specification.md index 0183a9e85db..324ed7e37db 100644 --- a/scratchpad/github-mcp-access-control-specification.md +++ b/scratchpad/github-mcp-access-control-specification.md @@ -74,7 +74,7 @@ This specification does NOT cover: - MCP Gateway core protocol (see [MCP Gateway Specification](/gh-aw/reference/mcp-gateway/)) - MCP protocol semantics (see [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)) -- GitHub MCP server internal implementation (see [GitHub MCP Server Documentation](/gh-aw/skills/github-mcp-server/)) +- GitHub MCP server internal implementation (see [GitHub MCP Server Documentation](/gh-aw/.github/skills/github-mcp-server/)) - GitHub API authentication mechanisms - General GitHub Actions workflow syntax @@ -278,7 +278,7 @@ tools: ### 4.2 GitHub MCP Server Configuration Fields -This specification extends the GitHub MCP server configuration, which includes the following existing fields defined in the [GitHub MCP Server Documentation](/gh-aw/skills/github-mcp-server/): +This specification extends the GitHub MCP server configuration, which includes the following existing fields defined in the [GitHub MCP Server Documentation](/gh-aw/.github/skills/github-mcp-server/): #### 4.2.1 mode (Existing Feature) @@ -331,7 +331,7 @@ Both modes support read-only operation to restrict write operations: - **Remote mode**: Set via `X-MCP-Readonly: true` HTTP header - **Local mode**: Set via `GITHUB_READ_ONLY=1` environment variable -**See**: [GitHub MCP Server Documentation - Overview](/gh-aw/skills/github-mcp-server/#overview) for detailed mode descriptions. +**See**: [GitHub MCP Server Documentation - Overview](/gh-aw/.github/skills/github-mcp-server/#overview) for detailed mode descriptions. #### 4.2.2 toolsets (Existing Feature) @@ -355,7 +355,7 @@ toolsets: [repos, issues] # Specific toolsets only toolsets: [all] # All available toolsets ``` -**See**: [GitHub MCP Server Documentation - Available Toolsets](/gh-aw/skills/github-mcp-server/#available-toolsets) for complete toolset reference. +**See**: [GitHub MCP Server Documentation - Available Toolsets](/gh-aw/.github/skills/github-mcp-server/#available-toolsets) for complete toolset reference. #### 4.2.3 tools (Existing Feature) @@ -393,7 +393,7 @@ tools: **Note**: The `toolsets` approach is **strongly recommended** over individual `tools` configuration for new workflows. Tool names may change between GitHub MCP server versions, but toolsets provide a stable API. -**See**: [GitHub MCP Server Documentation - Migration from Allowed to Toolsets](/gh-aw/skills/github-mcp-server/#migration-from-allowed-to-toolsets) for migration guidance. +**See**: [GitHub MCP Server Documentation - Migration from Allowed to Toolsets](/gh-aw/.github/skills/github-mcp-server/#migration-from-allowed-to-toolsets) for migration guidance. #### 4.2.4 read-only (Existing Feature) @@ -2234,7 +2234,7 @@ tools: **Use Case**: Highly restricted documentation analysis agent with minimal tool access -**Note**: Using `toolsets` is recommended over individual `tools` for most workflows. See [GitHub MCP Server Documentation](/gh-aw/skills/github-mcp-server/) for details. +**Note**: Using `toolsets` is recommended over individual `tools` for most workflows. See [GitHub MCP Server Documentation](/gh-aw/.github/skills/github-mcp-server/) for details. #### A.8 Local Mode with Specific Version @@ -2262,7 +2262,7 @@ tools: - Uses `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable - Suitable for environments without internet access -**See**: [GitHub MCP Server Documentation - Remote vs Local Mode](/gh-aw/skills/github-mcp-server/#overview) for mode selection guidance. +**See**: [GitHub MCP Server Documentation - Remote vs Local Mode](/gh-aw/.github/skills/github-mcp-server/#overview) for mode selection guidance. #### A.9 Read-Only Mode with Access Control @@ -2624,7 +2624,7 @@ GitHub API rate limits apply to: - **[Safe Outputs Spec]** Safe Outputs System Specification, GitHub Agentic Workflows. [/gh-aw/scratchpad/safe-outputs-specification/](/gh-aw/scratchpad/safe-outputs-specification/) -- **[GitHub MCP Server]** GitHub MCP Server Documentation. [/gh-aw/skills/github-mcp-server/](/gh-aw/skills/github-mcp-server/) +- **[GitHub MCP Server]** GitHub MCP Server Documentation. [/gh-aw/.github/skills/github-mcp-server/](/gh-aw/.github/skills/github-mcp-server/) - **[GitHub Roles]** Repository roles for an organization, GitHub Docs. https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization 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 diff --git a/specs/aw-harness.md b/specs/aw-harness.md index f0b63917cb4..e6b082a7161 100644 --- a/specs/aw-harness.md +++ b/specs/aw-harness.md @@ -272,9 +272,9 @@ An `engine: aw` workflow document **MUST** include a YAML frontmatter block conf > > # All files and skills the agent may reference MUST be declared here. > # The compiler resolves each path and passes the contents to the harness. -> # Skills are files under skills/ and must be listed explicitly. +> # Skills are files under .github/skills/ and must be listed explicitly. > imports: -> - skills/reporting/SKILL.md # Skill: formatting guidelines for reports +> - .github/skills/reporting/SKILL.md # Skill: formatting guidelines for reports > - shared/review-criteria.md # Shared context: review checklist > > # gh-proxy and cli-proxy are ALWAYS enabled for engine: aw. @@ -405,7 +405,7 @@ The `imports:` key is **OPTIONAL**. It is a standard gh-aw frontmatter key that Each entry is a repository-relative path (string). Entries **MAY** point to: -- **Skill files** — files under `skills/` (e.g., `skills/reporting/SKILL.md`). +- **Skill files** — files under `.github/skills/` (e.g., `.github/skills/reporting/SKILL.md`). - **Shared context files** — markdown or text files shared across workflows (e.g., `shared/review-criteria.md`). - **Agent files** — custom agent `.yml` files (resolved and embedded by the compiler). @@ -415,8 +415,8 @@ A conforming implementation **MUST NOT** treat any skill, shared file, or agent > > ```yaml > imports: -> - skills/reporting/SKILL.md # Skill: formatting guidelines -> - skills/github-issue-query/SKILL.md # Skill: querying GitHub issues +> - .github/skills/reporting/SKILL.md # Skill: formatting guidelines +> - .github/skills/github-issue-query/SKILL.md # Skill: querying GitHub issues > - shared/review-criteria.md # Shared review checklist > ``` @@ -462,8 +462,8 @@ Skills **MUST** be treated as ordinary imported files: they carry no special run > ```yaml > # All skills and files must be declared explicitly. > imports: -> - skills/reporting/SKILL.md # Skill: formatting guidelines -> - skills/github-issue-query/SKILL.md # Skill: querying issues +> - .github/skills/reporting/SKILL.md # Skill: formatting guidelines +> - .github/skills/github-issue-query/SKILL.md # Skill: querying issues > - shared/pr-review-criteria.md # Shared context: review checklist > ``` @@ -731,7 +731,7 @@ The following five extensions **MUST** be loaded into the `AgentSession` created > > **Context provenance record:** > ```json -> {"timestamp":"2026-05-02T10:29:00.000Z","source":"import","path":"skills/reporting/SKILL.md","tokens":1240,"cumulative_tokens":1240,"role":"user"} +> {"timestamp":"2026-05-02T10:29:00.000Z","source":"import","path":".github/skills/reporting/SKILL.md","tokens":1240,"cumulative_tokens":1240,"role":"user"} > {"timestamp":"2026-05-02T10:29:00.001Z","source":"prompt","tokens":520,"cumulative_tokens":1760,"role":"user"} > ``` > @@ -748,7 +748,7 @@ The following five extensions **MUST** be loaded into the `AgentSession` created > ### Context Provenance > | Source | Path | Tokens | > |--------|------|--------| -> | import | skills/reporting/SKILL.md | 1,240 | +> | import | .github/skills/reporting/SKILL.md | 1,240 | > | prompt | _(prompt.txt)_ | 520 | > ``` >