How proficientlyjobs/proficiently-claude-skills works
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: plugin.json plugin.json · setup/SKILL.md Setup · job-search/SKILL.md Job search · network-scan/SKILL.md Network scan
Components 21
Plugin surface
Installable Claude plugin metadata and entrypoints.
- plugin.json · Defines the Claude plugin entrypoint and namespace exposure.
.claude-plugin/plugin.json - marketplace.json · Describes marketplace discovery and install metadata.
.claude-plugin/marketplace.json
Shared guidance
Cross-skill reference rules and reusable templates.
- Shared refs · Canonical rules for fit scoring, priorities, prerequisites, browser setup, ATS patterns, and data layout.
shared/references - Profile template · Reusable work-history and profile format used across skills.
shared/templates/profile.md
Skill workflows
Commandable workflow boundaries executed by Claude.
- Setup · Seeds persistent user state and initializes the local data layout.
skills/setup/SKILL.md - Job search · Finds and ranks jobs using profile, preferences, resume, and shared fit rules.
skills/job-search/SKILL.md - Tailor resume · Creates job-specific resume variants inside a per-job folder.
skills/tailor-resume/SKILL.md - Cover letter · Generates job-specific cover letters using shared guidance and job context.
skills/cover-letter/SKILL.md - Network scan · Checks contacts against companies and resolves careers pages for warm opportunities.
skills/network-scan/SKILL.md - Apply · Submits applications through browser-based ATS forms using saved artifacts and data.
skills/apply/SKILL.md - Telegram 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-assisted execution environment required for interactive automation.
- ATS sites · Application systems such as Greenhouse, Lever, and Workday.
- LinkedIn · Source of contacts and networking context for warm leads.
- Telegram · Chat interface used to send commands into the workflow system.
Local state
Persistent user data stored outside the repository.
- ~/.proficiently · External local filesystem boundary holding resumes, preferences, job folders, contacts, and logs.
- Resume · Base resume used by onboarding and downstream tailoring.
- Preferences · User-defined job search and application preferences.
- Job history · Record of searched, evaluated, and tracked jobs.
- Per-job folder · Folder-scoped artifact set for one target job, including posting, resume, letter, and application log.
- Contacts · Imported LinkedIn contacts used for warm-intro and company matching.
Connections 39
- 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.