[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6AD4W0S6994TVD098NYAFK8":3,"skill-same:01M6AD4W0S6994TVD098NYAFK8":80},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":28,"publishedAt":45,"linkOnly":46,"markdownContent":47,"markdownBody":48,"frontMatter":49,"refName":50,"commitSha":51,"skillDirectory":52,"forksCount":53,"repositoryHtmlUrl":54,"repositoryHomepageUrl":55,"ownerHtmlUrl":56,"ownerBlogUrl":57,"ownerDescription":58,"updatedAt":59,"install":60,"resources":73},"01M6AD4W0S6994TVD098NYAFK8","developer-internals",null,"Internal gh-aw architecture: validation, pure session graders, safe output messages, schema validation, YAML compatibility, and MCP logs guardrail.","github\u002Fgh-aw","github","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F9919?v=4","01M6AC83DS133TPXFSP1DHNCC6","GitHub","01M6AD3VCZ4WKQSFSRTPN7N9DN",5636,"MIT","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fdeveloper-internals\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44],"developer internals","developer","MCP","safe","architecture","validation","yaml","logs","messages","gh","session","schema","compatibility","guardrail","output","schema validation","2026-11-10 10:12:30",false,"---\nname: developer-internals\ndescription: \"Internal gh-aw architecture: validation, pure session graders, safe output messages, schema validation, YAML compatibility, and MCP logs guardrail.\"\n---\n\n\n# gh-aw Internal Architecture\n\nUse this reference when working on the gh-aw compiler internals, validation system, session graders, safe output processing, or MCP server features.\n\n## Table of Contents\n\n- [Validation Architecture](#validation-architecture)\n- [Session Graders](#session-graders)\n- [Safe Output Messages](#safe-output-messages)\n- [Schema Validation](#schema-validation)\n- [YAML Compatibility](#yaml-compatibility)\n- [MCP Logs Guardrail](#mcp-logs-guardrail)\n\n## Validation Architecture\n\nThe validation system ensures workflow configurations are correct, secure, and compatible with GitHub Actions before compilation.\n\n### Architecture Overview\n\n```mermaid\ngraph LR\n    WF[Workflow] --> CV[Centralized Validation]\n    WF --> DV[Domain-Specific Validation]\n    CV --> validation.go\n    DV --> strict_mode_validation.go\n    DV --> strict_mode_permissions_validation.go\n    DV --> pip.go\n    DV --> npm.go\n    DV --> expression_safety_validation.go\n    DV --> engine.go\n    DV --> mcp-config.go\n```\n\n### Centralized Validation\n\n**Location:** `pkg\u002Fworkflow\u002Fvalidation.go` (core compile-time checks)\n\n**Purpose:** General-purpose validation that applies across the entire workflow system\n\n**Key Functions:**\n- `validateExpressionSizes()` - Ensures GitHub Actions expression size limits\n- `validateContainerImages()` - Verifies Docker images exist and are accessible\n- `validateRuntimePackages()` - Validates runtime package dependencies\n- `validateGitHubActionsSchema()` - Validates against GitHub Actions YAML schema\n- `validateNoDuplicateCacheIDs()` - Ensures unique cache identifiers\n- `validateSecretReferences()` - Validates secret reference syntax\n- `validateRepositoryFeatures()` - Checks repository capabilities\n- `validateHTTPTransportSupport()` - Validates HTTP transport configuration\n- `validateWorkflowRunBranches()` - Validates workflow run branch configuration\n\n**When to add validation here:**\n- Cross-cutting concerns that span multiple domains\n- Core workflow integrity checks\n- GitHub Actions compatibility validation\n- General schema and configuration validation\n- Repository-level feature detection\n\n### Domain-Specific Validation\n\nDomain-specific validation is organized into separate files in `pkg\u002Fworkflow\u002F`:\n\n#### Strict Mode Validation\n\n**Files:** `pkg\u002Fworkflow\u002Fstrict_mode_validation.go` and the `strict_mode_*.go` validators\n\nEnforces security and safety constraints in strict mode:\n- `validateStrictPermissions()` - Refuses write permissions\n- `validateStrictNetwork()` - Requires explicit network configuration\n- `validateStrictMCPNetwork()` - Requires network config on custom MCP servers\n- `validateStrictBashTools()` - Refuses bash wildcard tools\n\n#### Python Package Validation\n\n**File:** `pkg\u002Fworkflow\u002Fpip.go`\n\nValidates Python package availability on PyPI.\n\n#### NPM Package Validation\n\n**File:** `pkg\u002Fworkflow\u002Fnpm.go`\n\nValidates NPX package availability on npm registry.\n\n#### Expression Safety\n\n**File:** `pkg\u002Fworkflow\u002Fexpression_safety_validation.go`\n\nValidates GitHub Actions expression security with allowlist-based validation. The matching test coverage lives in `pkg\u002Fworkflow\u002Fexpression_safety_test.go`.\n\n### Validation Decision Tree\n\n```mermaid\ngraph TD\n    A[New Validation Requirement] --> B{Security or strict mode?}\n    B -->|Yes| C[strict_mode_validation.go]\n    B -->|No| D{Only applies to one domain?}\n    D -->|Yes| E{Domain-specific file exists?}\n    E -->|Yes| F[Add to domain file]\n    E -->|No| G[Create new domain file]\n    D -->|No| H{Cross-cutting concern?}\n    H -->|Yes| I[validation.go]\n    H -->|No| J{Validates external resources?}\n    J -->|Yes| K[Domain-specific file]\n    J -->|No| I\n```\n\n### Validation Patterns\n\n#### Allowlist Validation\n\nUsed for security-sensitive validation with limited set of valid options:\n\n```go\nfunc validateExpressionSafety(content string) error {\n    matches := expressionRegex.FindAllStringSubmatch(content, -1)\n    var unauthorizedExpressions []string\n\n    for _, match := range matches {\n        expression := strings.TrimSpace(match[1])\n        if !isAllowed(expression) {\n            unauthorizedExpressions = append(unauthorizedExpressions, expression)\n        }\n    }\n\n    if len(unauthorizedExpressions) > 0 {\n        return fmt.Errorf(\"unauthorized expressions: %v\", unauthorizedExpressions)\n    }\n    return nil\n}\n```\n\n#### External Resource Validation\n\nUsed for validating external dependencies:\n\n```go\nfunc validateDockerImage(image string, verbose bool) error {\n    cmd := exec.Command(\"docker\", \"inspect\", image)\n    output, err := cmd.CombinedOutput()\n\n    if err != nil {\n        pullCmd := exec.Command(\"docker\", \"pull\", image)\n        if pullErr := pullCmd.Run(); pullErr != nil {\n            return fmt.Errorf(\"docker image not found: %s\", image)\n        }\n    }\n    return nil\n}\n```\n\n#### Schema Validation\n\nUsed for configuration file validation:\n\n```go\nfunc (c *Compiler) validateGitHubActionsSchema(yamlContent string) error {\n    schema := loadGitHubActionsSchema()\n\n    var data interface{}\n    if err := yaml.Unmarshal([]byte(yamlContent), &data); err != nil {\n        return err\n    }\n\n    if err := schema.Validate(data); err != nil {\n        return fmt.Errorf(\"schema validation failed: %w\", err)\n    }\n    return nil\n}\n```\n\n#### Progressive Validation\n\nUsed for applying multiple validation checks in sequence:\n\n```go\nfunc (c *Compiler) validateStrictMode(frontmatter map[string]any, networkPermissions *NetworkPermissions) error {\n    if !c.strictMode {\n        return nil\n    }\n\n    if err := c.validateStrictPermissions(frontmatter); err != nil {\n        return err\n    }\n\n    if err := c.validateStrictNetwork(networkPermissions); err != nil {\n        return err\n    }\n\n    return nil\n}\n```\n\n\n\n## Session Graders\n\nBuilt-ins implement `computeGraders(session, graders = [])` over a redacted\nin-memory unified-session array. Reuse `createSessionLookups(session)` from\n`actions\u002Fsetup\u002Fjs\u002Fgrader_session.cjs` for statistics, typed event lookups,\ncorrelated tool calls, scoped call indexes, and trajectory projections.\nKeep file I\u002FO at the collection\u002Freplay boundary, never inside graders.\nTen fast built-ins are enabled by default; expensive analyses require opt-in.\n\nCustom syntax is `graders.\u003Cdistinct-id>.script`, a synchronous JavaScript body\nreceiving immutable `session`, `config`, and `helpers` snapshots. Return a\nfinite number, `null`, or an object with `value`. The compiler partitions custom\nsource into a restricted downstream `graders` job; conclusion receives only\ncustom IDs. Never import or execute user code in conclusion, permit its step\nhooks, or allow `jobs.graders` customization. Repository-owned\n`graders.operational-value.run` Bash also runs only in that separate job: freeze\nthe confined `.sh` source at compilation, pass session JSONL as `$1` \u002F\n`GH_AW_SESSION_FILE` and config JSON as `GH_AW_GRADER_CONFIG`, and preserve legacy\nmetric-array output. Compilation and `grader-shell-file-write` share the Bash AST\nwrite checker. Shell has bounded execution and a stripped environment but is not\na filesystem\u002Fnetwork sandbox or microVM yet. Built-in overrides remain rejected.\n\nThe separate job consumes `usage\u002Faw_session.jsonl` and publishes combined results\nin the `graders` artifact without source. Preserve conclusion's published session.\nAudit conditionally fetches registered custom results; the logs `graders`\nartifact set includes `usage`, `graders`, and historical transports. Keep compiler,\nruntime, schema, replay, artifact maps, and these consumers consistent.\nSee [operational-value-designer](..\u002Foperational-value-designer\u002FSKILL.md) for\ncurrent authoring syntax and evidence design.\n\n## Safe Output Messages\n\nSafe output functions handle GitHub API write operations (creating issues, discussions, comments, PRs) from AI-generated content with consistent messaging patterns.\n\n### Recorded execution outcomes\n\nCustom safe jobs can map `outputs.status` and `outputs.url` to step outputs.\nConclusion identifies configured safe jobs explicitly and reads their outputs\nfrom `needs`, not from agent requests. It records `safe_output.result` events\nwith the normalized job name, status, and optional canonical absolute resource\nURI in `data.url`. A failed, cancelled, or skipped job cannot report success.\nOn a successful job, an explicit status can distinguish an intentional skip or\napplication-level failure; absent status falls back to the Actions job result.\nPrepared work-queue adapters are not verified effects and must not be promoted\nto successful safe-job outcomes.\n\nSafe scripts return execution results through the handler contract:\n`success: true` with `url` identifies the canonical resource returned by the\nservice. The safe-output manifest preserves execution status for conclusion's\nunified session collector. Keep artifact redaction before serialization and\npreserve staged\u002Fdeferred suppression. Never infer a generated resource URI\nfrom an agent-supplied request or copy arbitrary handler outputs into the session.\n\n### Safe Output Message Flow\n\nThe following diagram illustrates how AI-generated content flows through the safe output system to GitHub API operations:\n\n```mermaid\ngraph TD\n    A[AI Agent Output] --> B{Staged Mode?}\n    B -->|Yes| C[Generate Preview Messages]\n    B -->|No| D[Process Safe Output]\n    C --> E[Show ? Staged Mode Preview]\n    E --> F[Display in Step Summary]\n    D --> G{Safe Output Type}\n    G -->|create-issue| H[Create GitHub Issue]\n    G -->|create-discussion| I[Create GitHub Discussion]\n    G -->|add-comment| J[Add GitHub Comment]\n    G -->|create-pull-request| K[Create Pull Request]\n    G -->|create-pr-review-comment| L[Create PR Review Comment]\n    G -->|update-issue| M[Update GitHub Issue]\n    H --> N[Apply Message Patterns]\n    I --> N\n    J --> N\n    K --> N\n    L --> N\n    M --> N\n    N --> O[Add AI Attribution Footer]\n    N --> P[Add Installation Instructions]\n    N --> Q[Add Related Items Links]\n    N --> R[Add Patch Preview]\n    O --> S[Execute GitHub API Operation]\n    P --> S\n    Q --> S\n    R --> S\n    S --> T[Generate Success Summary]\n    T --> U[Display in Step Summary]\n```\n\n**Flow Stages:**\n1. **AI Agent Output** - AI generates content for GitHub operations\n2. **Staged Mode Check** - Determines if operation is in preview mode\n3. **Safe Output Processing** - Routes to appropriate GitHub operation type\n4. **Message Pattern Application** - Applies consistent formatting (footers, instructions, links)\n5. **GitHub API Execution** - Performs the actual GitHub operation\n6. **Success Summary** - Reports results in workflow step summary\n\n### Message Categories\n\n#### AI Attribution Footer\n\nIdentifies content as AI-generated and links to workflow run:\n\n```markdown\n> AI generated by [WorkflowName](run_url)\n```\n\nWith triggering context:\n```markdown\n> AI generated by [WorkflowName](run_url) for #123\n```\n\n#### Workflow Installation Instructions\n\n```markdown\n>\n> To add this workflow in your repository, run `gh aw add owner\u002Frepo\u002Fpath@ref`. See [usage guide](https:\u002F\u002Fgithub.github.com\u002Fgh-aw\u002Fsetup\u002Fcli\u002F).\n```\n\n#### Staged Mode Preview\n\nAll staged mode previews use consistent format with ? emoji:\n\n```markdown\n## ? Staged Mode: [Operation Type] Preview\n\nThe following [items] would be [action] if staged mode was disabled:\n```\n\n#### Patch Preview\n\nDisplay git patches in pull request bodies with size limits:\n\n```markdown\n\u003Cdetails>\u003Csummary>Show patch (45 lines)\u003C\u002Fsummary>\n\n\\`\\`\\`diff\ndiff --git a\u002Fsrc\u002Fauth.js b\u002Fsrc\u002Fauth.js\nindex 1234567..abcdefg 100644\n--- a\u002Fsrc\u002Fauth.js\n+++ b\u002Fsrc\u002Fauth.js\n@@ -10,7 +10,10 @@ export async function login(username, password) {\n-    throw new Error('Login failed');\n+    if (response.status === 401) {\n+      throw new Error('Invalid credentials');\n+    }\n+    throw new Error('Login error: ' + response.statusText);\n\\`\\`\\`\n\n\u003C\u002Fdetails>\n```\n\nLimits: Max 500 lines or 2000 characters (truncated with \"... (truncated)\" if exceeded)\n\n### Design Principles\n\n#### Consistency\n- All AI-generated content uses same blockquote footer format\n- ? emoji consistently marks staged preview mode\n- URL patterns match GitHub conventions\n- Step summaries follow same heading and list structure\n\n#### Clarity\n- Clear distinction between preview and actual operations\n- Explicit error messages with actionable guidance\n- Helpful fallback instructions when operations fail\n- Field labels consistently use bold text\n\n#### Discoverability\n- Installation instructions included in footers when available\n- Related items automatically linked across workflow outputs\n- Step summaries provide quick access to created items\n- Collapsible sections keep large content manageable\n\n#### Safety\n- Labels sanitized to prevent unintended @mentions\n- Patch sizes validated and truncated when needed\n- Staged mode allows testing without side effects\n- Graceful fallbacks when primary operations fail\n\n\n\n## Schema Validation\n\nAll three JSON schema files enforce strict validation with `\"additionalProperties\": false` at the root level, preventing typos and undefined fields from silently passing validation.\n\n### Schema Files\n\n| File | Purpose |\n|------|---------|\n| `pkg\u002Fparser\u002Fschemas\u002Fmain_workflow_schema.json` | Validates agentic workflow frontmatter in `.github\u002Fworkflows\u002F*.md` files |\n| `pkg\u002Fparser\u002Fschemas\u002Fmcp_config_schema.json` | Validates MCP (Model Context Protocol) server configuration |\n\n### How It Works\n\nWhen `\"additionalProperties\": false` is set at the root level, the validator rejects any properties not explicitly defined in the schema's `properties` section. This catches common typos:\n\n- `permisions` instead of `permissions`\n- `engnie` instead of `engine`\n- `toolz` instead of `tools`\n- `timeout_minute` instead of `timeout-minutes`\n- `runs_on` instead of `runs-on`\n- `safe_outputs` instead of `safe-outputs`\n\n### Example Validation Error\n\n```bash\n$ gh aw compile workflow-with-typo.md\n✗ error: Unknown properties: toolz, engnie, permisions. Valid fields are: tools, engine, permissions, ...\n```\n\n### Validation Process\n\n```mermaid\ngraph LR\n    A[Read workflow frontmatter] --> B[Parse YAML]\n    B --> C[Validate against JSON schema]\n    C --> D{Valid?}\n    D -->|Yes| E[Continue compilation]\n    D -->|No| F[Provide detailed error]\n    F --> G[Show invalid fields]\n    F --> H[Show valid field names]\n```\n\n### Schema Embedded in Binary\n\nSchemas are embedded in the Go binary using `\u002F\u002Fgo:embed` directives:\n\n```go\n\u002F\u002Fgo:embed schemas\u002Fmain_workflow_schema.json\nvar mainWorkflowSchema string\n```\n\nThis means:\n- Schema changes require running `make build` to take effect\n- Schemas are validated at runtime, not at build time\n- No external JSON files need to be distributed with the binary\n\n### Adding New Fields\n\nWhen adding new fields to schemas:\n\n1. Update the schema JSON file with the new property definition\n2. Rebuild the binary with `make build`\n3. Add test cases to verify the new field works\n4. Update documentation if the field is user-facing\n\n\n\n## YAML Compatibility\n\nYAML has two major versions with incompatible boolean parsing behavior that affects workflow validation.\n\n### The Core Issue\n\n#### YAML 1.1 Boolean Parsing Problem\n\nIn YAML 1.1, certain plain strings are automatically converted to boolean values. The workflow trigger key `on:` can be misinterpreted as boolean `true` instead of string `\"on\"`.\n\n**Example:**\n```python\n# Python yaml.safe_load (YAML 1.1 parser)\nimport yaml\n\ncontent = \"\"\"\non:\n  issues:\n    types: [opened]\n\"\"\"\n\nresult = yaml.safe_load(content)\nprint(result)\n# Output: {True: {'issues': {'types': ['opened']}}}\n#          ^^^^ The key is boolean True, not string \"on\"!\n```\n\nThis creates false positives when validating workflows with Python-based tools.\n\n#### YAML 1.2 Correct Behavior\n\nYAML 1.2 parsers treat `on`, `off`, `yes`, and `no` as regular strings, not booleans. Only explicit boolean literals `true` and `false` are treated as booleans.\n\n**Example:**\n```go\n\u002F\u002F Go goccy\u002Fgo-yaml (YAML 1.2 parser) - Used by gh-aw\nvar result map[string]interface{}\nyaml.Unmarshal([]byte(content), &result)\n\nfmt.Printf(\"%+v\\n\", result)\n\u002F\u002F Output: map[on:map[issues:map[types:[opened]]]]\n\u002F\u002F         ^^^ The key is string \"on\" ✓\n```\n\n### How gh-aw Handles This\n\nGitHub Agentic Workflows uses **`goccy\u002Fgo-yaml` v1.18.0**, which is a **YAML 1.2 compliant parser**:\n\n- ✅ `on:` is correctly parsed as a string key, not a boolean\n- ✅ Workflow frontmatter validation works correctly\n- ✅ GitHub Actions YAML is compatible (GitHub Actions also uses YAML 1.2 parsing)\n\n### Compatibility Flow\n\n```mermaid\ngraph TD\n    A[Workflow File] --> B{Parser Type?}\n    B -->|YAML 1.1| C[Python yaml.safe_load]\n    B -->|YAML 1.2| D[gh-aw \u002F goccy\u002Fgo-yaml]\n    C --> E[on: parsed as True]\n    D --> F[on: parsed as string]\n    E --> G[False Positive]\n    F --> H[Correct Validation]\n```\n\n### Affected Keywords\n\nYAML 1.1 treats these as booleans (parsed as `true` or `false`):\n\n**Parsed as `true`:** on, yes, y, Y, YES, Yes, ON, On\n**Parsed as `false`:** off, no, n, N, NO, No, OFF, Off\n\nYAML 1.2 treats all of the above as strings. Only these are booleans: `true`, `false`\n\n### Recommendations\n\n#### For Workflow Authors\n\n1. **Use gh-aw's compiler for validation:**\n   ```bash\n   gh aw compile workflow.md\n   ```\n\n2. **Don't trust Python yaml.safe_load for validation** - it will give false positives for the `on:` trigger key.\n\n3. **Use explicit booleans when you mean boolean values:**\n   ```yaml\n   enabled: true      # Explicit boolean\n   disabled: false    # Explicit boolean\n\n   # Avoid for boolean values:\n   enabled: yes       # Might be confusing across parsers\n   disabled: no       # Might be confusing across parsers\n   ```\n\n#### For Tool Developers\n\n1. **Use YAML 1.2 parsers for gh-aw integration:**\n   - Go: `github.com\u002Fgoccy\u002Fgo-yaml`\n   - Python: `ruamel.yaml` (with YAML 1.2 mode)\n   - JavaScript: `yaml` package v2+ (YAML 1.2 by default)\n   - Ruby: `Psych` (YAML 1.2 by default in Ruby 2.6+)\n\n2. **Document parser version in your tool**\n\n3. **Consider adding compatibility mode** to switch between YAML 1.1 and 1.2 parsing\n\n\n\n## MCP Logs Guardrail\n\nThe MCP server `logs` command includes an automatic guardrail to prevent overwhelming responses when fetching workflow logs.\n\n### How It Works\n\n```mermaid\ngraph TD\n    A[logs command called] --> B[Generate output]\n    B --> C{Output size check}\n    C -->|≤ 12000 tokens| D[Return full JSON data]\n    C -->|> 12000 tokens| E[Return guardrail message]\n    E --> F[Include schema description]\n    E --> G[Provide suggested jq queries]\n```\n\n### Normal Operation (Output ≤ Token Limit)\n\nWhen output is within the token limit (default: 12000 tokens), the command returns full JSON data:\n\n```json\n{\n  \"summary\": {\n    \"total_runs\": 5,\n    \"total_duration\": \"2h30m\",\n    \"total_tokens\": 45000,\n    \"total_cost\": 0.23\n  },\n  \"runs\": [...],\n  \"tool_usage\": [...]\n}\n```\n\n### Guardrail Triggered (Output > Token Limit)\n\nWhen output exceeds the token limit, the command returns structured response with:\n\n```json\n{\n  \"message\": \"⚠️  Output size (15000 tokens) exceeds the limit (12000 tokens). To reduce output size, use the 'jq' parameter with one of the suggested queries below.\",\n  \"output_tokens\": 15000,\n  \"output_size_limit\": 12000,\n  \"schema\": { ... },\n  \"suggested_queries\": [\n    {\n      \"description\": \"Get only the summary statistics\",\n      \"query\": \".summary\",\n      \"example\": \"Use jq parameter: \\\".summary\\\"\"\n    },\n    ...\n  ]\n}\n```\n\n### Configuring the Token Limit\n\nDefault limit is 12000 tokens (approximately 48KB of text). Customize using the `max_tokens` parameter:\n\n```json\n{\n  \"name\": \"logs\",\n  \"arguments\": {\n    \"count\": 100,\n    \"max_tokens\": 20000\n  }\n}\n```\n\nToken estimation uses approximately 4 characters per token (OpenAI's rule of thumb).\n\n### Using the jq Parameter\n\nFilter output using jq syntax:\n\n**Get only summary statistics:**\n```json\n{ \"jq\": \".summary\" }\n```\n\n**Get run IDs and basic info:**\n```json\n{ \"jq\": \".runs | map({database_id, workflow_name, status})\" }\n```\n\n**Get only failed runs:**\n```json\n{ \"jq\": \".runs | map(select(.conclusion == \\\"failure\\\"))\" }\n```\n\n**Get high token usage runs:**\n```json\n{ \"jq\": \".runs | map(select(.token_usage > 10000))\" }\n```\n\n### Implementation Details\n\n**Constants:**\n- `DefaultMaxMCPLogsOutputTokens`: 12000 tokens (default limit)\n- `CharsPerToken`: 4 characters per token (estimation factor)\n\n**Files:**\n- `pkg\u002Fcli\u002Fmcp_logs_guardrail.go` - Core guardrail implementation\n- `pkg\u002Fcli\u002Fmcp_logs_guardrail_test.go` - Unit tests\n- `pkg\u002Fcli\u002Fmcp_logs_guardrail_integration_test.go` - Integration tests\n- `pkg\u002Fcli\u002Fmcp_server.go` - Integration with MCP server\n\n### Benefits\n\n1. Prevents overwhelming responses for AI models\n2. Provides guidance with specific filters\n3. Self-documenting with schema description\n4. Preserves functionality with jq filtering\n5. Transparent messaging about why guardrail triggered\n","# gh-aw Internal Architecture\n\nUse this reference when working on the gh-aw compiler internals, validation system, session graders, safe output processing, or MCP server features.\n\n## Table of Contents\n\n- [Validation Architecture](#validation-architecture)\n- [Session Graders](#session-graders)\n- [Safe Output Messages](#safe-output-messages)\n- [Schema Validation](#schema-validation)\n- [YAML Compatibility](#yaml-compatibility)\n- [MCP Logs Guardrail](#mcp-logs-guardrail)\n\n## Validation Architecture\n\nThe validation system ensures workflow configurations are correct, secure, and compatible with GitHub Actions before compilation.\n\n### Architecture Overview\n\n```mermaid\ngraph LR\n    WF[Workflow] --> CV[Centralized Validation]\n    WF --> DV[Domain-Specific Validation]\n    CV --> validation.go\n    DV --> strict_mode_validation.go\n    DV --> strict_mode_permissions_validation.go\n    DV --> pip.go\n    DV --> npm.go\n    DV --> expression_safety_validation.go\n    DV --> engine.go\n    DV --> mcp-config.go\n```\n\n### Centralized Validation\n\n**Location:** `pkg\u002Fworkflow\u002Fvalidation.go` (core compile-time checks)\n\n**Purpose:** General-purpose validation that applies across the entire workflow system\n\n**Key Functions:**\n- `validateExpressionSizes()` - Ensures GitHub Actions expression size limits\n- `validateContainerImages()` - Verifies Docker images exist and are accessible\n- `validateRuntimePackages()` - Validates runtime package dependencies\n- `validateGitHubActionsSchema()` - Validates against GitHub Actions YAML schema\n- `validateNoDuplicateCacheIDs()` - Ensures unique cache identifiers\n- `validateSecretReferences()` - Validates secret reference syntax\n- `validateRepositoryFeatures()` - Checks repository capabilities\n- `validateHTTPTransportSupport()` - Validates HTTP transport configuration\n- `validateWorkflowRunBranches()` - Validates workflow run branch configuration\n\n**When to add validation here:**\n- Cross-cutting concerns that span multiple domains\n- Core workflow integrity checks\n- GitHub Actions compatibility validation\n- General schema and configuration validation\n- Repository-level feature detection\n\n### Domain-Specific Validation\n\nDomain-specific validation is organized into separate files in `pkg\u002Fworkflow\u002F`:\n\n#### Strict Mode Validation\n\n**Files:** `pkg\u002Fworkflow\u002Fstrict_mode_validation.go` and the `strict_mode_*.go` validators\n\nEnforces security and safety constraints in strict mode:\n- `validateStrictPermissions()` - Refuses write permissions\n- `validateStrictNetwork()` - Requires explicit network configuration\n- `validateStrictMCPNetwork()` - Requires network config on custom MCP servers\n- `validateStrictBashTools()` - Refuses bash wildcard tools\n\n#### Python Package Validation\n\n**File:** `pkg\u002Fworkflow\u002Fpip.go`\n\nValidates Python package availability on PyPI.\n\n#### NPM Package Validation\n\n**File:** `pkg\u002Fworkflow\u002Fnpm.go`\n\nValidates NPX package availability on npm registry.\n\n#### Expression Safety\n\n**File:** `pkg\u002Fworkflow\u002Fexpression_safety_validation.go`\n\nValidates GitHub Actions expression security with allowlist-based validation. The matching test coverage lives in `pkg\u002Fworkflow\u002Fexpression_safety_test.go`.\n\n### Validation Decision Tree\n\n```mermaid\ngraph TD\n    A[New Validation Requirement] --> B{Security or strict mode?}\n    B -->|Yes| C[strict_mode_validation.go]\n    B -->|No| D{Only applies to one domain?}\n    D -->|Yes| E{Domain-specific file exists?}\n    E -->|Yes| F[Add to domain file]\n    E -->|No| G[Create new domain file]\n    D -->|No| H{Cross-cutting concern?}\n    H -->|Yes| I[validation.go]\n    H -->|No| J{Validates external resources?}\n    J -->|Yes| K[Domain-specific file]\n    J -->|No| I\n```\n\n### Validation Patterns\n\n#### Allowlist Validation\n\nUsed for security-sensitive validation with limited set of valid options:\n\n```go\nfunc validateExpressionSafety(content string) error {\n    matches := expressionRegex.FindAllStringSubmatch(content, -1)\n    var unauthorizedExpressions []string\n\n    for _, match := range matches {\n        expression := strings.TrimSpace(match[1])\n        if !isAllowed(expression) {\n            unauthorizedExpressions = append(unauthorizedExpressions, expression)\n        }\n    }\n\n    if len(unauthorizedExpressions) > 0 {\n        return fmt.Errorf(\"unauthorized expressions: %v\", unauthorizedExpressions)\n    }\n    return nil\n}\n```\n\n#### External Resource Validation\n\nUsed for validating external dependencies:\n\n```go\nfunc validateDockerImage(image string, verbose bool) error {\n    cmd := exec.Command(\"docker\", \"inspect\", image)\n    output, err := cmd.CombinedOutput()\n\n    if err != nil {\n        pullCmd := exec.Command(\"docker\", \"pull\", image)\n        if pullErr := pullCmd.Run(); pullErr != nil {\n            return fmt.Errorf(\"docker image not found: %s\", image)\n        }\n    }\n    return nil\n}\n```\n\n#### Schema Validation\n\nUsed for configuration file validation:\n\n```go\nfunc (c *Compiler) validateGitHubActionsSchema(yamlContent string) error {\n    schema := loadGitHubActionsSchema()\n\n    var data interface{}\n    if err := yaml.Unmarshal([]byte(yamlContent), &data); err != nil {\n        return err\n    }\n\n    if err := schema.Validate(data); err != nil {\n        return fmt.Errorf(\"schema validation failed: %w\", err)\n    }\n    return nil\n}\n```\n\n#### Progressive Validation\n\nUsed for applying multiple validation checks in sequence:\n\n```go\nfunc (c *Compiler) validateStrictMode(frontmatter map[string]any, networkPermissions *NetworkPermissions) error {\n    if !c.strictMode {\n        return nil\n    }\n\n    if err := c.validateStrictPermissions(frontmatter); err != nil {\n        return err\n    }\n\n    if err := c.validateStrictNetwork(networkPermissions); err != nil {\n        return err\n    }\n\n    return nil\n}\n```\n\n\n\n## Session Graders\n\nBuilt-ins implement `computeGraders(session, graders = [])` over a redacted\nin-memory unified-session array. Reuse `createSessionLookups(session)` from\n`actions\u002Fsetup\u002Fjs\u002Fgrader_session.cjs` for statistics, typed event lookups,\ncorrelated tool calls, scoped call indexes, and trajectory projections.\nKeep file I\u002FO at the collection\u002Freplay boundary, never inside graders.\nTen fast built-ins are enabled by default; expensive analyses require opt-in.\n\nCustom syntax is `graders.\u003Cdistinct-id>.script`, a synchronous JavaScript body\nreceiving immutable `session`, `config`, and `helpers` snapshots. Return a\nfinite number, `null`, or an object with `value`. The compiler partitions custom\nsource into a restricted downstream `graders` job; conclusion receives only\ncustom IDs. Never import or execute user code in conclusion, permit its step\nhooks, or allow `jobs.graders` customization. Repository-owned\n`graders.operational-value.run` Bash also runs only in that separate job: freeze\nthe confined `.sh` source at compilation, pass session JSONL as `$1` \u002F\n`GH_AW_SESSION_FILE` and config JSON as `GH_AW_GRADER_CONFIG`, and preserve legacy\nmetric-array output. Compilation and `grader-shell-file-write` share the Bash AST\nwrite checker. Shell has bounded execution and a stripped environment but is not\na filesystem\u002Fnetwork sandbox or microVM yet. Built-in overrides remain rejected.\n\nThe separate job consumes `usage\u002Faw_session.jsonl` and publishes combined results\nin the `graders` artifact without source. Preserve conclusion's published session.\nAudit conditionally fetches registered custom results; the logs `graders`\nartifact set includes `usage`, `graders`, and historical transports. Keep compiler,\nruntime, schema, replay, artifact maps, and these consumers consistent.\nSee [operational-value-designer](..\u002Foperational-value-designer\u002FSKILL.md) for\ncurrent authoring syntax and evidence design.\n\n## Safe Output Messages\n\nSafe output functions handle GitHub API write operations (creating issues, discussions, comments, PRs) from AI-generated content with consistent messaging patterns.\n\n### Recorded execution outcomes\n\nCustom safe jobs can map `outputs.status` and `outputs.url` to step outputs.\nConclusion identifies configured safe jobs explicitly and reads their outputs\nfrom `needs`, not from agent requests. It records `safe_output.result` events\nwith the normalized job name, status, and optional canonical absolute resource\nURI in `data.url`. A failed, cancelled, or skipped job cannot report success.\nOn a successful job, an explicit status can distinguish an intentional skip or\napplication-level failure; absent status falls back to the Actions job result.\nPrepared work-queue adapters are not verified effects and must not be promoted\nto successful safe-job outcomes.\n\nSafe scripts return execution results through the handler contract:\n`success: true` with `url` identifies the canonical resource returned by the\nservice. The safe-output manifest preserves execution status for conclusion's\nunified session collector. Keep artifact redaction before serialization and\npreserve staged\u002Fdeferred suppression. Never infer a generated resource URI\nfrom an agent-supplied request or copy arbitrary handler outputs into the session.\n\n### Safe Output Message Flow\n\nThe following diagram illustrates how AI-generated content flows through the safe output system to GitHub API operations:\n\n```mermaid\ngraph TD\n    A[AI Agent Output] --> B{Staged Mode?}\n    B -->|Yes| C[Generate Preview Messages]\n    B -->|No| D[Process Safe Output]\n    C --> E[Show ? Staged Mode Preview]\n    E --> F[Display in Step Summary]\n    D --> G{Safe Output Type}\n    G -->|create-issue| H[Create GitHub Issue]\n    G -->|create-discussion| I[Create GitHub Discussion]\n    G -->|add-comment| J[Add GitHub Comment]\n    G -->|create-pull-request| K[Create Pull Request]\n    G -->|create-pr-review-comment| L[Create PR Review Comment]\n    G -->|update-issue| M[Update GitHub Issue]\n    H --> N[Apply Message Patterns]\n    I --> N\n    J --> N\n    K --> N\n    L --> N\n    M --> N\n    N --> O[Add AI Attribution Footer]\n    N --> P[Add Installation Instructions]\n    N --> Q[Add Related Items Links]\n    N --> R[Add Patch Preview]\n    O --> S[Execute GitHub API Operation]\n    P --> S\n    Q --> S\n    R --> S\n    S --> T[Generate Success Summary]\n    T --> U[Display in Step Summary]\n```\n\n**Flow Stages:**\n1. **AI Agent Output** - AI generates content for GitHub operations\n2. **Staged Mode Check** - Determines if operation is in preview mode\n3. **Safe Output Processing** - Routes to appropriate GitHub operation type\n4. **Message Pattern Application** - Applies consistent formatting (footers, instructions, links)\n5. **GitHub API Execution** - Performs the actual GitHub operation\n6. **Success Summary** - Reports results in workflow step summary\n\n### Message Categories\n\n#### AI Attribution Footer\n\nIdentifies content as AI-generated and links to workflow run:\n\n```markdown\n> AI generated by [WorkflowName](run_url)\n```\n\nWith triggering context:\n```markdown\n> AI generated by [WorkflowName](run_url) for #123\n```\n\n#### Workflow Installation Instructions\n\n```markdown\n>\n> To add this workflow in your repository, run `gh aw add owner\u002Frepo\u002Fpath@ref`. See [usage guide](https:\u002F\u002Fgithub.github.com\u002Fgh-aw\u002Fsetup\u002Fcli\u002F).\n```\n\n#### Staged Mode Preview\n\nAll staged mode previews use consistent format with ? emoji:\n\n```markdown\n## ? Staged Mode: [Operation Type] Preview\n\nThe following [items] would be [action] if staged mode was disabled:\n```\n\n#### Patch Preview\n\nDisplay git patches in pull request bodies with size limits:\n\n```markdown\n\u003Cdetails>\u003Csummary>Show patch (45 lines)\u003C\u002Fsummary>\n\n\\`\\`\\`diff\ndiff --git a\u002Fsrc\u002Fauth.js b\u002Fsrc\u002Fauth.js\nindex 1234567..abcdefg 100644\n--- a\u002Fsrc\u002Fauth.js\n+++ b\u002Fsrc\u002Fauth.js\n@@ -10,7 +10,10 @@ export async function login(username, password) {\n-    throw new Error('Login failed');\n+    if (response.status === 401) {\n+      throw new Error('Invalid credentials');\n+    }\n+    throw new Error('Login error: ' + response.statusText);\n\\`\\`\\`\n\n\u003C\u002Fdetails>\n```\n\nLimits: Max 500 lines or 2000 characters (truncated with \"... (truncated)\" if exceeded)\n\n### Design Principles\n\n#### Consistency\n- All AI-generated content uses same blockquote footer format\n- ? emoji consistently marks staged preview mode\n- URL patterns match GitHub conventions\n- Step summaries follow same heading and list structure\n\n#### Clarity\n- Clear distinction between preview and actual operations\n- Explicit error messages with actionable guidance\n- Helpful fallback instructions when operations fail\n- Field labels consistently use bold text\n\n#### Discoverability\n- Installation instructions included in footers when available\n- Related items automatically linked across workflow outputs\n- Step summaries provide quick access to created items\n- Collapsible sections keep large content manageable\n\n#### Safety\n- Labels sanitized to prevent unintended @mentions\n- Patch sizes validated and truncated when needed\n- Staged mode allows testing without side effects\n- Graceful fallbacks when primary operations fail\n\n\n\n## Schema Validation\n\nAll three JSON schema files enforce strict validation with `\"additionalProperties\": false` at the root level, preventing typos and undefined fields from silently passing validation.\n\n### Schema Files\n\n| File | Purpose |\n|------|---------|\n| `pkg\u002Fparser\u002Fschemas\u002Fmain_workflow_schema.json` | Validates agentic workflow frontmatter in `.github\u002Fworkflows\u002F*.md` files |\n| `pkg\u002Fparser\u002Fschemas\u002Fmcp_config_schema.json` | Validates MCP (Model Context Protocol) server configuration |\n\n### How It Works\n\nWhen `\"additionalProperties\": false` is set at the root level, the validator rejects any properties not explicitly defined in the schema's `properties` section. This catches common typos:\n\n- `permisions` instead of `permissions`\n- `engnie` instead of `engine`\n- `toolz` instead of `tools`\n- `timeout_minute` instead of `timeout-minutes`\n- `runs_on` instead of `runs-on`\n- `safe_outputs` instead of `safe-outputs`\n\n### Example Validation Error\n\n```bash\n$ gh aw compile workflow-with-typo.md\n✗ error: Unknown properties: toolz, engnie, permisions. Valid fields are: tools, engine, permissions, ...\n```\n\n### Validation Process\n\n```mermaid\ngraph LR\n    A[Read workflow frontmatter] --> B[Parse YAML]\n    B --> C[Validate against JSON schema]\n    C --> D{Valid?}\n    D -->|Yes| E[Continue compilation]\n    D -->|No| F[Provide detailed error]\n    F --> G[Show invalid fields]\n    F --> H[Show valid field names]\n```\n\n### Schema Embedded in Binary\n\nSchemas are embedded in the Go binary using `\u002F\u002Fgo:embed` directives:\n\n```go\n\u002F\u002Fgo:embed schemas\u002Fmain_workflow_schema.json\nvar mainWorkflowSchema string\n```\n\nThis means:\n- Schema changes require running `make build` to take effect\n- Schemas are validated at runtime, not at build time\n- No external JSON files need to be distributed with the binary\n\n### Adding New Fields\n\nWhen adding new fields to schemas:\n\n1. Update the schema JSON file with the new property definition\n2. Rebuild the binary with `make build`\n3. Add test cases to verify the new field works\n4. Update documentation if the field is user-facing\n\n\n\n## YAML Compatibility\n\nYAML has two major versions with incompatible boolean parsing behavior that affects workflow validation.\n\n### The Core Issue\n\n#### YAML 1.1 Boolean Parsing Problem\n\nIn YAML 1.1, certain plain strings are automatically converted to boolean values. The workflow trigger key `on:` can be misinterpreted as boolean `true` instead of string `\"on\"`.\n\n**Example:**\n```python\n# Python yaml.safe_load (YAML 1.1 parser)\nimport yaml\n\ncontent = \"\"\"\non:\n  issues:\n    types: [opened]\n\"\"\"\n\nresult = yaml.safe_load(content)\nprint(result)\n# Output: {True: {'issues': {'types': ['opened']}}}\n#          ^^^^ The key is boolean True, not string \"on\"!\n```\n\nThis creates false positives when validating workflows with Python-based tools.\n\n#### YAML 1.2 Correct Behavior\n\nYAML 1.2 parsers treat `on`, `off`, `yes`, and `no` as regular strings, not booleans. Only explicit boolean literals `true` and `false` are treated as booleans.\n\n**Example:**\n```go\n\u002F\u002F Go goccy\u002Fgo-yaml (YAML 1.2 parser) - Used by gh-aw\nvar result map[string]interface{}\nyaml.Unmarshal([]byte(content), &result)\n\nfmt.Printf(\"%+v\\n\", result)\n\u002F\u002F Output: map[on:map[issues:map[types:[opened]]]]\n\u002F\u002F         ^^^ The key is string \"on\" ✓\n```\n\n### How gh-aw Handles This\n\nGitHub Agentic Workflows uses **`goccy\u002Fgo-yaml` v1.18.0**, which is a **YAML 1.2 compliant parser**:\n\n- ✅ `on:` is correctly parsed as a string key, not a boolean\n- ✅ Workflow frontmatter validation works correctly\n- ✅ GitHub Actions YAML is compatible (GitHub Actions also uses YAML 1.2 parsing)\n\n### Compatibility Flow\n\n```mermaid\ngraph TD\n    A[Workflow File] --> B{Parser Type?}\n    B -->|YAML 1.1| C[Python yaml.safe_load]\n    B -->|YAML 1.2| D[gh-aw \u002F goccy\u002Fgo-yaml]\n    C --> E[on: parsed as True]\n    D --> F[on: parsed as string]\n    E --> G[False Positive]\n    F --> H[Correct Validation]\n```\n\n### Affected Keywords\n\nYAML 1.1 treats these as booleans (parsed as `true` or `false`):\n\n**Parsed as `true`:** on, yes, y, Y, YES, Yes, ON, On\n**Parsed as `false`:** off, no, n, N, NO, No, OFF, Off\n\nYAML 1.2 treats all of the above as strings. Only these are booleans: `true`, `false`\n\n### Recommendations\n\n#### For Workflow Authors\n\n1. **Use gh-aw's compiler for validation:**\n   ```bash\n   gh aw compile workflow.md\n   ```\n\n2. **Don't trust Python yaml.safe_load for validation** - it will give false positives for the `on:` trigger key.\n\n3. **Use explicit booleans when you mean boolean values:**\n   ```yaml\n   enabled: true      # Explicit boolean\n   disabled: false    # Explicit boolean\n\n   # Avoid for boolean values:\n   enabled: yes       # Might be confusing across parsers\n   disabled: no       # Might be confusing across parsers\n   ```\n\n#### For Tool Developers\n\n1. **Use YAML 1.2 parsers for gh-aw integration:**\n   - Go: `github.com\u002Fgoccy\u002Fgo-yaml`\n   - Python: `ruamel.yaml` (with YAML 1.2 mode)\n   - JavaScript: `yaml` package v2+ (YAML 1.2 by default)\n   - Ruby: `Psych` (YAML 1.2 by default in Ruby 2.6+)\n\n2. **Document parser version in your tool**\n\n3. **Consider adding compatibility mode** to switch between YAML 1.1 and 1.2 parsing\n\n\n\n## MCP Logs Guardrail\n\nThe MCP server `logs` command includes an automatic guardrail to prevent overwhelming responses when fetching workflow logs.\n\n### How It Works\n\n```mermaid\ngraph TD\n    A[logs command called] --> B[Generate output]\n    B --> C{Output size check}\n    C -->|≤ 12000 tokens| D[Return full JSON data]\n    C -->|> 12000 tokens| E[Return guardrail message]\n    E --> F[Include schema description]\n    E --> G[Provide suggested jq queries]\n```\n\n### Normal Operation (Output ≤ Token Limit)\n\nWhen output is within the token limit (default: 12000 tokens), the command returns full JSON data:\n\n```json\n{\n  \"summary\": {\n    \"total_runs\": 5,\n    \"total_duration\": \"2h30m\",\n    \"total_tokens\": 45000,\n    \"total_cost\": 0.23\n  },\n  \"runs\": [...],\n  \"tool_usage\": [...]\n}\n```\n\n### Guardrail Triggered (Output > Token Limit)\n\nWhen output exceeds the token limit, the command returns structured response with:\n\n```json\n{\n  \"message\": \"⚠️  Output size (15000 tokens) exceeds the limit (12000 tokens). To reduce output size, use the 'jq' parameter with one of the suggested queries below.\",\n  \"output_tokens\": 15000,\n  \"output_size_limit\": 12000,\n  \"schema\": { ... },\n  \"suggested_queries\": [\n    {\n      \"description\": \"Get only the summary statistics\",\n      \"query\": \".summary\",\n      \"example\": \"Use jq parameter: \\\".summary\\\"\"\n    },\n    ...\n  ]\n}\n```\n\n### Configuring the Token Limit\n\nDefault limit is 12000 tokens (approximately 48KB of text). Customize using the `max_tokens` parameter:\n\n```json\n{\n  \"name\": \"logs\",\n  \"arguments\": {\n    \"count\": 100,\n    \"max_tokens\": 20000\n  }\n}\n```\n\nToken estimation uses approximately 4 characters per token (OpenAI's rule of thumb).\n\n### Using the jq Parameter\n\nFilter output using jq syntax:\n\n**Get only summary statistics:**\n```json\n{ \"jq\": \".summary\" }\n```\n\n**Get run IDs and basic info:**\n```json\n{ \"jq\": \".runs | map({database_id, workflow_name, status})\" }\n```\n\n**Get only failed runs:**\n```json\n{ \"jq\": \".runs | map(select(.conclusion == \\\"failure\\\"))\" }\n```\n\n**Get high token usage runs:**\n```json\n{ \"jq\": \".runs | map(select(.token_usage > 10000))\" }\n```\n\n### Implementation Details\n\n**Constants:**\n- `DefaultMaxMCPLogsOutputTokens`: 12000 tokens (default limit)\n- `CharsPerToken`: 4 characters per token (estimation factor)\n\n**Files:**\n- `pkg\u002Fcli\u002Fmcp_logs_guardrail.go` - Core guardrail implementation\n- `pkg\u002Fcli\u002Fmcp_logs_guardrail_test.go` - Unit tests\n- `pkg\u002Fcli\u002Fmcp_logs_guardrail_integration_test.go` - Integration tests\n- `pkg\u002Fcli\u002Fmcp_server.go` - Integration with MCP server\n\n### Benefits\n\n1. Prevents overwhelming responses for AI models\n2. Provides guidance with specific filters\n3. Self-documenting with schema description\n4. Preserves functionality with jq filtering\n5. Transparent messaging about why guardrail triggered\n",{"name":5,"description":7},"main","8541229759617347888641eba917d3b0ad66a984",".github\u002Fskills\u002Fdeveloper-internals",626,"https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw","https:\u002F\u002Fgh.io\u002Fgh-aw","https:\u002F\u002Fgithub.com\u002Fgithub","https:\u002F\u002Fgithub.com\u002Fabout","How people build software.","2026-11-15 06:45:15",{"source":8,"skillName":5,"commands":61,"prompt":71,"zipAvailable":72},[62,65,68],{"tool":63,"command":64},"npx","npx skills add github\u002Fgh-aw --skill developer-internals",{"tool":66,"command":67},"bunx","bunx skills add github\u002Fgh-aw --skill developer-internals",{"tool":69,"command":70},"pnpm","pnpm dlx skills add github\u002Fgh-aw --skill developer-internals","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fdeveloper-internals\u002FSKILL.md",true,[74],{"path":75,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":78,"sourceHtmlUrl":79},"agents\u002Fopenai.yaml","REFERENCE","参考文档",146,"https:\u002F\u002Fgithub.com\u002Faliyome\u002Fenv\u002Fblob\u002Fmaster\u002F.rulesync\u002Fskills\u002F.curated\u002Fretro\u002Fagents\u002Fopenai.yaml",[81,89,97,121,138,163],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":88},"01M7DQYVZ9W9DDXKQ9452SNP8J","cracktro","Edit, preview, and verify the standalone interactive talk deck in docs\u002Fpublic\u002Fcracktro (slides, SVG diagrams, transitions, WebAudio sound).","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fcracktro\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":96},"01M7612HQ4378TK8QZ5HPAF4KR","create-connector","Create or extend a declaration-only third-party connector, with narrow reads, separate safe outputs, optional protected triggers, and offline conformance evidence.","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fcreate-connector\u002FSKILL.md",[],[],"2026-11-12 13:55:43",{"skillNo":98,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":107,"publishedAt":45},"01M6ADC942STTXHFV410J4DH0X","GitHub Agentic Workflows","GitHub Agentic Workflows (`gh-aw`) is a GitHub CLI extension for writing Agentic Workflows in markdown and compiling them to GitHub Actions.","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002FSKILL.md",[103,106],{"categoryNo":104,"categoryName":105,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000011","运维与部署",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[9,108,109,110,111,112,113,114,115,38,116,117,118,119,120],"github agentic workflows","agentic workflows","workflows","agentic","extension","markdown","github cli","cli","for","compiling","writing","github actions","actions",{"skillNo":122,"name":123,"nameZh":6,"description":124,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":125,"categories":126,"keywords":127,"publishedAt":45},"01M6ADC6ZXSA46N9XD6VNAP1MS","windows-compatibility","Cross-platform path handling and command patterns","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Fwindows-compatibility\u002FSKILL.md",[],[128,129,41,130,131,132,133,134,135,136,137],"windows","windows compatibility","command","git","bugs","platform","high","patterns","cross-platform","path",{"skillNo":139,"name":140,"nameZh":6,"description":141,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":142,"categories":143,"keywords":144,"publishedAt":45},"01M6ADC44957SVQF96R5YY247P","versioning-policy","Semver versioning rules for Squad SDK and CLI — prevents prerelease version incidents","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Fversioning-policy\u002FSKILL.md",[],[145,146,147,148,149,115,150,151,152,153,154,155,156,157,116,158,159,160,161,162],"versioning","policy","versioning policy","gate","implementation","workspace","pr","sdk","release","ci","npm","semver","squad","incident","incidents","Rules","version","resolution",{"skillNo":164,"name":165,"nameZh":6,"description":166,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":167,"categories":168,"keywords":173,"publishedAt":45},"01M6ADC1PHMEAEVR87F8PDR89X","tiered-memory","Three-tier agent memory model (hot\u002Fcold\u002Fwiki) for context reduction per spawn","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Ftiered-memory\u002FSKILL.md",[169,172],{"categoryNo":170,"categoryName":171,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[174,175,176,177,178,179,180,181,182,183,184,185,186,116,187,188],"tiered memory","memory","performance","design","agent memory","proposal","cold","model","wiki","spawn","memory-management","context","three","runtime","management"]