Terminal
Terminal/Skill
Builds a self-contained org chart page of a company's C-suite and VP leaders from Clay search, with reporting lines marked as inferred.
By Clay
Works with
npx skills add clay-run/clay-skill-creator --skill clay-org-chart-builderThe insight: Clay's people search returns titles, locations and role start dates, and never who reports to whom. Checked on the live response for a 1,500-person software company: every leader record carried a current title and a start date for that title, and none carried a manager. So an org chart built from it has two kinds of fact in it, and the whole design keeps them apart: the people and titles are Clay's, and every line between them is an inference from titles and functions that the page labels as inferred, gives a reason for, and lets the viewer correct. People with no evidence for a manager are not parked under the CEO to make the chart look complete; they wait in a Needs review tray.
The output is one self-contained page with two views:
Each tile opens a side panel with the reason for its line, the buying role and level (editable), Clay
details, recent news, and "Find email / Find mobile with Clay" buttons that run only when the viewer
clicks and confirms. references/page-behavior.md describes every control on the page.
Do not start a step before the steps above it have their answers. If a declared input is missing, ask for it — never assume a default and continue.
Nothing here ships with a value. Each one is the installer's, not the author's: ask for it, never substitute a plausible default, and where an answer does not exist say which step becomes unavailable rather than guessing. Where a default IS defensible it is named below, and using it means saying so in the output.
| Input | What the installer supplies | If it is missing |
|---|---|---|
| Target company | a company name, or better a website domain | no default — ask. A bare name is resolved and confirmed before any people search (Step 4) |
| Branding choice | yes or no: style the page in their own company's brand | ask. No means the default style (off-white page, purple accents) |
| Their website | the seller's own site, only if they chose branding | no brand is extracted; the default style is used and the reply says so |
| First-build size | how many leader records to pull on the first build | 30 is the author's default and must be stated; never more than 50 on a first build |
| Mobile lookup function | a function in their Clay workspace that finds a mobile number, picked from their own function list (Step 5) | the page offers email lookup only and the reply says so |
| News window | how far back the news section looks | 3 months is the author's default and must be stated |
| Clay workspace | whichever workspace their Clay connection is signed in to | confirmed at Step 0, never assumed |
If an answer sheet is present beside this skill, load it and ask only for what it does not cover. A partial sheet is normal; a value it is missing gets asked for on its own rather than restarting the interview. Say which values came from the sheet before using them — a sheet applied silently is a wrong field nobody catches. If there is no sheet, say nothing about sheets — the check is a file lookup, not a question. At delivery, offer to save the durable answers back (brand website, mobile lookup function, build size, news window; identifiers only, never a token or a password), private and never published — and phrase the offer so it explains itself: "want me to save these settings to a file, so the next chart you or a teammate builds doesn't ask them again?" The target company changes every run, so it is never saved.
Contact lookups on the finished page are the viewer's own action: each one runs through the viewer's own Clay connection, only after they click and confirm an inline notice that it uses their Clay credits.
clay whoami where the Clay CLI is installed) and tell the user
which Clay workspace the search will run in, in one line.python3 runs; the page is built by scripts/orgatlas.py, which needs only the standard
library.If any check fails, say which component is missing and the one thing that fixes it (connect the Clay
connector, or sign in with clay login), then stop. Do not install, upgrade or fetch anything to repair
it, and never continue with other data.
Say the posture in two sentences before Step 1: "This reads Clay's search results for one company and writes one org chart page. It never writes to Clay or a CRM, and it runs no email or phone lookups while building." All classification, deduping and line inference runs locally in the script, so it costs nothing; only the Clay searches can use credits.
If the user has not named the target company, ask: "Which company do you want to build the org chart for? A website domain helps me find the right one." Wait for the answer.
Send this notice, filled in, together with the branding question, as one message:
I'll search Clay for current C-Suite and VP leaders at {Company}: CEOs and other chiefs, presidents, EVPs, SVPs and VPs. Former employees, directors, advisors, consultants and board-only seats are left out. The first build includes up to {first-build size, default 30} people, and you can add more later. The search charges per result at your workspace's search pricing, and it runs as soon as you answer below. It writes nothing anywhere except the org chart page.
Question: "Do you want the org chart styled with your company's brand?"
Answering this question is the go-ahead for the search. No search runs before it.
The brand is the user's company (the seller), not the target account.
backgroundColor, the fontFamily of h1 and body, hex custom properties
on :root, Google Fonts <link> tags and the header logo. A page-to-markdown fetch drops the CSS,
so use one only when no browser is available. Take only what is present:
og:site_name, the <title> prefix, or the logo alt text.--primary, --brand, a named swatch); <meta name="theme-color">.
Ignore black, white, greys and pale tints; if the only colored button is a pale tint, take the
strongest saturated brand swatch instead.family= values of Google Fonts links, else the first family in the heading and
body declarations.<svg> markup or a small SVG file returned as text, base64-encoded as a
data:image/svg+xml;base64,... URI. Otherwise leave it empty and the page shows the brand name as
a wordmark. Do not download binary images.theme.json:
{"brandName":"Acme","primary":"#0A66FF","fontHeading":"Space Grotesk","fontBody":"Inter",
"googleFontsUrl":"https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@600;700&family=Inter:wght@400;500;600;700&display=swap",
"logoDataUri":null,"source":"acme.com"}
The renderer adjusts the primary color so text meets WCAG AA contrast in light and dark mode; mention
it if the adjustment is visible.select from companies where domain = "<domain>".limit 5.company.json with only values Clay returned: {"name":..., "domain":..., "clayCompanyId":..., "industry":..., "location":..., "linkedinUrl":...}. From here on pass the company's LinkedIn
company URL as the identifier, never the bare name, because a shared domain pulls in the
subsidiary's people. Use the domain only if Clay returned no LinkedIn URL.Call people search with companyIdentifiers: ["<resolved LinkedIn company URL>"], which filters by
current employer. Start from this query, then adjust field names and operators to match the people
schema exactly:
select from people where experiences.any(is_current = true and (
job_title contains ("chief", "president", "ceo", "cfo", "coo", "cto", "cio", "cmo", "cro", "cpo", "chro", "clo")
or job_title is_similar_to ("Vice President", "Executive Vice President", "Senior Vice President")
)) limit 30
taskId while hasMore is true.
Never fetch more than 50 records on a first build.taskId and record which one each contact came from; the page's email
lookup and Step 8 use it.linkedinUrl, name, companyName, companyDomain, email (the
sourced email, if any), the company's companyLinkedinUrl, or none.enrich.json:
{"server":"Clay","email":true,"phone":{"id":"<function id>","name":"<function name>","inputs":{"<input name>":"<field>"}}}.
Show the user which function and input mapping you picked, and let them correct it.{"server":"Clay","email":true} and say in one line that the page will
offer email lookup only.Convert each returned contact into this shape, copying only fields Clay actually returned:
profile_id → clayId, name → name, latest_experience_title → title, url →
linkedinUrl, location_name → location, entityId → clayEntityId, the page's taskId →
clayTaskId.latest_experience_start_date (YYYY-MM) → roleStartDate. This is when the person started
their current title, so it can be a promotion rather than a new hire. Keep it only when
present; never estimate it.isCurrent: true when latest_experience_company matches the resolved company; false when it
names another company. Use the current title at the resolved company, not the headline.audienceFields entirely. That block is the workspace's own CRM record, and its titles,
emails, phones and "no longer at company" flags often describe a previous employer.{"clayId":"...", "name":"...", "title":"<current title at this company>", "linkedinUrl":"...",
"location":"...", "roleStartDate":"YYYY-MM", "email":"<only if already in the result>",
"seniority":"<only if returned>", "isCurrent": true}
Save the list as raw.json.
Run python3 scripts/orgatlas.py normalize --raw raw.json --company company.json --out people.json --limit 30
(the limit is the declared first-build size). It is deterministic and free:
Excludes former employees, directors and below, advisors, consultants, assistants and board-only seats, "Head of" titles without VP seniority, and field or deputy C-titles such as "Field CTO", which are not the company's C-Suite seat.
Classifies level: "Chief … Officer", C-level acronyms and President are C-Suite; EVP, SVP, VP and Global VP are VP.
Maps function from the title to one of: Executive, Revenue, Sales, Marketing, Finance, Product, Engineering, People, Legal, Operations, Strategy, Customer, Other.
Dedupes by Clay ID, then normalized LinkedIn URL, then normalized name plus company domain.
Infers reporting lines as reportsTo: {id, basis, confidence}, in this order, first match
wins:
unplaced and goes to the Needs review tray.Every line points to someone more senior, so the chart cannot contain a cycle.
Prints a report of counts, exclusion reasons and line confidence. Keep it for the reply.
Find recent news that names the charted leaders. This is web search only, not Clay, so it costs no Clay credits. It is the one web-sourced section, it is labeled as such on the page, and nothing in it ever changes a person, title or line.
alsoAt.news.json. Summaries are one or two sentences in your own words: never copy article text
beyond a few words, and never put words in a leader's mouth.
{"checkedAt":"YYYY-MM-DD","windowMonths":3,"items":[
{"date":"YYYY-MM-DD","title":"<headline>","url":"https://...","source":"<outlet>",
"kind":"News | Press release | Byline","summary":"<your words>",
"people":["<people.json id>"],"alsoAt":[{"source":"<outlet>","url":"https://..."}]}]}
The renderer drops any item with no date, no https link, no title, or no one on the chart.news.json with an empty items list; the page says no news named these
leaders.python3 scripts/orgatlas.py render --people people.json --company company.json [--theme theme.json] --enrich enrich.json --news news.json --out "<Company> Org Chart.html".
The template is scripts/orgchart_template.html. The default output is a page body with no
doctype, html, head or body tags, for hosts that publish pages; add --full-document for a
standalone file.enrich.json has a phone function — run function direct. On a republish, keep the stored
capability unless the tool list changes.people.json, company.json and theme.json from the same session, or
read the published page back and run python3 scripts/orgatlas.py extract --html <file> --outdir .,
which recovers all three.taskId from this session if one is still valid; otherwise
re-run the Step 5 query with a limit of current total plus the requested amount, and deduping drops
the people already charted. Default to 20 more if no number is given, and say it uses Clay credits
before running it.python3 scripts/orgatlas.py normalize --raw raw_more.json --company company.json --existing people.json --out people.json --limit <N more>.Built the Northwind Robotics org chart from Clay (workspace: Acme GTM): 25 leaders — 7 C-Suite, 18 VP. Left out 5: 2 field CTO titles, 1 former employee, 1 executive assistant, 1 non-VP title. 10 people are in Needs review because Clay's data has no same-function leader for them, and 1 line is low confidence. The news section has 6 items from the last 3 months, naming 4 leaders. Reporting lines are inferred from titles, not supplied by Clay. First build size 30 and news window 3 months are the defaults.
| Leaders | Champions | Exec buyers | Not yet classified | Contacts found | Need a manager | Lines you set | New in role (6 mo) |
|---|---|---|---|---|---|---|---|
| 25 · 7 C-Suite · 18 VP | 0 | 0 | 25 | 0 | 10 | 0 | 7 |
| Person | Title | Lane | Reports to | Line | Why |
|---|---|---|---|---|---|
| Dana Whitfield | Chief Executive Officer | top of chart | — | — | most senior title in Clay's results |
| Omar Reyes | Chief Technology Officer · New · 4 mo | Engineering & Security | Dana Whitfield | inferred, medium | C-Suite executives usually report to the CEO |
| Lena Park | VP, Platform Engineering | Engineering & Security | Omar Reyes | inferred, medium | same function (Engineering) as the Chief Technology Officer |
| Priya Nair | VP, Demand Marketing | Needs review | — | none | no same-function leader in this dataset |
| Date | Outlet | Type | Headline | Names |
|---|---|---|---|---|
| Aug 4, 2026 | Northwind newsroom | Press release | Northwind launches autonomous fleet monitoring | Omar Reyes |
audienceFields or any other CRM-record data for a person.--demo exists only for testing the page, labels every
record Demo, and is never a fallback when Clay fails.Ask: "Org chart for northwind-robotics.example, styled in our brand, acme.example."
Step 0 confirms the Clay workspace. Step 2 sends the notice and branding question; the user says yes and
names their site. Step 3 reads the site's computed styles: primary #3859F9, a geometric sans heading
font available on Google Fonts, no inline logo, so the wordmark is used. Step 4 resolves the domain to one
company and saves its LinkedIn company URL. Step 5 returns 20 records, then 10 more with load more;
the workspace has a mobile-number function taking a LinkedIn URL, which the user confirms. Step 6: 30
records → 25 leaders (7 C-Suite, 18 VP), 5 excluded (2 field CTOs, 1 former employee, 1 assistant, 1
non-VP title); lines: 13 medium, 1 low (an EVP with no same-function leader), 10 unplaced. Step 7 finds 6
dated, verified items naming 4 leaders and drops 2 undated ones. Step 8 publishes the page privately and
replies with the counts above.