feat: add AWF agent skill for Claude Code agents

[Mossaka]

Summary

• Add a comprehensive skill that enables Claude Code agents to use AWF effectively
• Place the skill at repository root (skill.md) for easy access at a simple URL
• Include installation instructions and documentation

Skill URL

Once merged, the skill will be available at:

https://raw.githubusercontent.com/github/gh-aw-firewall/main/skill.md

How to Install

Other agents can install this skill with:

mkdir -p .claude/skills/awf-skill
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/skill.md \
  -o .claude/skills/awf-skill/SKILL.md

Skill Contents

The skill provides:

• Complete AWF CLI reference and usage patterns
• Domain whitelisting syntax (wildcards, subdomains, protocol filters)
• Common workflows (GitHub Copilot, MCP servers, Playwright, CI/CD)
• Log analysis commands
• Debugging and troubleshooting guides
• Best practices and limitations

Files Added

File	Purpose
skill.md	Main skill file at repository root
.claude/skills/awf-skill/SKILL.md	Local development copy
.claude/skills/awf-skill/README.md	Installation guide
.claude/skills/awf-skill/install.sh	Install script
docs/agent-skill.md	Documentation

Test plan

• Verify skill.md is accessible after merge
• Test installation in a separate project
• Verify Claude Code agents can reference the skill

🤖 Generated with Claude Code

[github-actions]

📰 VERDICT: Smoke Copilot has concluded. All systems operational. This is a developing story. 🎤

[github-actions]

🎬 THE END — Smoke Claude MISSION: ACCOMPLISHED! The hero saves the day! ✨

[github-actions]

✅ Coverage Check Passed

Overall Coverage

Metric	Base	PR	Delta
Lines	82.08%	82.08%	➡️ +0.00%
Statements	82.12%	82.12%	➡️ +0.00%
Functions	81.95%	81.95%	➡️ +0.00%
Branches	75.41%	75.41%	➡️ +0.00%

---

Coverage comparison generated by scripts/ci/compare-coverage.ts

[github-actions]

Go Build Test Results

Project	Download	Tests	Status
color	✅	1/1	PASS
env	✅	1/1	PASS
uuid	✅	1/1	PASS

Overall: PASS ✅

All Go projects built and tested successfully.

AI generated by Build Test Go

[github-actions]

C++ Build Test Results

Project	CMake	Build	Status
fmt	✅	✅	PASS
json	✅	✅	PASS

Overall: PASS ✅

All C++ projects built successfully.

AI generated by Build Test C++

[github-actions]

Deno Build Test Results

Project	Tests	Status
oak	1/1	✅ PASS
std	1/1	✅ PASS

Overall: ✅ PASS

All Deno tests completed successfully.

AI generated by Build Test Deno

[github-actions]

Smoke Test Results

Last 2 Merged PRs:

• fix: add auth and error handling to build-test workflows
• fix: restructure smoke-chroot workflow to avoid Docker-in-Docker

Tests:

• ✅ GitHub MCP Testing
• ✅ Playwright Testing (GitHub page title verified)
• ✅ File Writing Testing
• ✅ Bash Tool Testing

Status: PASS

cc @Mossaka

AI generated by Smoke Copilot

[github-actions]

Node.js Build Test Results

Project	Install	Tests	Status
clsx	✅	PASS	PASS
execa	✅	PASS	PASS
p-limit	✅	PASS	PASS

Overall: PASS ✅

All Node.js projects built and tested successfully.

AI generated by Build Test Node.js

[github-actions]

❌ Java Build Test Failed

Status: FAILED - Missing Dependencies

Issue

Java Development Kit (JDK) and Apache Maven are not installed in the GitHub Actions runner environment.

Test Status

Project	Compile	Tests	Status
gson	❌	-	FAILED (Cannot compile - Maven not available)
caffeine	❌	-	FAILED (Cannot compile - Maven not available)

Overall: FAILED

Required Action

The workflow needs to be updated to install Java and Maven before running tests. Recommended solutions:

