# heilcheng/awesome-agent-skills architecture

> Architecture diagram of the GitHub repository heilcheng/awesome-agent-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/heilcheng/awesome-agent-skills
- Repository: https://github.com/heilcheng/awesome-agent-skills

## Overview

1. **Repository shape**
   - This repo is primarily a documentation-and-directory site for “Agent Skill Index.”
   - The actual application lives in `website/`; the root README files are multilingual project docs, not runtime code.

2. **Deployment/runtime boundary**
   - The site is a **Next.js** app in `website/`, configured for deployment on **Vercel** via `vercel.json` and `website/vercel.json`.
   - There is no visible backend service, database, or API layer in the tree; the site is effectively a static/presentation app.

3. **Top-level page flow**
   - `website/src/app/page.tsx` is the main entry point and likely composes the homepage from many section components.
   - `website/src/app/layout.tsx` provides the application shell around all routes, with global CSS from `globals.css`.

4. **Layout and chrome**
   - Shared frame components live in `website/src/components/`:
     - `Navbar.tsx` and `Footer.tsx` for site-wide navigation and footer
     - `LayoutShell.tsx` for the overall page structure
     - `Providers.tsx` for app-level context wrappers
   - These are the main “chrome” boundaries around the content sections.

5. **Content model: section-based landing page**
   - Most of the site’s information is split into self-contained homepage sections in `website/src/components/sections/`.
   - Examples include:
     - `Hero`, `WhatIsIt`, `HowItWorks`
     - `CompatibleAgents`, `SkillDirectory`, `Trends`
     - `UsingSkills`, `CreatingSkills`, `Tutorials`, `FAQ`, `Contributing`
   - For an architecture diagram, these are best treated as presentation modules feeding one central homepage.

6. **Navigation and sidebar behavior**
   - `WikiSidebar.tsx` and `SidebarContext.tsx` suggest a side-navigation or “wiki-style” content navigator.
   - That implies a client-side state boundary for opening/closing or tracking sidebar state, separate from the static page content.

7. **Internationalization**
   - `website/src/lib/i18n.tsx` indicates client-side or component-level language support.
   - The repo also contains translated root READMEs (`README.es.md`, `README.ja.md`, `README.ko.md`, `README.zh-CN.md`, `README.zh-TW.md`), so multilingual content is a first-class concern even if the app itself is mostly static.

8. **Assets and media**
   - Visual assets are stored under `assets/` at the repo root and `website/public/assets/`.
   - The site uses these for banners, marketplace screenshots, and other marketing visuals; they are static files served directly by the web app.

9. **Interactive widgets and animations**
   - `website/src/components/animations/SnakeGame.tsx` is a notable interactive/animated feature.
   - This is the clearest “dynamic” UI boundary in an otherwise content-heavy site, likely isolated so the homepage can stay mostly static while still including playful or engaging elements.

10. **Technology boundaries**
    - The app is built with **TypeScript**, **React**, **Next.js App Router**, and standard web styling via `globals.css` and PostCSS.
    - `eslint.config.mjs`, `postcss.config.mjs`, and `tsconfig.json` show normal frontend tooling, but they do not introduce separate runtime subsystems.

11. **External integrations**
    - The site heavily links out to external resources rather than calling internal services:
      - agent-skill.co live directory
      - GitHub repositories for skills
      - vendor docs for Claude, Codex, Copilot, Gemini, Vercel, etc.
    - Architecturally, these are outbound knowledge/navigation edges, not data dependencies.

12. **Suggested diagram framing**
    - Draw the repo as a **single Next.js presentation app** with:
      - an app shell
      - a homepage assembled from modular content sections
      - a small amount of client-side UI state for sidebar/i18n/animations
      - static assets and outbound links
    - Do not model any persistence, job processing, or backend APIs, because none are evident in this repository.

