# proficientlyjobs/proficiently-claude-skills architecture

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

- Interactive diagram: https://gitdiagram.com/proficientlyjobs/proficiently-claude-skills
- Repository: https://github.com/proficientlyjobs/proficiently-claude-skills

## Overview

1. **What this repo is**
   - This is a **Claude Code plugin** package, not a traditional application codebase.
   - Its architecture is primarily **instruction-driven**: each “skill” is a commandable workflow that Claude executes using Markdown guidance and shared reference docs.

2. **Plugin boundary and distribution**
   - The `.claude-plugin/` directory is the installable plugin surface.
   - `plugin.json` and `marketplace.json` define how Claude discovers, installs, and exposes the plugin via the Proficiently namespace.
   - The repo is meant to be consumed through Claude Cowork / Claude Code, not run as a standalone service.

3. **Primary functional subsystems**
   - The repo is organized into **skills** that map directly to user commands:
     - setup
     - job-search
     - tailor-resume
     - cover-letter
     - network-scan
     - apply
     - jobsearch-telegram
   - Each skill is a separate workflow boundary with its own `SKILL.md` and supporting assets/scripts.

4. **Shared policy and reference layer**
   - `shared/references/` contains cross-cutting architecture rules and canonical behavior:
     - fit scoring
     - priority hierarchy
     - prerequisites
     - browser setup
     - ATS patterns
     - data directory resolution
   - `shared/templates/profile.md` provides a reusable work-history/profile format.
   - These files act as the **common contract** across skills so they behave consistently.

5. **Onboarding as the data-seeding workflow**
   - `/proficiently:setup` is the root workflow that initializes personal state.
   - It collects or creates the user’s resume, preferences, optional LinkedIn contacts, and work-history profile.
   - This skill establishes the persistent local data layout under `~/.proficiently/`, which all other skills depend on.

6. **Local user-data store as the main state boundary**
   - The repo itself is mostly static instructions; **persistent state lives outside the repo** in `~/.proficiently/`.
   - That directory stores the user’s resume, profile, preferences, job history, contacts, career URL cache, application data, and per-job folders.
   - The architecture centers on this local filesystem as the shared state bus between workflows.

7. **Job search and ranking pipeline**
   - `/proficiently:job-search` reads the user’s profile, preferences, and resume to find matching jobs.
   - It applies the shared fit-scoring and matching rules, then records results into `job-history.md`.
   - It also performs network-aware filtering by identifying companies where the user has contacts.

8. **Per-job artifact generation**
   - `/proficiently:tailor-resume` and `/proficiently:cover-letter` create job-specific artifacts inside a dedicated folder under `~/.proficiently/jobs/`.
   - Each job folder becomes the unit of work, typically holding:
     - the saved posting
     - a tailored resume
     - a cover letter
     - later, an application log
   - This makes the application process **folder-scoped and traceable**.

9. **Application automation boundary**
   - `/proficiently:apply` is the browser-facing workflow.
   - It targets ATS systems called out in the repo: **Greenhouse, Lever, and Workday**.
   - The repo’s browser prerequisites and ATS-pattern references suggest this skill is responsible for navigating forms, filling repeated fields, and using previously saved application data.

10. **Network-scan as a sourcing amplifier**
   - `/proficiently:network-scan` uses imported LinkedIn contacts to inspect companies for openings.
   - It maintains its own history log and a cached `company-careers.json` map of careers page URLs.
   - This is a distinct discovery path from general job search: it starts from people/network data rather than keyword search.

11. **Telegram skill as a remote control layer**
   - `/proficiently:jobsearch-telegram` is a headless interaction layer for triggering the same job-search/apply flows from chat.
   - Architecturally, it is an alternate control plane rather than a new business subsystem.
   - The README implies it can run continuously in a loop, enabling asynchronous command intake.

12. **Browser automation and external dependencies**
   - The plugin depends on **Claude in Chrome** plus Chrome itself for browser-assisted automation.
   - This is important architecturally because some workflows are not purely text generation; they require a browser session and extension-based control.
   - External services involved include LinkedIn/contact import and ATS-hosted job application systems.

13. **Cross-skill orchestration model**
   - The workflows are intentionally chained:
     - setup creates state
     - job-search finds candidates
     - tailor-resume and cover-letter generate application assets
     - apply submits them
     - network-scan adds warm-intro opportunities
   - The repo is designed so each skill can be run independently, but the real value comes from the shared data directory and consistent artifact handoff.