1. Use actions/setup-java@v4 in the workflow:

   - uses: actions/setup-java@v4
     with:
       distribution: 'temurin'
       java-version: '17'
       cache: 'maven'

2. Or use a container with Java pre-installed:

   container: maven:3.9-openjdk-17

Error Details

E: List directory /var/lib/apt/lists/partial is missing
sudo: The "no new privileges" flag is set, which prevents sudo from running as root

The runner environment does not have package management configured and cannot install dependencies.

AI generated by Build Test Java

[github-actions]

Smoke Test Results

Last 2 merged PRs:

• fix: add auth and error handling to build-test workflows #514: fix: add auth and error handling to build-test workflows
• fix: restructure smoke-chroot workflow to avoid Docker-in-Docker #508: fix: restructure smoke-chroot workflow to avoid Docker-in-Docker

✅ GitHub MCP - PASS
✅ Playwright - PASS (title: "GitHub · Change is constant. GitHub keeps you ahead. · GitHub")
✅ File Writing - PASS
✅ Bash Tool - PASS

Overall: PASS

AI generated by Smoke Claude

[Copilot]

Pull request overview

This PR adds a comprehensive skill that enables Claude Code agents to effectively use the AWF (Agentic Workflow Firewall) tool. The skill provides complete CLI documentation, usage patterns, and troubleshooting guides that agents can reference when running commands with network isolation and domain whitelisting.

Changes:

