# appleboy/skills architecture

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

- Interactive diagram: https://gitdiagram.com/appleboy/skills
- Repository: https://github.com/appleboy/skills

## Overview

1. This repository is not an application runtime; it is a **collection of Claude Code skills/plugins** packaged for distribution through a Claude marketplace. The architecture is content-first: mostly manifests and Markdown skill definitions rather than executable code.

2. The **root marketplace layer** is `.claude-plugin/marketplace.json`, which acts as the catalog entrypoint for the whole repo. It is the boundary a Claude Code client uses to discover installable plugins under `plugins/`.

3. Each item under `plugins/` is an **independent plugin unit** with its own `.claude-plugin/plugin.json` manifest and one skill document in `skills/<skill-name>/SKILL.md`. That makes each plugin a separately installable, loosely coupled module.

4. The plugin set is organized by workflow stage:
   - `commit-message` for conventional commit generation from staged git changes
   - `classify-change` for deciding leaf vs core change scope
   - `plan-feature` for pre-coding feature planning and `plan.md` handoff
   - `pr-prepare` for PR description drafting and checklisting
   - `code-review` and `copilot-review` for review workflows
   - `prompt-audit` for improving prompts against a rubric

5. The **skill files are the behavioral core**. `SKILL.md` likely contains the instructions, heuristics, and output format the Claude agent follows. In diagram terms, this is where the “logic” lives, but it is declarative content rather than code.

6. The main data flow is:
   **user invokes a plugin in Claude Code → marketplace resolves plugin manifest → plugin manifest points to the skill document → Claude loads the skill instructions and applies them to the current context**.
   The inputs are typically git state, PR diffs, prompts, or repository context; the outputs are commit messages, plans, reviews, or rewritten prompts.

7. A key architectural boundary is between **classification/planning skills** and **execution/review skills**. `classify-change` and `plan-feature` decide scope and approach before work starts, while `code-review`, `copilot-review`, and `pr-prepare` operate after code or PR content exists.

8. Another boundary is **human-facing artifact generation**. Several skills are designed to produce concrete handoff artifacts outside the plugin system: commit messages, PR descriptions, review comments, and `plan.md`. The repo is therefore a workflow accelerator, not a source of product business logic.

9. Tooling and release infrastructure are lightweight but important:
   - `.github/workflows/goreleaser.yml` and `.goreleaser.yaml` handle packaging/release automation
   - `.github/workflows/security.yml` runs security scanning
   - Dependabot and funding metadata support maintenance
   These files suggest the repo is distributed as a versioned plugin bundle.

10. The external dependency is primarily the **Claude Code plugin ecosystem** itself, with GitHub as the hosting/release platform. There is no sign of a backend service, database, or API layer; the runtime is the user’s Claude Code environment consuming packaged skill definitions from this repository.

