# alterlab-ieu/alterlab-fc-skills architecture

> Architecture diagram of the GitHub repository alterlab-ieu/alterlab-fc-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alterlab-ieu/alterlab-fc-skills
- Repository: https://github.com/alterlab-ieu/alterlab-fc-skills

## Overview

1. This repository is a **prompt library**, not an application runtime. Its core product is a set of **72 standalone Markdown skill files** that instruct Claude how to act as domain-specific autonomous agents.

2. The top-level structure is intentionally simple: `README.md` explains the catalog, `CLAUDE.md` defines repository-wide instructions and required format rules, `package.json` and `scripts/validate.js` support validation, and the real content lives under `skills/`.

3. The `skills/` tree is the main subsystem boundary. It is organized into **six departments**, each with 12 skills:
   - `pra` — PR & Advertising
   - `cdm` — Cinema & Digital Media
   - `nmc` — New Media & Communication
   - `genai` — Generative AI Production
   - `vcd` — Visual Communication Design
   - `rma` — Research Methods & Academic Writing

4. Each individual skill is isolated in its own folder, and the only required artifact inside is `SKILL.md`. That makes every skill a self-contained unit that can be loaded independently into Claude Projects or Claude Code.

5. The content model is consistent across the repo: each skill is a **structured prompt** that defines role, workflow, frameworks, and output expectations. The README describes the common agentic cycle: **research → context reading → creation → self-review → presentation**.

6. The architecture is therefore **catalog + pack + atomic skill**:
   - catalog layer: README indexes the system
   - department layer: groups skills by communication discipline
   - skill layer: one prompt file per use case

7. `CLAUDE.md` is an important governance boundary. The README explicitly says all skills follow the **AlterLab NEXUS skill architecture**, and `CLAUDE.md` contains the mandatory template and formatting rules that contributors must follow when adding or improving skills.

8. Validation is handled as a lightweight quality-control pipeline. The `scripts/validate.js` script is the repo’s executable check, and `.github/workflows/validate.yml` runs that validation in CI so broken structure or malformed skill files can be caught before merge.

9. GitHub is used as the distribution and contribution surface rather than as an app backend. Issue templates and a pull request template support skill requests and improvements, while the workflow enforces consistency across contributions.

10. The README positions the skills as usable in two main ways: through **Claude Projects** by uploading `SKILL.md` files, or through **Claude Code CLI** by pointing Claude at the repository. So the repo’s output boundary is external: Claude consumes these files as instructions.

11. There are no databases, services, or compiled artifacts in the repository. The architecture is documentation-driven and file-based, with the main data flow being: contributor edits `SKILL.md` → validation checks the repository rules → Claude loads the skill file as an agent prompt.

12. For an architecture diagram, the key nodes are: **repository docs and governance**, **department folders**, **atomic skill files**, **validation script**, and **GitHub Actions CI**. The arrows are mostly from contributors into skills, validation over the skill tree, and Claude consuming the Markdown files as executable instruction sets.

