F4: The .github Agentic OS — GitHub Copilot’s 7 Primitives

Table of Contents

• F4.1 Why .github Is No Longer Just a Folder
• F4.2 The 4-Layer Architecture
• F4.3 Layer 1 — Always-On Context (Instructions)
• F4.4 Layer 2 — On-Demand Capabilities
• F4.5 Layer 3 — Enforcement & Automation
• F4.6 Layer 4 — Distribution (Plugins)
• F4.7 FrootAI’s Implementation — 19 Files per Solution Play
• F4.8 Decision Guide — When to Use What
• F4.9 Building Your Own .github Agentic OS
• Learning Outcomes
• Prerequisites
• Applied Scenario: Compose a Governed Repository Assistant
• Knowledge Check
• Key Takeaways

Learning Outcomes

After completing this module, you can:

• Distinguish instructions, prompts, agents, skills, hooks, workflows, and plugins by ownership and lifecycle.
• Select the smallest GitHub customization primitive that satisfies a requirement.
• Wire reusable primitives through a manifest without duplicating source guidance.
• Review an agentic repository for scope, trust, and maintenance risks.

Prerequisites

Prerequisites: Complete F1: GenAI Foundations and understand GitHub repositories, Markdown, and Actions workflows.

F4.1 Why .github Is No Longer Just a Folder

GitHub Copilot’s .github folder has evolved from a single copilot-instructions.md file into a full agentic operating system — 7 composable primitives across 4 layers that turn any repository into an agent-native workspace.

This is not a future roadmap. This is happening now. Every AI-first team needs to understand and adopt these primitives to stay competitive.

The Mental Model

Think of .github as your repository’s operating system for AI agents:

F4.2 The 4-Layer Architecture

The 7 primitives are organized into 4 layers, each serving a distinct purpose:

F4.3 Layer 1 — Always-On Context (Instructions)

Primitive 1: Instructions

Files: .github/copilot-instructions.md + .github/instructions/*.instructions.md

Instructions are passive memory — they apply to every prompt automatically without the user asking. Copilot reads these before generating any response.

Use for: Coding standards, framework rules, repo conventions, architectural constraints.

Single File (Legacy)

<!-- .github/copilot-instructions.md -->
You are working on an Azure-based RAG pipeline.
Always use Managed Identity. Never hardcode secrets.
Use config/*.json for all AI parameters.

Modular Files (Modern)

.github/instructions/
├── azure-coding.instructions.md    # Azure SDK patterns, managed identity
├── rag-patterns.instructions.md    # Chunking, retrieval, anti-hallucination
└── security.instructions.md        # Secrets, PII, access control

Why modular? Different files apply to different parts of the codebase. Copilot loads only the relevant instructions based on the file being edited, reducing noise and improving accuracy.

Best Practices

F4.4 Layer 2 — On-Demand Capabilities

Primitive 2: Prompt Files

Files: .github/prompts/*.prompt.md

Prompt files are slash commands — manually invoked by the user or another agent. They define a specific task with context and steps.

<!-- .github/prompts/deploy.prompt.md -->
# Deploy to Azure
 
## Steps
1. Validate config files exist
2. Run az bicep build to validate template
3. Deploy infrastructure
4. Run smoke test

Invocation: Type /deploy in Copilot Chat → Copilot reads and executes the prompt.

Use for: /security-review, /release-notes, /changelog, /deploy, /test, /evaluate

Primitive 3: Custom Agents

Files: .github/agents/*.agent.md

Custom agents are specialist personas with their own identity, tools, and MCP server bindings. Agents can be chained via handoffs:

planning agent → implementation agent → review agent

<!-- .github/agents/builder.agent.md -->
# Builder Agent
 
You are the implementation agent for this solution.
 
## Your Tools
- FrootAI MCP Server (frootai-mcp)
- Azure CLI
- Python runtime
 
## Your MCP Servers
{"servers": {"frootai": {"command": "npx", "args": ["frootai-mcp"]}}}
 
## Rules
- Use values from config files, never hardcode
- Hand off to reviewer.agent.md when done

Key difference from instructions: Instructions are passive (always on). Agents are active (invoked for specific tasks) and have their own tool bindings.

Primitive 4: Skills

Files: .github/skills/<name>/SKILL.md

Skills are self-contained folders with instructions + scripts + references. They’re progressively loaded — Copilot reads the description first, loads the full instructions only when relevant.

.github/skills/
├── deploy-azure/
│   ├── SKILL.md        # Description + prerequisites + references
│   └── deploy.sh       # Executable script
├── evaluate/
│   ├── SKILL.md
│   └── eval.py
└── tune/
    ├── SKILL.md
    └── tune-config.sh

Use for: Repeatable runbooks, incident triage, IaC risk analysis, deployment procedures.

Progressive loading: Copilot reads SKILL.md header first. If the user’s question matches the skill’s domain, Copilot loads the full content. This saves tokens and reduces noise.

F4.5 Layer 3 — Enforcement & Automation

Primitive 5: Hooks

Files: .github/hooks/*.json

Hooks are deterministic shell commands triggered at lifecycle events. They enforce policies before, during, and after tool execution.

Three lifecycle events:

{
  "hooks": [
    {
      "event": "preToolUse",
      "match": { "toolName": "write_file", "pathPattern": "**/*.env" },
      "action": "deny_if_contains",
      "patterns": ["api_key", "secret", "password"],
      "message": "BLOCKED: Detected secrets. Use Key Vault."
    }
  ]
}