14. **Diagramming takeaway**
   - A useful architecture diagram would show:
     - **Claude Code / Claude Cowork** as the execution host
     - **skill modules** as command workflows
     - **shared references/templates** as policy inputs
     - **`~/.proficiently/`** as persistent local state
     - **browser/Chrome + ATS sites** as external automation targets
     - **LinkedIn / Telegram** as optional external intake channels
   - The dominant architectural pattern is a **local-state, instruction-driven workflow system** rather than a server-based app.

Main entry points: [`.claude-plugin/plugin.json`](https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/.claude-plugin/plugin.json) (plugin.json), [`skills/setup/SKILL.md`](https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/setup/SKILL.md) (Setup), [`skills/job-search/SKILL.md`](https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/job-search/SKILL.md) (Job search), [`skills/network-scan/SKILL.md`](https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/network-scan/SKILL.md) (Network scan)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_plugin["Plugin surface"]
  node_node_plugin_json["plugin.json<br/>plugin manifest<br/>[plugin.json]"]
  node_node_marketplace_json["marketplace.json<br/>distribution metadata<br/>[marketplace.json]"]
end

subgraph group_group_shared["Shared guidance"]
  node_node_references["Shared refs<br/>policy docs"]
  node_node_profile_template["Profile template<br/>[profile.md]"]
end

subgraph group_group_skills["Skill workflows"]
  node_node_setup["Setup<br/>onboarding workflow<br/>[SKILL.md]"]
  node_node_job_search["Job search<br/>discovery workflow<br/>[SKILL.md]"]
  node_node_tailor_resume["Tailor resume<br/>document workflow<br/>[SKILL.md]"]
  node_node_cover_letter["Cover letter<br/>document workflow<br/>[SKILL.md]"]
  node_node_network_scan["Network scan<br/>sourcing workflow<br/>[SKILL.md]"]
  node_node_apply["Apply<br/>browser workflow<br/>[SKILL.md]"]
  node_node_telegram["Telegram control<br/>remote control<br/>[SKILL.md]"]
end

subgraph group_group_external["External systems"]
  node_node_browser(("Claude in Chrome<br/>browser control"))
  node_node_ats{{"ATS sites<br/>external target"}}
  node_node_linkedin{{"LinkedIn<br/>external source"}}
  node_node_telegram_ext{{"Telegram<br/>external channel"}}
end

subgraph group_group_state["Local state"]
  node_node_local_state[("~/.proficiently<br/>persistent store")]
  node_node_resume["Resume<br/>user input"]
  node_node_preferences["Preferences<br/>user profile"]
  node_node_job_history["Job history<br/>application log"]
  node_node_job_folder[("Per-job folder<br/>job workspace")]
  node_node_contacts["Contacts<br/>network data"]
end

node_node_plugin_json -->|"exposes"| node_node_setup
node_node_plugin_json -->|"exposes"| node_node_job_search
node_node_plugin_json -->|"exposes"| node_node_tailor_resume
node_node_plugin_json -->|"exposes"| node_node_cover_letter
node_node_plugin_json -->|"exposes"| node_node_network_scan
node_node_plugin_json -->|"exposes"| node_node_apply
node_node_plugin_json -->|"exposes"| node_node_telegram
node_node_marketplace_json -->|"distributes"| node_node_plugin_json
node_node_references -->|"guides"| node_node_setup
node_node_references -->|"guides"| node_node_job_search
node_node_references -->|"guides"| node_node_tailor_resume
node_node_references -->|"guides"| node_node_cover_letter
node_node_references -->|"guides"| node_node_apply
node_node_profile_template -->|"structures"| node_node_setup
node_node_setup -->|"creates"| node_node_local_state
node_node_setup -->|"collects"| node_node_resume
node_node_setup -->|"collects"| node_node_preferences
node_node_setup -.->|"optionally imports"| node_node_contacts
node_node_setup -->|"initializes"| node_node_job_history
node_node_job_search -->|"reads/writes"| node_node_local_state
node_node_job_search -->|"records"| node_node_job_history
node_node_job_search -.->|"filters by network"| node_node_contacts
node_node_job_search -->|"selects"| node_node_job_folder
node_node_tailor_resume -->|"writes"| node_node_job_folder
node_node_cover_letter -->|"writes"| node_node_job_folder
node_node_tailor_resume -->|"reads"| node_node_resume
node_node_cover_letter -->|"reads"| node_node_job_folder
node_node_network_scan -->|"reads"| node_node_contacts
node_node_network_scan -->|"records"| node_node_job_history
node_node_network_scan -->|"caches"| node_node_local_state
node_node_network_scan -->|"uses"| node_node_linkedin
node_node_network_scan -.->|"enriches"| node_node_job_folder
node_node_apply -->|"consumes"| node_node_job_folder
node_node_apply -->|"drives"| node_node_browser
node_node_apply -->|"submits to"| node_node_ats
node_node_telegram -->|"triggers"| node_node_job_search
node_node_telegram -->|"triggers"| node_node_apply
node_node_telegram -->|"uses"| node_node_telegram_ext
node_node_browser -->|"operates on"| node_node_ats

