github-agentic-workflows-tools-ecosystem

# 🛠️ GitHub Agentic Workflows Tools Ecosystem ## 🔴 AI FIRST Quality Principle > **Apply the AI FIRST principle: never accept first-pass quality. Minimum 2 iterations. Read all output, improve every section. No shortcuts.** ## 📋 Overview This skill provides a comprehensive guide to all tools available in GitHub Agentic Workflows. Understanding the tools ecosystem is critical for building effective AI agents that can interact with code, GitHub APIs, browsers, and external services. ### What is the Tools Ecosystem? The **Tools Ecosystem** is the collection of capabilities that AI agents can invoke to perform actions: - **GitHub Tools**: Interact with repositories, issues, PRs, workflows - **File Operations**: Read, write, edit files in repositories - **Web Tools**: Fetch web pages, make HTTP requests, search the web - **Bash Tools**: Execute shell commands, run scripts - **Playwright Tools**: Automate browsers, take screenshots, interact with web UIs - **Memory Tools**: Store and retrieve knowledge across sessions - **Custom Tools**: Develop domain-specific tools via MCP servers ### Why Master the Tools Ecosystem? Effective agents require deep knowledge of available tools: - ✅ **Capability Awareness**: Know what's possible - ✅ **Tool Selection**: Choose the right tool for each task - ✅ **Efficient Workflows**: Combine tools effectively - ✅ **Security**: Understand tool limitations and risks - ✅ **Error Handling**: Handle tool failures gracefully - ✅ **Extensibility**: Build custom tools when needed --- ## 🐙 GitHub Tools ### Repository Operations #### View Files and Directories ```javascript // github-get_file_contents await github.getFileContents({ owner: 'Hack23', repo: 'riksdagsmonitor', path: 'src/index.js', ref: 'main', }); // List directory await github.getFileContents({ owner: 'Hack23', repo: 'riksdagsmonitor', path: 'src/', }); ``` #### Get Repository Tree ```javascript // github-get_repository_tree await github.getRepositoryTree({ owner: 'Hack23', repo: 'riksdagsmonitor', tree_sha: 'main', recursive: true, path_filter: 'src/', }); ``` ### Issue Operations ```javascript // Create issue await github.issueWrite({ method: 'create', owner: 'Hack23', repo: 'riksdagsmonitor', title: 'Bug: Application crashes', body: 'Description here...', labels: ['bug', 'P1-high'], assignees: ['developer1'], }); // Search issues await github.searchIssues({ query: 'repo:Hack23/riksdagsmonitor is:open label:bug', sort: 'created', order: 'desc', }); ``` ### Pull Request Operations ```javascript // Create PR await github.createPullRequest({ owner: 'Hack23', repo: 'riksdagsmonitor', title: 'feat: Add dark mode', body: 'Implementation details...', head: 'feature/dark-mode', base: 'main', }); // Get PR diff await github.pullRequestRead({ method: 'get_diff', owner: 'Hack23', repo: 'riksdagsmonitor', pullNumber: 456, }); // Code review await github.pullRequestReviewWrite({ method: 'create', owner: 'Hack23', repo: 'riksdagsmonitor', pullNumber: 456, body: 'LGTM!', event: 'APPROVE', }); ``` ### GitHub Actions ```javascript // List workflows await github.actionsList({ method: 'list_workflows', owner: 'Hack23', repo: 'riksdagsmonitor', }); // Trigger workflow await github.actionsRunTrigger({ method: 'run_workflow', owner: 'Hack23', repo: 'riksdagsmonitor', workflow_id: 'deploy.yml', ref: 'main', inputs: { environment: 'production' }, }); // Get job logs await github.getJobLogs({ owner: 'Hack23', repo: 'riksdagsmonitor', job_id: 98765432, return_content: true, tail_lines: 500, }); ``` --- ## 📁 File Operations ### Read Files ```javascript // Read entire file const content = await filesystem.readTextFile({ path: '/workspace/src/index.js', }); // Read first 50 lines const header = await filesystem.readTextFile({ path: '/workspace/README.md', head: 50, }); // Read last 100 lines const logs = await filesystem.readTextFile({ path: '/workspace/app.log', tail: 100, }); // Read multiple files const files = await filesystem.readMultipleFiles({ paths: ['file1.js', 'file2.js', 'file3.js'], }); ``` ### Write and Edit Files ```javascript // Create or overwrite file await filesystem.writeFile({ path: '/workspace/output.txt', content: 'File content...', }); // Edit file (line-based) await filesystem.editFile({ path: '/workspace/src/index.js', edits: [ { oldText: 'const oldVar = 123;', newText: 'const newVar = 456;', }, ], }); ``` ### Directory Operations ```javascript // List directory const entries = await filesystem.listDirectory({ path: '/workspace/src', }); // List with sizes const entriesWithSizes = await filesystem.listDirectoryWithSizes({ path: '/workspace/dist', sortBy: 'size', }); // Get directory tree const tree = await filesystem.directoryTree({ path: '/workspace', excludePatterns: ['node_modules/**', '.git/**'], }); // Create directory await filesystem.createDirectory({ path: '/workspace/new-dir', }); // Search files const jsFiles = await filesystem.searchFiles({ path: '/workspace', pattern: '**/*.js', }); ``` --- ## 🌐 Web Tools ### AI-Powered Web Search ```javascript // Web search with AI-generated answer const result = await web.search({ query: 'What are the latest features in React 19?', }); // Returns: // { // answer: 'AI-generated answer with citations...', // sources: [...] // } ``` ### HTTP Requests (via bash) ```bash # GET request curl -s https://api.github.com/repos/Hack23/riksdagsmonitor | jq . # POST request curl -s -X POST https://api.example.com/endpoint \ -H "Content-Type: application/json" \ -d '{"key":"value"}' # With authentication curl -s -H "Authorization: Bearer $TOKEN" \ https://api.example.com/data ``` --- ## 💻 Bash Tools ### Execute Commands ```javascript // Synchronous const result = await bash({ command: 'npm test', mode: 'sync', initial_wait: 60, }); // Async await bash({ command: 'npm run build', mode: 'async', shellId: 'build-session', }); // Read output await read_bash({ shellId: 'build-session', delay: 30, }); // Detached (persistent) await bash({ command: 'npm run dev', mode: 'async', detach: true, }); ``` ### Common Patterns ```bash # Code analysis eslint src/ --format json > report.json npm audit --json > audit.json # Git operations git --no-pager status git --no-pager diff git add . && git commit -m "feat: New feature" # Build and test npm ci npm run lint npm test npm run build ``` --- ## 🌐 Playwright Tools ### Browser Navigation ```javascript // Navigate await playwright.browserNavigate({ url: 'https://riksdagsmonitor.pages.dev', }); // Capture accessibility snapshot const snapshot = await playwright.browserSnapshot(); ``` ### Page Interaction ```javascript // Click element await playwright.browserClick({ ref: '[2]', element: 'Button', }); // Type text await playwright.browserType({ ref: '[5]', element: 'Search input', text: 'query', submit: true, }); // Fill form await playwright.browserFillForm({ fields: [ { ref: '[10]', name: 'username', type: 'textbox', value: 'user' }, { ref: '[11]', name: 'password', type: 'textbox', value: 'pass' }, ], }); ``` ### Screenshots ```javascript // Full page screenshot await playwright.browserTakeScreenshot({ filename: 'page.png', fullPage: true, }); // Element screenshot await playwright.browserTakeScreenshot({ ref: '[4]', element: 'Article', filename: 'article.png', }); ``` --- ## 🧠 Memory Tools ### Knowledge Graph ```javascript // Create entities await memory.createEntities({ entities: [ { name: 'Riksdagsmonitor', entityType: 'project', observations: ['Static website', 'GitHub Pages'], }, ], }); // Create relationships await memory.createRelations({ relations: [ { from: 'Riksdagsmonitor', to: 'GitHub Pages', relationType: 'uses', }, ], }); // Search knowledge const results = await memory.searchNodes({ query: 'Swedish Parliament', }); // Read graph const graph = await memory.readGraph(); ``` --- ## 🔧 Custom Tool Development ### Create MCP Server ```javascript // custom-mcp-server.js import { Server } from '@modelcontextprotocol/sdk/server/index.js'; class CustomMCPServer { constructor() { this.server = new Server({ name: 'custom-tools', version: '1.0.0', }, { capabilities: { tools: {} }, }); this.setupTools(); } setupTools() { this.server.setRequestHandler('tools/list', async () => ({ tools: [ { name: 'analyze_code', description: 'Analyze code quality', inputSchema: { type: 'object', properties: { path: { type: 'string' }, }, required: ['path'], }, }, ], })); this.server.setRequestHandler('tools/call', async (request) => { const { name, arguments: args } = request.params; if (name === 'analyze_code') { return this.analyzeCode(args); } throw new Error(`Unknown tool: ${name}`); }); } async analyzeCode(args) { // Implementation return { content: [ { type: 'text', text: 'Analysis results...' }, ], }; } async start() { const transport = new StdioServerTransport();