Why hooks are critical: They make the AI agent safe by default. Without hooks, an agent can write secrets to code, modify guardrails, or deploy to production. With hooks, you enforce policies deterministically — no LLM judgment involved.

Primitive 6: Agentic Workflows

Files: .github/workflows/*.md (compiled to YAML GitHub Actions)

Agentic workflows are natural language automation that compiles to GitHub Actions. They define AI-driven CI/CD pipelines.

<!-- .github/workflows/ai-review.md -->
# AI Code Review
 
## Trigger
On pull request to main branch.
 
## Steps
1. Validate TuneKit configs
2. Run evaluation pipeline
3. Post review summary as PR comment
4. Block merge if critical issues found

Key insight: The .md file is the source of truth — it’s human-readable and AI-editable. It compiles to YAML for GitHub Actions.

Use for: PR review automation, deployment pipelines, scheduled maintenance, issue triage.

Permissions: Always read-only unless explicitly elevated. Principle of least privilege.

F4.6 Layer 4 — Distribution (Plugins)

Primitive 7: Plugins

Plugins bundle agents + skills + commands into a distributable package. Two distribution modes:

{
  "plugin": "frootai-enterprise-rag",
  "version": "1.0.0",
  "agents": ["builder", "reviewer", "tuner"],
  "skills": ["deploy-azure", "evaluate", "tune"],
  "prompts": ["deploy", "test", "review", "evaluate"],
  "hooks": ["guardrails"],
  "mcp_servers": ["frootai"]
}

plugin.json declares what’s inside. Consumers install the plugin → get all agents, skills, prompts, and hooks preconfigured.

FrootAI solution plays can ship a plugin manifest with their agentic assets. The repository currently contains 101 numbered solution-play catalog directories. Treat each play’s checked-in manifest and specification as authoritative because maturity and packaged assets vary by play. Browse them at github.com/frootai/frootai/tree/main/solution-plays .

F4.7 FrootAI’s Solution-Play Implementation

FrootAI projects a consistent .github agentic structure into solution plays. The following is the target structure; use the individual play manifest to determine which assets a specific play currently ships:

solution-plays/01-enterprise-rag/
├── .github/
│   ├── copilot-instructions.md          # Layer 1
│   ├── instructions/
│   │   ├── azure-coding.instructions.md  # Coding standards
│   │   ├── rag-patterns.instructions.md  # RAG-specific rules
│   │   └── security.instructions.md      # Security conventions
│   ├── prompts/
│   │   ├── deploy.prompt.md              # /deploy
│   │   ├── test.prompt.md                # /test
│   │   ├── review.prompt.md              # /review
│   │   └── evaluate.prompt.md            # /evaluate
│   ├── agents/
│   │   ├── builder.agent.md              # Implementation
│   │   ├── reviewer.agent.md             # Code review
│   │   └── tuner.agent.md                # TuneKit verification
│   ├── skills/
│   │   ├── deploy-azure/SKILL.md         # Azure deployment
│   │   ├── evaluate/SKILL.md             # Quality evaluation
│   │   └── tune/SKILL.md                 # Config validation
│   ├── hooks/
│   │   └── guardrails.json               # Policy enforcement
│   └── workflows/
│       ├── ai-review.md                  # PR review automation
│       └── ai-deploy.md                  # Deployment automation

Do not infer an ecosystem-wide file count from this example. Generated projections and play maturity change independently; validate a play from its manifest and quality-gate evidence.

Agent Chain (per play)

F4.8 Decision Guide — When to Use What

Layering Strategy

Start here → Layer 1 (Instructions)
↓ Need slash commands? → Layer 2 (Prompts)
↓ Need specialist agents? → Layer 2 (Agents + Skills)
↓ Need safety enforcement? → Layer 3 (Hooks)
↓ Need CI/CD automation? → Layer 3 (Workflows)
↓ Need to share across repos? → Layer 4 (Plugins)

F4.9 Building Your Own .github Agentic OS

Step 1: Start with Instructions (5 minutes)

Create .github/copilot-instructions.md:

You are working on [PROJECT NAME].
Framework: [e.g., Python FastAPI + Azure]
Always use managed identity. Never hardcode secrets.
Follow the patterns in docs/architecture.md.

Step 2: Add Modular Instructions (10 minutes)

Create .github/instructions/ with domain-specific files.

Step 3: Add Prompt Files (15 minutes)

Create .github/prompts/ for common tasks: deploy, test, review.

Step 4: Add Agents (20 minutes)

Create .github/agents/ with specialist personas for your codebase.

Step 5: Add Skills (20 minutes)

Create .github/skills/ with self-contained runbooks.

Step 6: Add Hooks (10 minutes)

Create .github/hooks/guardrails.json with preToolUse policies.

Step 7: Add Workflows (15 minutes)

Create .github/workflows/ with AI-driven CI/CD.

Total time: ~95 minutes for a complete .github agentic OS.

Or use FrootAI: run FrootAI: Initialize DevKit → get all 19 files instantly.

Applied Scenario: Compose a Governed Repository Assistant

Situation: A team wants Copilot to apply architecture rules, invoke a repeatable review capability, and run deterministic checks before merge.

Composition: Put durable rules in scoped instructions, package the review method as a skill, use an agent only when tool choice or orchestration is required, and keep deterministic enforcement in hooks or workflows.

Review gate: Every primitive must declare a narrow purpose, source owner, applicable paths, required tools, and a failure mode that does not silently bypass governance.

Validation: Test one matching file, one non-matching file, one denied tool call, and one workflow failure before distributing the package.

Key Takeaways

1. The .github folder is now an operating system — 7 primitives, 4 layers, one repo.
2. Layer 1 (Instructions) is the foundation — always start here. Passive memory that applies to every prompt.
3. Layer 2 (Prompts, Agents, Skills) adds on-demand power — specialist personas, slash commands, self-contained logic.
4. Layer 3 (Hooks, Workflows) adds safety — deterministic enforcement and AI-driven CI/CD.
5. Layer 4 (Plugins) enables distribution — share agent stacks across repos and marketplace.
6. Agent chaining (builder → reviewer → tuner) creates quality gates that catch issues before production.
7. Hooks are non-negotiable — preToolUse gates prevent secrets in code, policy violations, and unsafe operations.
8. FrootAI ships 380 files — 19 per solution play × 20 plays. Ready-to-use .github agentic OS for 20 AI solutions.

Next: O2: AI Agents & Agent Framework for deep agent architecture | O3: MCP, Tools & Function Calling for MCP server patterns

Knowledge Check

1. When should guidance be an instruction instead of an agent?

2. What belongs in a deterministic workflow rather than a prompt?

3. Why should primitives reference canonical knowledge instead of copying it?