UK GDAD PCF Agent Skills: How Markdown Files Became Multi-Agent Job Descriptions

A Show HN post introduces a practical approach to multi-agent systems: using the UK Government Digital and Data Profession Capability Framework (GDAD PCF) as agent skill definitions. Instead of generic “researcher” or “coder” agents, the system maps to real job roles like Software Developer, Test Analyst, and Incident Manager. Each role is a markdown file containing structured skill descriptions.

The author reports that this approach produces results comparable to popular multi-agent generic systems, with a key advantage: teams understand the system immediately because it uses standardized government job titles and skill taxonomies that map to existing organizational structures.

Why Markdown Files Work as Agent Definitions

Markdown is readable enough for executives to audit and structured enough for orchestrators to parse. For novice users, it’s copy-paste into ChatGPT. For orchestration systems like Claude Code, it’s structured context that can be loaded programmatically.

The UK GDAD PCF provides:

Predefined role names (e.g., “Technical architect”, “DevOps engineer”)
Documented skill clusters per role
Naming conventions that map to organizational charts

This eliminates the cold-start problem of defining agent capabilities from scratch. You’re not inventing a taxonomy; you’re adopting one that already has buy-in from government and enterprise teams.

The specificity constrains the agent’s scope and sets clearer expectations for tool selection and output format. A generic prompt says “You are a helpful coding assistant.” A PCF-based prompt says “You are a Software Developer (GDAD PCF). Your skills include: Availability and capacity management, Development process optimization, Modern standards approach…”

Architecture: Markdown as Configuration Primitive

The system treats each markdown file as a skill manifest. The author describes using Claude Code with swarms of subagents. Based on this description, a plausible orchestration flow would include:

Load phase: Orchestrator reads markdown files from a directory structure (e.g., roles/software-developer.md, roles/test-analyst.md)
Parse phase: Extract role name, skill list, and any embedded examples or constraints
Invocation phase: When a task arrives, the orchestrator selects one or more roles based on task type
Context injection: The markdown content becomes part of the system prompt for the selected agent(s)

Role vs. skill boundary:

Concept	Implementation	State
Role	Markdown file defining a job title and skill set	Stateless; reloaded per invocation
Skill	Individual capability listed within a role	No separate process; just prompt context
Agent instance	Runtime process or API call with role context injected	Ephemeral; spawned per task

Each markdown file does not spawn a subprocess. Instead, it provides the context window for an LLM call. If you need three agents (Software Developer, Test Analyst, Incident Manager) working on the same problem, you make three separate LLM calls with different markdown contexts.

Overlap handling:

When multiple roles share skills (e.g., both Software Developer and DevOps Engineer need “Modern standards approach”), the system duplicates skill descriptions per role. This is intentional: each role interprets the skill through its own lens. A Software Developer applies modern standards to code structure; a DevOps Engineer applies them to deployment pipelines.

Observability and Failure Modes

Logging requirements:

Log which role was invoked for each task
Track token usage per role (some roles may have longer skill descriptions)
Record which skills from the markdown were actually referenced in the output

Common failure modes:

Failure	Cause	Mitigation
Role mismatch	Task routed to wrong role (e.g., asking Test Analyst to write code)	Add a routing agent that maps tasks to roles before invocation
Skill drift	UK GDAD PCF updates but markdown files are stale	Version-control markdown files; monitor UK GDAD PCF changelog for updates
Context overflow	Markdown file + task description exceeds token limit	Summarize skill descriptions or split into core/extended skills
Coordination deadlock	Two agents waiting for each other’s output	Define explicit dependency graph; use timeouts

Version control strategy:

Treat markdown files like infrastructure-as-code:

roles/
  software-developer.md
  test-analyst.md
  incident-manager.md
versions/
  2026-05-01/
    software-developer.md
  2026-01-15/
    software-developer.md

When the UK updates the PCF, diff the new version against your current markdown files. Use semantic versioning for breaking changes (e.g., a skill is removed or renamed).

Deployment Shape

The author explicitly describes orchestration with Claude Code and subagent swarms. The markdown-as-config design also enables a simpler copy-paste workflow for novice users:

Copy-paste workflow (inferred from design):

User opens a role markdown file in the repository
Copies entire file
Pastes into ChatGPT with task description
Gets role-constrained response

No infrastructure needed. The markdown file is the entire deployment artifact.

Orchestration workflow:

Clone the repository to your orchestration server
Mount roles/ directory as a volume in your container
Orchestrator reads markdown files on startup or per-request
Inject role context into LLM API calls

Scaling considerations:

Each markdown file is ~2-5KB. Loading 50 roles adds negligible latency.
If you’re spawning hundreds of agents per second, cache parsed markdown in memory.
For distributed systems, sync the roles/ directory to all orchestrator nodes (rsync, S3, or bake into container image).

For production multi-agent systems, shared context between agents typically requires patterns like Redis for distributed state, message queues (RabbitMQ, Kafka) for async coordination, or vector stores (Pinecone, Weaviate) if agents need semantic search over prior outputs. Refer to the GitHub repository for the author’s specific implementation details.

Token Budget Implications

Injecting full markdown files into system prompts consumes context window budget. A typical role definition might use 500-1500 tokens. For high-throughput systems:

Pre-parse markdown files at startup
Cache skill descriptions in memory
Inject only relevant skills based on task type
Monitor token usage per role to identify bloat

If you’re hitting context limits, split role definitions into core skills (always included) and extended skills (loaded on demand).

Technical Verdict

Use this approach when:

Governance or compliance teams need to audit agent capabilities against standardized job descriptions
Non-technical stakeholders (executives, legal, procurement) need readable agent definitions that map to organizational roles
You’re working in regulated environments where AI agent responsibilities must align with documented job functions
Your tasks map cleanly to existing job functions (software development, testing, incident response)

Avoid this approach when:

Your domain lacks a standardized role taxonomy (you’ll spend more time maintaining custom markdown than you save in clarity)
You have sub-100ms response time requirements for real-time chat interfaces where markdown parsing latency is unacceptable (pre-parse and cache, or use a different format)
Your agents need complex stateful coordination beyond simple context injection
Token budget is tight and you can’t afford to inject 1000+ tokens of role context per agent invocation

The primary value is governance clarity. Legal and compliance teams can audit agent capabilities against standardized job descriptions. This makes the approach particularly valuable in regulated environments or organizations with strict AI governance requirements. If you don’t need that level of auditability, simpler prompt engineering may suffice.