Main entry points: [`.claude-plugin/marketplace.json`](https://github.com/appleboy/skills/blob/main/.claude-plugin/marketplace.json) (Marketplace), [`.github/workflows/goreleaser.yml`](https://github.com/appleboy/skills/blob/main/.github/workflows/goreleaser.yml) (Release Workflow), [`plugins/commit-message/.claude-plugin/plugin.json`](https://github.com/appleboy/skills/blob/main/plugins/commit-message/.claude-plugin/plugin.json) (Commit Plugin), [`plugins/classify-change/.claude-plugin/plugin.json`](https://github.com/appleboy/skills/blob/main/plugins/classify-change/.claude-plugin/plugin.json) (Classify Plugin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Catalog"]
  node_marketplace["Marketplace<br/>catalog manifest<br/>[marketplace.json]"]
  node_readme["README<br/>overview doc<br/>[README.md]"]
end

subgraph group_plugins["Plugins"]
  node_commit_manifest["Commit Plugin<br/>plugin manifest<br/>[plugin.json]"]
  node_commit_skill["Commit Skill<br/>skill instructions<br/>[SKILL.md]"]
  node_classify_manifest["Classify Plugin<br/>plugin manifest<br/>[plugin.json]"]
  node_classify_skill["Classify Skill<br/>skill instructions<br/>[SKILL.md]"]
  node_plan_manifest["Plan Plugin<br/>plugin manifest<br/>[plugin.json]"]
  node_plan_skill["Plan Skill<br/>skill instructions<br/>[SKILL.md]"]
  node_pr_manifest["PR Plugin<br/>plugin manifest<br/>[plugin.json]"]
  node_pr_skill["PR Skill<br/>skill instructions<br/>[SKILL.md]"]
  node_review_manifest["Review Plugin<br/>plugin manifest<br/>[plugin.json]"]
  node_review_skill["Review Skill<br/>skill instructions<br/>[SKILL.md]"]
  node_copilot_manifest["Copilot Plugin<br/>plugin manifest<br/>[plugin.json]"]
  node_copilot_skill["Copilot Skill<br/>skill instructions<br/>[SKILL.md]"]
  node_audit_manifest["Audit Plugin<br/>plugin manifest<br/>[plugin.json]"]
  node_audit_skill["Audit Skill<br/>skill instructions<br/>[SKILL.md]"]
end

subgraph group_release["Release"]
  node_goreleaser["Release Config<br/>[.goreleaser.yaml]"]
  node_release_workflow["Release Workflow<br/>ci workflow<br/>[goreleaser.yml]"]
  node_security_workflow["Security Workflow<br/>ci workflow<br/>[security.yml]"]
end

node_marketplace -->|"discovers"| node_commit_manifest
node_marketplace -->|"discovers"| node_classify_manifest
node_marketplace -->|"discovers"| node_plan_manifest
node_marketplace -->|"discovers"| node_pr_manifest
node_marketplace -->|"discovers"| node_review_manifest
node_marketplace -->|"discovers"| node_copilot_manifest
node_marketplace -->|"discovers"| node_audit_manifest
node_commit_manifest -->|"loads"| node_commit_skill
node_classify_manifest -->|"loads"| node_classify_skill
node_plan_manifest -->|"loads"| node_plan_skill
node_pr_manifest -->|"loads"| node_pr_skill
node_review_manifest -->|"loads"| node_review_skill
node_copilot_manifest -->|"loads"| node_copilot_skill
node_audit_manifest -->|"loads"| node_audit_skill
node_classify_skill -->|"feeds"| node_plan_skill
node_plan_skill -->|"handoff"| node_pr_skill
node_review_skill -->|"informs"| node_pr_skill
node_copilot_skill -->|"extends"| node_review_skill
node_goreleaser -->|"drives"| node_release_workflow
node_release_workflow -->|"publishes"| node_marketplace
node_release_workflow -->|"packages"| node_commit_manifest
node_release_workflow -->|"packages"| node_classify_manifest
node_release_workflow -->|"packages"| node_plan_manifest
node_release_workflow -->|"packages"| node_pr_manifest
node_release_workflow -->|"packages"| node_review_manifest
node_release_workflow -->|"packages"| node_copilot_manifest
node_release_workflow -->|"packages"| node_audit_manifest
node_security_workflow -->|"scans"| node_marketplace
node_readme -->|"documents"| node_marketplace

click node_marketplace "https://github.com/appleboy/skills/blob/main/.claude-plugin/marketplace.json"
click node_readme "https://github.com/appleboy/skills/blob/main/README.md"
click node_commit_manifest "https://github.com/appleboy/skills/blob/main/plugins/commit-message/.claude-plugin/plugin.json"
click node_commit_skill "https://github.com/appleboy/skills/blob/main/plugins/commit-message/skills/commit-message/SKILL.md"
click node_classify_manifest "https://github.com/appleboy/skills/blob/main/plugins/classify-change/.claude-plugin/plugin.json"
click node_classify_skill "https://github.com/appleboy/skills/blob/main/plugins/classify-change/skills/classify-change/SKILL.md"
click node_plan_manifest "https://github.com/appleboy/skills/blob/main/plugins/plan-feature/.claude-plugin/plugin.json"
click node_plan_skill "https://github.com/appleboy/skills/blob/main/plugins/plan-feature/skills/plan-feature/SKILL.md"
click node_pr_manifest "https://github.com/appleboy/skills/blob/main/plugins/pr-prepare/.claude-plugin/plugin.json"
click node_pr_skill "https://github.com/appleboy/skills/blob/main/plugins/pr-prepare/skills/pr-prepare/SKILL.md"
click node_review_manifest "https://github.com/appleboy/skills/blob/main/plugins/code-review/.claude-plugin/plugin.json"
click node_review_skill "https://github.com/appleboy/skills/blob/main/plugins/code-review/skills/code-review/SKILL.md"
click node_copilot_manifest "https://github.com/appleboy/skills/blob/main/plugins/copilot-review/.claude-plugin/plugin.json"
click node_copilot_skill "https://github.com/appleboy/skills/blob/main/plugins/copilot-review/skills/copilot-review/SKILL.md"
click node_audit_manifest "https://github.com/appleboy/skills/blob/main/plugins/prompt-audit/.claude-plugin/plugin.json"
click node_audit_skill "https://github.com/appleboy/skills/blob/main/plugins/prompt-audit/skills/prompt-audit/SKILL.md"
click node_goreleaser "https://github.com/appleboy/skills/blob/main/.goreleaser.yaml"
click node_release_workflow "https://github.com/appleboy/skills/blob/main/.github/workflows/goreleaser.yml"
click node_security_workflow "https://github.com/appleboy/skills/blob/main/.github/workflows/security.yml"

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_marketplace,node_readme toneBlue
class node_commit_manifest,node_commit_skill,node_classify_manifest,node_classify_skill,node_plan_manifest,node_plan_skill,node_pr_manifest,node_pr_skill,node_review_manifest,node_review_skill,node_copilot_manifest,node_copilot_skill,node_audit_manifest,node_audit_skill toneAmber
class node_goreleaser,node_release_workflow,node_security_workflow toneMint
```

## Components

### Catalog

Marketplace entrypoint and repository documentation.

- [Marketplace](https://github.com/appleboy/skills/blob/main/.claude-plugin/marketplace.json): catalog manifest · Top-level plugin catalog entry used by Claude Code to discover installable plugins. · `.claude-plugin/marketplace.json`
- [README](https://github.com/appleboy/skills/blob/main/README.md): overview doc · Human-facing repository overview and usage guidance. · `README.md`

### Plugins

Independently installable Claude Code skill packages.

- [Commit Plugin](https://github.com/appleboy/skills/blob/main/plugins/commit-message/.claude-plugin/plugin.json): plugin manifest · Package definition for commit message generation. · `plugins/commit-message/.claude-plugin/plugin.json`
- [Commit Skill](https://github.com/appleboy/skills/blob/main/plugins/commit-message/skills/commit-message/SKILL.md): skill instructions · Behavioral instructions for generating conventional commit messages from staged changes. · `plugins/commit-message/skills/commit-message/SKILL.md`
- [Classify Plugin](https://github.com/appleboy/skills/blob/main/plugins/classify-change/.claude-plugin/plugin.json): plugin manifest · Package definition for change-scope classification. · `plugins/classify-change/.claude-plugin/plugin.json`
- [Classify Skill](https://github.com/appleboy/skills/blob/main/plugins/classify-change/skills/classify-change/SKILL.md): skill instructions · Instructions for deciding leaf-versus-core change scope. · `plugins/classify-change/skills/classify-change/SKILL.md`
- [Plan Plugin](https://github.com/appleboy/skills/blob/main/plugins/plan-feature/.claude-plugin/plugin.json): plugin manifest · Package definition for feature planning and plan handoff. · `plugins/plan-feature/.claude-plugin/plugin.json`
- [Plan Skill](https://github.com/appleboy/skills/blob/main/plugins/plan-feature/skills/plan-feature/SKILL.md): skill instructions · Instructions for pre-coding feature planning and producing plan.md. · `plugins/plan-feature/skills/plan-feature/SKILL.md`
- [PR Plugin](https://github.com/appleboy/skills/blob/main/plugins/pr-prepare/.claude-plugin/plugin.json): plugin manifest · Package definition for pull request preparation. · `plugins/pr-prepare/.claude-plugin/plugin.json`
- [PR Skill](https://github.com/appleboy/skills/blob/main/plugins/pr-prepare/skills/pr-prepare/SKILL.md): skill instructions · Instructions for drafting PR descriptions and checklists. · `plugins/pr-prepare/skills/pr-prepare/SKILL.md`
- [Review Plugin](https://github.com/appleboy/skills/blob/main/plugins/code-review/.claude-plugin/plugin.json): plugin manifest · Package definition for code review workflows. · `plugins/code-review/.claude-plugin/plugin.json`
- [Review Skill](https://github.com/appleboy/skills/blob/main/plugins/code-review/skills/code-review/SKILL.md): skill instructions · Instructions for reviewing code and changes against repository expectations. · `plugins/code-review/skills/code-review/SKILL.md`
- [Copilot Plugin](https://github.com/appleboy/skills/blob/main/plugins/copilot-review/.claude-plugin/plugin.json): plugin manifest · Package definition for Copilot-assisted review workflows. · `plugins/copilot-review/.claude-plugin/plugin.json`
- [Copilot Skill](https://github.com/appleboy/skills/blob/main/plugins/copilot-review/skills/copilot-review/SKILL.md): skill instructions · Instructions for Copilot-focused review and commentary. · `plugins/copilot-review/skills/copilot-review/SKILL.md`
- [Audit Plugin](https://github.com/appleboy/skills/blob/main/plugins/prompt-audit/.claude-plugin/plugin.json): plugin manifest · Package definition for prompt auditing and improvement. · `plugins/prompt-audit/.claude-plugin/plugin.json`
- [Audit Skill](https://github.com/appleboy/skills/blob/main/plugins/prompt-audit/skills/prompt-audit/SKILL.md): skill instructions · Instructions for improving prompts against a rubric. · `plugins/prompt-audit/skills/prompt-audit/SKILL.md`

### Release

Packaging and maintenance automation.

- [Release Config](https://github.com/appleboy/skills/blob/main/.goreleaser.yaml): release config · goreleaser configuration for packaging and publishing the plugin bundle. · `.goreleaser.yaml`
- [Release Workflow](https://github.com/appleboy/skills/blob/main/.github/workflows/goreleaser.yml): ci workflow · GitHub Actions workflow that runs the release packaging pipeline. · `.github/workflows/goreleaser.yml`
- [Security Workflow](https://github.com/appleboy/skills/blob/main/.github/workflows/security.yml): ci workflow · GitHub Actions workflow for security scanning. · `.github/workflows/security.yml`

## Connections

- Marketplace → Commit Plugin: discovers · The catalog lists the commit-message plugin as installable.
- Marketplace → Classify Plugin: discovers · The catalog lists the classify-change plugin as installable.
- Marketplace → Plan Plugin: discovers · The catalog lists the plan-feature plugin as installable.
- Marketplace → PR Plugin: discovers · The catalog lists the pr-prepare plugin as installable.
- Marketplace → Review Plugin: discovers · The catalog lists the code-review plugin as installable.
- Marketplace → Copilot Plugin: discovers · The catalog lists the copilot-review plugin as installable.
- Marketplace → Audit Plugin: discovers · The catalog lists the prompt-audit plugin as installable.
- Commit Plugin → Commit Skill: loads · The plugin manifest points to the skill instructions.
- Classify Plugin → Classify Skill: loads · The plugin manifest points to the skill instructions.
- Plan Plugin → Plan Skill: loads · The plugin manifest points to the skill instructions.
- PR Plugin → PR Skill: loads · The plugin manifest points to the skill instructions.
- Review Plugin → Review Skill: loads · The plugin manifest points to the skill instructions.
- Copilot Plugin → Copilot Skill: loads · The plugin manifest points to the skill instructions.
- Audit Plugin → Audit Skill: loads · The plugin manifest points to the skill instructions.
- Classify Skill → Plan Skill: feeds · Scope classification informs feature planning before coding starts.
- Plan Skill → PR Skill: handoff · Planning artifacts can flow into pull request preparation.
- Review Skill → PR Skill: informs · Review findings can shape PR descriptions and checklists.
- Copilot Skill → Review Skill: extends · Copilot review is a specialized review workflow.
- Release Config → Release Workflow: drives · The release config is exercised by the release workflow.
- Release Workflow → Marketplace: publishes · The release pipeline packages and publishes the marketplace catalog entry.
- Release Workflow → Commit Plugin: packages · The release pipeline bundles plugin manifests for distribution.
- Release Workflow → Classify Plugin: packages · The release pipeline bundles plugin manifests for distribution.
- Release Workflow → Plan Plugin: packages · The release pipeline bundles plugin manifests for distribution.
- Release Workflow → PR Plugin: packages · The release pipeline bundles plugin manifests for distribution.
- Release Workflow → Review Plugin: packages · The release pipeline bundles plugin manifests for distribution.
- Release Workflow → Copilot Plugin: packages · The release pipeline bundles plugin manifests for distribution.
- Release Workflow → Audit Plugin: packages · The release pipeline bundles plugin manifests for distribution.
- Security Workflow → Marketplace: scans · Security automation covers the repository's distributable catalog entry and contents.
- README → Marketplace: documents · The README explains the marketplace and plugin bundle to humans.