Main entry points: [`skills`](https://github.com/alterlab-ieu/alterlab-fc-skills/tree/main/skills) (Skills), [`scripts/validate.js`](https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/scripts/validate.js) (Validate), [`skills/pra/alterlab-pra-copywriter/SKILL.md`](https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/skills/pra/alterlab-pra-copywriter/SKILL.md) (Copywriter), [`skills/cdm/alterlab-cdm-screenwriter/SKILL.md`](https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/skills/cdm/alterlab-cdm-screenwriter/SKILL.md) (Screenwriter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_governance["Governance"]
  node_claude(("Claude<br/>consumer"))
  node_readme["README<br/>catalog<br/>[README.md]"]
  node_claude_md["CLAUDE.md<br/>policy<br/>[CLAUDE.md]"]
end

subgraph group_quality["Quality Control"]
  node_package_json["package.json<br/>manifest<br/>[package.json]"]
  node_validate_js["Validate<br/>checker<br/>[validate.js]"]
  node_workflow["CI Check<br/>[validate.yml]"]
end

subgraph group_contribution["Contribution Surface"]
  node_contributors(("Contributors<br/>actor"))
  node_issue_templates["Issue Forms<br/>template-set<br/>[ISSUE_TEMPLATE]"]
  node_pr_template["PR Template"]
end

subgraph group_skills["Skills Library"]
  node_skills_root["Skills"]
  node_pra["PRA<br/>department"]
  node_cdm["CDM<br/>department"]
  node_nmc["NMC<br/>department"]
  node_genai["GenAI<br/>department"]
  node_vcd["VCD<br/>department"]
  node_rma["RMA<br/>department"]
  node_pra_skill["Copywriter<br/>atomic skill<br/>[SKILL.md]"]
  node_cdm_skill["Screenwriter<br/>atomic skill<br/>[SKILL.md]"]
  node_nmc_skill["Web Strategist<br/>atomic skill<br/>[SKILL.md]"]
  node_genai_skill["Text-to-Image<br/>atomic skill<br/>[SKILL.md]"]
  node_vcd_skill["Layout Designer<br/>atomic skill<br/>[SKILL.md]"]
  node_rma_skill["Academic Writer<br/>atomic skill<br/>[SKILL.md]"]
end

node_contributors -->|"request skill"| node_issue_templates
node_contributors -->|"submit changes"| node_pr_template
node_contributors -->|"edit prompt"| node_pra_skill
node_contributors -->|"edit prompt"| node_cdm_skill
node_contributors -->|"edit prompt"| node_nmc_skill
node_contributors -->|"edit prompt"| node_genai_skill
node_contributors -->|"edit prompt"| node_vcd_skill
node_contributors -->|"edit prompt"| node_rma_skill
node_readme -->|"defines rules"| node_claude_md
node_readme -->|"indexes library"| node_skills_root
node_claude_md -->|"enforces format"| node_skills_root
node_skills_root -->|"contains"| node_pra
node_skills_root -->|"contains"| node_cdm
node_skills_root -->|"contains"| node_nmc
node_skills_root -->|"contains"| node_genai
node_skills_root -->|"contains"| node_vcd
node_skills_root -->|"contains"| node_rma
node_pra -->|"packs"| node_pra_skill
node_cdm -->|"packs"| node_cdm_skill
node_nmc -->|"packs"| node_nmc_skill
node_genai -->|"packs"| node_genai_skill
node_vcd -->|"packs"| node_vcd_skill
node_rma -->|"packs"| node_rma_skill
node_package_json -->|"wires script"| node_validate_js
node_validate_js -->|"checks"| node_skills_root
node_workflow -->|"runs"| node_validate_js
node_issue_templates -->|"feeds changes"| node_skills_root
node_pr_template -->|"aligns with"| node_workflow
node_pra_skill -->|"loaded by"| node_claude
node_cdm_skill -->|"loaded by"| node_claude
node_nmc_skill -->|"loaded by"| node_claude
node_genai_skill -->|"loaded by"| node_claude
node_vcd_skill -->|"loaded by"| node_claude
node_rma_skill -->|"loaded by"| node_claude

click node_readme "https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/README.md"
click node_claude_md "https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/CLAUDE.md"
click node_package_json "https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/package.json"
click node_validate_js "https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/scripts/validate.js"
click node_workflow "https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/.github/workflows/validate.yml"
click node_issue_templates "https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/.github/ISSUE_TEMPLATE"
click node_pr_template "https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/.github/PULL_REQUEST_TEMPLATE.md"
click node_skills_root "https://github.com/alterlab-ieu/alterlab-fc-skills/tree/main/skills"
click node_pra "https://github.com/alterlab-ieu/alterlab-fc-skills/tree/main/skills/pra"
click node_cdm "https://github.com/alterlab-ieu/alterlab-fc-skills/tree/main/skills/cdm"
click node_nmc "https://github.com/alterlab-ieu/alterlab-fc-skills/tree/main/skills/nmc"
click node_genai "https://github.com/alterlab-ieu/alterlab-fc-skills/tree/main/skills/genai"
click node_vcd "https://github.com/alterlab-ieu/alterlab-fc-skills/tree/main/skills/vcd"
click node_rma "https://github.com/alterlab-ieu/alterlab-fc-skills/tree/main/skills/rma"
click node_pra_skill "https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/skills/pra/alterlab-pra-copywriter/SKILL.md"
click node_cdm_skill "https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/skills/cdm/alterlab-cdm-screenwriter/SKILL.md"
click node_nmc_skill "https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/skills/nmc/alterlab-nmc-web-strategist/SKILL.md"
click node_genai_skill "https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/skills/genai/alterlab-genai-text-to-image/SKILL.md"
click node_vcd_skill "https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/skills/vcd/alterlab-vcd-layout-designer/SKILL.md"
click node_rma_skill "https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/skills/rma/alterlab-rma-academic-writer/SKILL.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_claude,node_readme,node_claude_md toneBlue
class node_package_json,node_validate_js,node_workflow toneAmber
class node_contributors,node_issue_templates,node_pr_template toneMint
class node_skills_root,node_pra,node_cdm,node_nmc,node_genai,node_vcd,node_rma,node_pra_skill,node_cdm_skill,node_nmc_skill,node_genai_skill,node_vcd_skill,node_rma_skill toneRose
```

## Components

### Governance

Repository-wide guidance, cataloging, and contribution rules.

- **Claude**: consumer · Claude consumes the skill markdown as executable instructions.
- [README](https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/README.md): catalog · Explains the skill library, usage, and repository structure. · `README.md`
- [CLAUDE.md](https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/CLAUDE.md): policy · Repository-wide instructions and mandatory skill format rules. · `CLAUDE.md`

### Quality Control

Validation and CI checks for skill structure and formatting.

- [package.json](https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/package.json): manifest · Project metadata and script wiring for validation. · `package.json`
- [Validate](https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/scripts/validate.js): checker · Executable repository validation for skills and structure. · `scripts/validate.js`
- [CI Check](https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/.github/workflows/validate.yml): ci · GitHub Actions workflow that runs validation on changes. · `.github/workflows/validate.yml`

### Contribution Surface

GitHub entry points for proposing and improving skills.

- **Contributors**: actor · People adding or improving skills.
- [Issue Forms](https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/.github/ISSUE_TEMPLATE): template-set · Issue templates for new skills and improvements. · `.github/ISSUE_TEMPLATE`
- [PR Template](https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/.github/PULL_REQUEST_TEMPLATE.md): template · Pull request template for contributing skill changes. · `.github/PULL_REQUEST_TEMPLATE.md`

### Skills Library

Departmented library of atomic prompt files.

- [Skills](https://github.com/alterlab-ieu/alterlab-fc-skills/tree/main/skills): library · Top-level library of standalone prompt skills. · `skills`
- [PRA](https://github.com/alterlab-ieu/alterlab-fc-skills/tree/main/skills/pra): department · PR and advertising skills. · `skills/pra`
- [CDM](https://github.com/alterlab-ieu/alterlab-fc-skills/tree/main/skills/cdm): department · Cinema and digital media skills. · `skills/cdm`
- [NMC](https://github.com/alterlab-ieu/alterlab-fc-skills/tree/main/skills/nmc): department · New media and communication skills. · `skills/nmc`
- [GenAI](https://github.com/alterlab-ieu/alterlab-fc-skills/tree/main/skills/genai): department · Generative AI production skills. · `skills/genai`
- [VCD](https://github.com/alterlab-ieu/alterlab-fc-skills/tree/main/skills/vcd): department · Visual communication design skills. · `skills/vcd`
- [RMA](https://github.com/alterlab-ieu/alterlab-fc-skills/tree/main/skills/rma): department · Research methods and academic writing skills. · `skills/rma`
- [Copywriter](https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/skills/pra/alterlab-pra-copywriter/SKILL.md): atomic skill · Representative standalone skill prompt; each department contains similar isolated SKILL.md files. · `skills/pra/alterlab-pra-copywriter/SKILL.md`
- [Screenwriter](https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/skills/cdm/alterlab-cdm-screenwriter/SKILL.md): atomic skill · Representative standalone skill prompt; each department contains similar isolated SKILL.md files. · `skills/cdm/alterlab-cdm-screenwriter/SKILL.md`
- [Web Strategist](https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/skills/nmc/alterlab-nmc-web-strategist/SKILL.md): atomic skill · Representative standalone skill prompt; each department contains similar isolated SKILL.md files. · `skills/nmc/alterlab-nmc-web-strategist/SKILL.md`
- [Text-to-Image](https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/skills/genai/alterlab-genai-text-to-image/SKILL.md): atomic skill · Representative standalone skill prompt; each department contains similar isolated SKILL.md files. · `skills/genai/alterlab-genai-text-to-image/SKILL.md`
- [Layout Designer](https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/skills/vcd/alterlab-vcd-layout-designer/SKILL.md): atomic skill · Representative standalone skill prompt; each department contains similar isolated SKILL.md files. · `skills/vcd/alterlab-vcd-layout-designer/SKILL.md`
- [Academic Writer](https://github.com/alterlab-ieu/alterlab-fc-skills/blob/main/skills/rma/alterlab-rma-academic-writer/SKILL.md): atomic skill · Representative standalone skill prompt; each department contains similar isolated SKILL.md files. · `skills/rma/alterlab-rma-academic-writer/SKILL.md`

## Connections

- Contributors → Issue Forms: request skill · Propose new skills or improvements through GitHub forms.
- Contributors → PR Template: submit changes · Open pull requests with the repository contribution template.
- Contributors → Copywriter: edit prompt · Contributors maintain individual skill prompts.
- Contributors → Screenwriter: edit prompt · Contributors maintain individual skill prompts.
- Contributors → Web Strategist: edit prompt · Contributors maintain individual skill prompts.
- Contributors → Text-to-Image: edit prompt · Contributors maintain individual skill prompts.
- Contributors → Layout Designer: edit prompt · Contributors maintain individual skill prompts.
- Contributors → Academic Writer: edit prompt · Contributors maintain individual skill prompts.
- README → CLAUDE.md: defines rules · README points to repository-wide architecture and formatting governance.
- README → Skills: indexes library · README describes the catalog and how to use the skills.
- CLAUDE.md → Skills: enforces format · Repository rules constrain how skills are authored.
- Skills → PRA: contains · The skills library is split into departments.
- Skills → CDM: contains · The skills library is split into departments.
- Skills → NMC: contains · The skills library is split into departments.
- Skills → GenAI: contains · The skills library is split into departments.
- Skills → VCD: contains · The skills library is split into departments.
- Skills → RMA: contains · The skills library is split into departments.
- PRA → Copywriter: packs · Each department contains many isolated SKILL.md prompts.
- CDM → Screenwriter: packs · Each department contains many isolated SKILL.md prompts.
- NMC → Web Strategist: packs · Each department contains many isolated SKILL.md prompts.
- GenAI → Text-to-Image: packs · Each department contains many isolated SKILL.md prompts.
- VCD → Layout Designer: packs · Each department contains many isolated SKILL.md prompts.
- RMA → Academic Writer: packs · Each department contains many isolated SKILL.md prompts.
- package.json → Validate: wires script · package metadata exposes the validation command.
- Validate → Skills: checks · Validation inspects skill structure and file conventions.
- CI Check → Validate: runs · CI executes the validation script before merge.
- Issue Forms → Skills: feeds changes · Template-driven requests lead to new or improved skills.
- PR Template → CI Check: aligns with · Pull requests are evaluated by the validation pipeline.
- Copywriter → Claude: loaded by · Skill markdown is consumed as instructions by Claude.
- Screenwriter → Claude: loaded by · Skill markdown is consumed as instructions by Claude.
- Web Strategist → Claude: loaded by · Skill markdown is consumed as instructions by Claude.
- Text-to-Image → Claude: loaded by · Skill markdown is consumed as instructions by Claude.
- Layout Designer → Claude: loaded by · Skill markdown is consumed as instructions by Claude.
- Academic Writer → Claude: loaded by · Skill markdown is consumed as instructions by Claude.