click node_node_plugin_json "https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/.claude-plugin/plugin.json"
click node_node_marketplace_json "https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/.claude-plugin/marketplace.json"
click node_node_references "https://github.com/proficientlyjobs/proficiently-claude-skills/tree/main/shared/references"
click node_node_profile_template "https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/shared/templates/profile.md"
click node_node_setup "https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/setup/SKILL.md"
click node_node_job_search "https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/job-search/SKILL.md"
click node_node_tailor_resume "https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/tailor-resume/SKILL.md"
click node_node_cover_letter "https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/cover-letter/SKILL.md"
click node_node_network_scan "https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/network-scan/SKILL.md"
click node_node_apply "https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/apply/SKILL.md"
click node_node_telegram "https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/jobsearch-telegram/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_node_plugin_json,node_node_marketplace_json toneBlue
class node_node_references,node_node_profile_template toneAmber
class node_node_setup,node_node_job_search,node_node_tailor_resume,node_node_cover_letter,node_node_network_scan,node_node_apply,node_node_telegram toneMint
class node_node_browser,node_node_ats,node_node_linkedin,node_node_telegram_ext toneRose
class node_node_local_state,node_node_resume,node_node_preferences,node_node_job_history,node_node_job_folder,node_node_contacts toneIndigo
```

## Components

### Plugin surface

Installable Claude plugin metadata and entrypoints.

- [plugin.json](https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/.claude-plugin/plugin.json): plugin manifest · Defines the Claude plugin entrypoint and namespace exposure. · `.claude-plugin/plugin.json`
- [marketplace.json](https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/.claude-plugin/marketplace.json): distribution metadata · Describes marketplace discovery and install metadata. · `.claude-plugin/marketplace.json`

### Shared guidance

Cross-skill reference rules and reusable templates.

- [Shared refs](https://github.com/proficientlyjobs/proficiently-claude-skills/tree/main/shared/references): policy docs · Canonical rules for fit scoring, priorities, prerequisites, browser setup, ATS patterns, and data layout. · `shared/references`
- [Profile template](https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/shared/templates/profile.md): template · Reusable work-history and profile format used across skills. · `shared/templates/profile.md`

### Skill workflows

Commandable workflow boundaries executed by Claude.

- [Setup](https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/setup/SKILL.md): onboarding workflow · Seeds persistent user state and initializes the local data layout. · `skills/setup/SKILL.md`
- [Job search](https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/job-search/SKILL.md): discovery workflow · Finds and ranks jobs using profile, preferences, resume, and shared fit rules. · `skills/job-search/SKILL.md`
- [Tailor resume](https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/tailor-resume/SKILL.md): document workflow · Creates job-specific resume variants inside a per-job folder. · `skills/tailor-resume/SKILL.md`
- [Cover letter](https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/cover-letter/SKILL.md): document workflow · Generates job-specific cover letters using shared guidance and job context. · `skills/cover-letter/SKILL.md`
- [Network scan](https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/network-scan/SKILL.md): sourcing workflow · Checks contacts against companies and resolves careers pages for warm opportunities. · `skills/network-scan/SKILL.md`
- [Apply](https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/apply/SKILL.md): browser workflow · Submits applications through browser-based ATS forms using saved artifacts and data. · `skills/apply/SKILL.md`
- [Telegram control](https://github.com/proficientlyjobs/proficiently-claude-skills/blob/main/skills/jobsearch-telegram/SKILL.md): remote control · Headless chat-driven control plane for triggering job search and application flows. · `skills/jobsearch-telegram/SKILL.md`

### External systems

Non-repo systems used for control, browsing, and applications.

- **Claude in Chrome**: browser control · Browser-assisted execution environment required for interactive automation.
- **ATS sites**: external target · Application systems such as Greenhouse, Lever, and Workday.
- **LinkedIn**: external source · Source of contacts and networking context for warm leads.
- **Telegram**: external channel · Chat interface used to send commands into the workflow system.

### Local state

Persistent user data stored outside the repository.

- **~/.proficiently**: persistent store · External local filesystem boundary holding resumes, preferences, job folders, contacts, and logs.
- **Resume**: user input · Base resume used by onboarding and downstream tailoring.
- **Preferences**: user profile · User-defined job search and application preferences.
- **Job history**: application log · Record of searched, evaluated, and tracked jobs.
- **Per-job folder**: job workspace · Folder-scoped artifact set for one target job, including posting, resume, letter, and application log.
- **Contacts**: network data · Imported LinkedIn contacts used for warm-intro and company matching.

## Connections

- plugin.json → Setup: exposes · Plugin manifest makes the onboarding workflow available.
- plugin.json → Job search: exposes · Plugin manifest makes job-search workflow available.
- plugin.json → Tailor resume: exposes · Plugin manifest makes resume tailoring workflow available.
- plugin.json → Cover letter: exposes · Plugin manifest makes cover-letter workflow available.
- plugin.json → Network scan: exposes · Plugin manifest makes network-scan workflow available.
- plugin.json → Apply: exposes · Plugin manifest makes application workflow available.
- plugin.json → Telegram control: exposes · Plugin manifest makes Telegram control workflow available.
- marketplace.json → plugin.json: distributes · Marketplace metadata points to the plugin package.
- Shared refs → Setup: guides · Shared rules shape onboarding and data initialization.
- Shared refs → Job search: guides · Shared fit scoring and matching rules govern discovery.
- Shared refs → Tailor resume: guides · Shared rules inform tailoring decisions.
- Shared refs → Cover letter: guides · Shared rules inform letter generation.
- Shared refs → Apply: guides · Shared ATS and browser guidance inform application automation.
- Profile template → Setup: structures · Profile template shapes the initialized work-history profile.
- Setup → ~/.proficiently: creates · Onboarding seeds the persistent local data store.
- Setup → Resume: collects · Setup gathers or creates the base resume.
- Setup → Preferences: collects · Setup gathers preferences for later matching.
- Setup → Contacts: optionally imports · Setup may import LinkedIn contacts for later network workflows.
- Setup → Job history: initializes · Setup establishes the initial history and tracking artifacts.
- Job search → ~/.proficiently: reads/writes · Job search consumes and updates persistent user state.
- Job search → Job history: records · Job search writes evaluated results into history.
- Job search → Contacts: filters by network · Job search can surface companies with known contacts.
- Job search → Per-job folder: selects · Promising jobs become per-job workspaces.
- Tailor resume → Per-job folder: writes · Tailored resume is saved inside the job workspace.
- Cover letter → Per-job folder: writes · Cover letter is saved inside the job workspace.
- Tailor resume → Resume: reads · Tailoring starts from the base resume.
- Cover letter → Per-job folder: reads · Letter generation uses the saved job context.
- Network scan → Contacts: reads · Network scan starts from imported contacts.
- Network scan → Job history: records · Network scan maintains its own discovery history.
- Network scan → ~/.proficiently: caches · Network scan stores careers-page URL cache and related artifacts.
- Network scan → LinkedIn: uses · Contacts and networking context come from LinkedIn.
- Network scan → Per-job folder: enriches · Company discoveries can feed job-specific workspaces.
- Apply → Per-job folder: consumes · Application flow uses saved posting and generated artifacts.
- Apply → Claude in Chrome: drives · Apply is browser-facing automation.
- Apply → ATS sites: submits to · Applications are sent to ATS systems.
- Telegram control → Job search: triggers · Telegram control can invoke job-search flows.
- Telegram control → Apply: triggers · Telegram control can invoke application flows.
- Telegram control → Telegram: uses · Telegram skill receives commands through chat.
- Claude in Chrome → ATS sites: operates on · Chrome-based browser control interacts with ATS forms.