Main entry points: [`website/src/app/page.tsx`](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/app/page.tsx) (Home page), [`website/src/components/LayoutShell.tsx`](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/LayoutShell.tsx) (Page frame), [`website/package.json`](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/package.json) (Website app), [`website/src/app/layout.tsx`](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/app/layout.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Repo docs"]
  node_root_readme["README set<br/>docs<br/>[README.md]"]
  node_contributing_root["Contributing<br/>docs<br/>[CONTRIBUTING.md]"]
end

subgraph group_webapp["Next.js site"]
  node_next_app["Website app<br/>nextjs app<br/>[package.json]"]
  node_app_page["Home page<br/>route entry<br/>[page.tsx]"]
  node_app_layout["App shell<br/>layout<br/>[layout.tsx]"]
  node_layout_shell["Page frame<br/>chrome<br/>[LayoutShell.tsx]"]
  node_navbar["Navbar<br/>navigation<br/>[Navbar.tsx]"]
  node_footer["Footer<br/>navigation<br/>[Footer.tsx]"]
  node_vercel_deploy["Vercel<br/>deployment config<br/>[vercel.json]"]
end

subgraph group_content["Homepage content"]
  node_intro_sections["Intro sections<br/>content bundle<br/>[Hero.tsx]"]
  node_directory_sections["Directory sections<br/>content bundle<br/>[SkillDirectory.tsx]"]
  node_guide_sections["Guide sections<br/>content bundle<br/>[UsingSkills.tsx]"]
  node_community_sections["Community sections<br/>content bundle<br/>[FAQ.tsx]"]
  node_timeline_section(("Adoption timeline<br/>content section"))
end

subgraph group_state["Client state"]
  node_providers["Providers<br/>context<br/>[Providers.tsx]"]
  node_sidebar_ctx["Sidebar state<br/>[SidebarContext.tsx]"]
  node_wiki_sidebar["Wiki sidebar<br/>navigation<br/>[WikiSidebar.tsx]"]
  node_i18n["i18n<br/>language support<br/>[i18n.tsx]"]
  node_snake_game(("Snake game<br/>interactive widget<br/>[SnakeGame.tsx]"))
end

subgraph group_static["Static media"]
  node_static_assets[("Assets<br/>static media")]
end

node_root_readme -->|"points to"| node_next_app
node_contributing_root -.->|"supports"| node_root_readme
node_next_app -->|"uses"| node_app_layout
node_next_app -->|"renders"| node_app_page
node_app_layout -->|"wraps"| node_layout_shell
node_app_layout -->|"wraps"| node_providers
node_layout_shell -->|"includes"| node_navbar
node_layout_shell -->|"includes"| node_footer
node_layout_shell -.->|"includes"| node_wiki_sidebar
node_wiki_sidebar -->|"uses"| node_sidebar_ctx
node_app_page -->|"composes"| node_intro_sections
node_app_page -->|"composes"| node_directory_sections
node_app_page -->|"composes"| node_guide_sections
node_app_page -->|"composes"| node_community_sections
node_app_page -.->|"includes"| node_timeline_section
node_app_page -.->|"embeds"| node_snake_game
node_app_page -->|"localizes"| node_i18n
node_intro_sections -->|"uses"| node_static_assets
node_directory_sections -->|"uses"| node_static_assets
node_guide_sections -.->|"uses"| node_static_assets
node_community_sections -->|"localizes"| node_i18n
node_vercel_deploy -->|"deploys"| node_next_app

click node_root_readme "https://github.com/heilcheng/awesome-agent-skills/blob/main/README.md"
click node_contributing_root "https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md"
click node_next_app "https://github.com/heilcheng/awesome-agent-skills/blob/main/website/package.json"
click node_app_page "https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/app/page.tsx"
click node_app_layout "https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/app/layout.tsx"
click node_layout_shell "https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/LayoutShell.tsx"
click node_navbar "https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Navbar.tsx"
click node_footer "https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx"
click node_providers "https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Providers.tsx"
click node_sidebar_ctx "https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/lib/SidebarContext.tsx"
click node_wiki_sidebar "https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/WikiSidebar.tsx"
click node_i18n "https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/lib/i18n.tsx"
click node_intro_sections "https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Hero.tsx"
click node_directory_sections "https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/SkillDirectory.tsx"
click node_guide_sections "https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx"
click node_community_sections "https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/FAQ.tsx"
click node_timeline_section "https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/AdoptionTimeline.tsx"
click node_snake_game "https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/animations/SnakeGame.tsx"
click node_static_assets "https://github.com/heilcheng/awesome-agent-skills/tree/main/assets"
click node_vercel_deploy "https://github.com/heilcheng/awesome-agent-skills/blob/main/vercel.json"

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_root_readme,node_contributing_root toneBlue
class node_next_app,node_app_page,node_app_layout,node_layout_shell,node_navbar,node_footer,node_vercel_deploy toneAmber
class node_intro_sections,node_directory_sections,node_guide_sections,node_community_sections,node_timeline_section toneMint
class node_providers,node_sidebar_ctx,node_wiki_sidebar,node_i18n,node_snake_game toneRose
class node_static_assets toneIndigo
```

## Components

### Repo docs

Multilingual project documentation at the repository root.

- [README set](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.md): docs · Main project overview plus translated root README files. · `README.md`
- [Contributing](https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md): docs · Repository contribution guidelines. · `CONTRIBUTING.md`

### Next.js site

Primary application under website/.

- [Website app](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/package.json): nextjs app · Primary Next.js App Router application. · `website/package.json`
- [Home page](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/app/page.tsx): route entry · Main homepage entry that assembles the landing experience. · `website/src/app/page.tsx`
- [App shell](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/app/layout.tsx): layout · Global application layout wrapping all routes. · `website/src/app/layout.tsx`
- [Page frame](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/LayoutShell.tsx): chrome · Overall page structure around content and navigation. · `website/src/components/LayoutShell.tsx`
- [Navbar](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Navbar.tsx): navigation · Top-level site navigation. · `website/src/components/Navbar.tsx`
- [Footer](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx): navigation · Site footer and closing links. · `website/src/components/Footer.tsx`
- [Vercel](https://github.com/heilcheng/awesome-agent-skills/blob/main/vercel.json): deployment config · Deployment configuration for Vercel. · `vercel.json`

### Homepage content

Section-based landing page modules composed into the homepage.

- [Intro sections](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Hero.tsx): content bundle · Hero and explanatory sections that introduce the project. · `website/src/components/sections/Hero.tsx`
- [Directory sections](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/SkillDirectory.tsx): content bundle · Discovery and catalog sections for skills and compatible agents. · `website/src/components/sections/SkillDirectory.tsx`
- [Guide sections](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx): content bundle · How-to sections for using and creating skills. · `website/src/components/sections/UsingSkills.tsx`
- [Community sections](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/FAQ.tsx): content bundle · FAQ, contribution, quality, and endorsement content. · `website/src/components/sections/FAQ.tsx`
- [Adoption timeline](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/AdoptionTimeline.tsx): content section · Trend or timeline view showing adoption over time. · `website/src/components/sections/AdoptionTimeline.tsx`

### Client state

Small client-side boundaries for navigation, language, and interactive UI.

- [Providers](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Providers.tsx): context · App-wide context wrappers. · `website/src/components/Providers.tsx`
- [Sidebar state](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/lib/SidebarContext.tsx): state · Client-side sidebar open/close and navigation state. · `website/src/lib/SidebarContext.tsx`
- [Wiki sidebar](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/WikiSidebar.tsx): navigation · Sidebar or wiki-style content navigator. · `website/src/components/WikiSidebar.tsx`
- [i18n](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/lib/i18n.tsx): language support · Component-level language selection and translation helpers. · `website/src/lib/i18n.tsx`
- [Snake game](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/animations/SnakeGame.tsx): interactive widget · Animated or playful interactive component embedded in the site. · `website/src/components/animations/SnakeGame.tsx`

### Static media

Images and other assets served directly by the site.

- [Assets](https://github.com/heilcheng/awesome-agent-skills/tree/main/assets): static media · Repository and public static assets used by the site. · `assets`

## Connections

- README set → Website app: points to · Root documentation introduces the website as the main runnable project.
- Contributing → README set: supports · Contribution guidance complements the project docs.
- Website app → App shell: uses · The app is wrapped by the global layout.
- Website app → Home page: renders · Homepage route is the main entry point.
- App shell → Page frame: wraps · Layout delegates page structure to the shared shell.
- App shell → Providers: wraps · Global providers establish app-wide context.
- Page frame → Navbar: includes · Shared shell includes site navigation.
- Page frame → Footer: includes · Shared shell includes the footer.
- Page frame → Wiki sidebar: includes · Shell can host the sidebar navigator.
- Wiki sidebar → Sidebar state: uses · Sidebar UI is driven by client-side state.
- Home page → Intro sections: composes · Homepage is assembled from introductory sections.
- Home page → Directory sections: composes · Homepage includes directory and discovery content.
- Home page → Guide sections: composes · Homepage includes usage and authoring guidance.
- Home page → Community sections: composes · Homepage includes FAQ and contribution content.
- Home page → Adoption timeline: includes · Homepage can surface adoption or trend information.
- Home page → Snake game: embeds · A distinct interactive widget lives alongside the static sections.
- Home page → i18n: localizes · Homepage content participates in multilingual rendering.
- Intro sections → Assets: uses · Sections consume static marketing and banner assets.
- Directory sections → Assets: uses · Directory views use screenshots and icon assets.
- Guide sections → Assets: uses · Guidance sections reference illustrative assets.
- Community sections → i18n: localizes · Community-facing copy is language-aware.
- Vercel → Website app: deploys · Root deployment config targets the Next.js site.