• Add canonical skill.md at repository root for easy GitHub raw URL access
• Include local development copy at .claude/skills/awf-skill/SKILL.md (intentionally excludes installation section since it's the installed artifact)
• Provide installation script and README for easy skill deployment
• Add comprehensive documentation in docs/agent-skill.md

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
skill.md	Canonical skill file at repository root providing complete AWF CLI reference, domain whitelisting patterns, common workflows, debugging guides, and best practices
.claude/skills/awf-skill/SKILL.md	Local development copy of the skill (excludes installation section as this is the installed artifact)
.claude/skills/awf-skill/README.md	Installation and usage guide for the AWF skill with multiple installation options
.claude/skills/awf-skill/install.sh	Bash script for automated skill installation supporting both local and remote sources
docs/agent-skill.md	Comprehensive documentation explaining what agent skills are, how to install the AWF skill, and example agent interactions

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

🎬 THE END — Smoke Claude MISSION: ACCOMPLISHED! The hero saves the day! ✨

[github-actions]

📰 VERDICT: Smoke Copilot has concluded. All systems operational. This is a developing story. 🎤

[github-actions]

C++ Build Test Results

Project	CMake	Build	Status
fmt	✅	✅	PASS
json	✅	✅	PASS

Overall: PASS ✅

All C++ projects built successfully.

AI generated by Build Test C++

[github-actions]

Go Build Test Results

Project	Download	Tests	Status
color	✅	1/1	PASS
env	✅	1/1	PASS
uuid	✅	1/1	PASS

Overall: PASS ✅

All Go projects successfully downloaded dependencies and passed tests.

AI generated by Build Test Go

[github-actions]

Smoke Test Results

Last 2 Merged PRs:

• fix: add auth and error handling to build-test workflows #514: fix: add auth and error handling to build-test workflows
• fix: restructure smoke-chroot workflow to avoid Docker-in-Docker #508: fix: restructure smoke-chroot workflow to avoid Docker-in-Docker

Test Results:

• ✅ GitHub MCP: Retrieved PR data successfully
• ✅ Playwright: Verified GitHub page title
• ✅ File Creation: Created test file at /tmp/gh-aw/agent/smoke-test-copilot-21690704996.txt
• ✅ Bash Commands: Verified file content

Overall Status: PASS 🎉

cc: @Mossaka

AI generated by Smoke Copilot

[github-actions]

Deno Build Test Results

Project	Tests	Status
oak	1/1	✅ PASS
std	1/1	✅ PASS

Overall: ✅ PASS

All Deno tests completed successfully.

AI generated by Build Test Deno

[github-actions]

Node.js Build Test Results

Project	Install	Tests	Status
clsx	✅	PASS	PASS
execa	✅	PASS	PASS
p-limit	✅	PASS	PASS

Overall: PASS ✅

All Node.js projects built and tested successfully.

AI generated by Build Test Node.js

[github-actions]

❌ Build Test: Bun - FAILED

Environment Issue: Bun runtime is incompatible with this GitHub Actions runner environment.

Error Details

• Bun Install: ✅ Installed successfully (v1.3.8)
• Repository Clone: ✅ Cloned successfully
• Runtime Execution: ❌ FAILED - Core dump when running tests

Root Cause

bun test v1.3.8
Aborted (core dumped)

The GitHub Actions runner environment lacks /proc/cpuinfo which Bun requires. When attempting to run bun test, the runtime crashes immediately.

Test Results

Project	Install	Tests	Status
elysia	❌	N/A	FAILED (runtime crash)
hono	❌	N/A	FAILED (runtime crash)

Overall: FAILED

Recommendation

To run Bun tests in CI:

1. Use self-hosted runners with full /proc filesystem access
2. Use Docker containers with --privileged flag
3. Use alternative runtimes (Node.js) for compatibility testing

AI generated by Build Test Bun

[github-actions]

Smoke Test Results - Claude Engine

Last 2 merged PRs:

• fix: add auth and error handling to build-test workflows #514: fix: add auth and error handling to build-test workflows
• fix: restructure smoke-chroot workflow to avoid Docker-in-Docker #508: fix: restructure smoke-chroot workflow to avoid Docker-in-Docker

Test Results:

• ✅ GitHub MCP - Retrieved PR data successfully
• ✅ Playwright - Page title: "GitHub · Change is constant. GitHub keeps you ahead. · GitHub"
• ✅ File Writing - Created /tmp/gh-aw/agent/smoke-test-claude-21690705028.txt
• ✅ Bash Tool - Verified file content: "Smoke test passed for Claude at Wed Feb 4 22:25:27 UTC 2026"

Overall Status: PASS

AI generated by Smoke Claude

[github-actions]

❌ Build Test: Java - FAILED

Status: Unable to execute tests due to environment issues.

Error Details

The test execution failed due to a broken Maven installation in the GitHub Actions runner:

1. Maven Installation Issue: Maven binary at /usr/share/apache-maven-3.9.12/ exists but produces error:

   cannot execute binary file: Exec format error
   

2. Shell Command Interception: All Java and Maven commands (even with full paths) are being intercepted and return bash version info instead of executing the actual binaries.

3. Container Environment: Running inside container bb54acbed1cf with restricted permissions (no sudo access to reinstall Maven).

Attempted Workarounds

• ✗ Direct Maven binary execution
• ✗ Java-based Maven launcher invocation
• ✗ Download fresh Maven binary
• ✗ Use alternate Maven paths

Test Results

Project	Compile	Tests	Status
gson	❌ Not Run	-	BLOCKED
caffeine	❌ Not Run	-	BLOCKED

Overall: FAILED - Environment issue prevents test execution

Required Action

The GitHub Actions runner environment needs to be fixed or the workflow needs to be updated to use a different approach (e.g., using a Docker container with pre-installed Maven, or using setup-java action with Maven cache).

AI generated by Build Test Java

[github-actions]

❌ Build Test: Rust - FAILED

Status: FAILED - Cannot Install Rust Toolchain

Environment Issue

Unable to execute Rust build tests due to a critical environment issue:

• Problem: The rustup binary is being replaced with /usr/bin/bash (verified via SHA256 hash)
• Hash: bc5945feb8bd26203ebfafea5ce1878bb2e32cb8fb50ab7ae395cfb1e1aaaef1 (matches bash, not rustup)
• Sudo disabled: Container has "no new privileges" flag set, preventing apt-get install cargo

Test Results

Project	Build	Tests	Status
fd	⏸️	-	BLOCKED
zoxide	⏸️	-	BLOCKED

Overall: FAILED

Resolution Required

This workflow requires Rust to be pre-installed in the GitHub Actions environment or container, as runtime installation via rustup is blocked by security policies.

AI generated by Build Test Rust