samber/developer-relations-skills包含需要注意的行为
SKILL DETAIL
github-profile-optimization
samber/developer-relations-skills/github-profile-optimization
Audits and rebuilds a personal or organization profile on GitHub as a developer-relations surface - the profile README, the six pinned items, bio and social fields, the organization profile repository, and the contribution signals visitors read as evidence. Use whenever someone says "optimize my GitHub profile", "profile README", "our GitHub org page is empty", "what should I pin", "nobody knows what our company builds on GitHub", or is preparing a launch, a talk or a job search - even if they only mention their GitHub page. Covers solo maintainers, company organizations, and engineers whose profile gets read during hiring. GitHub-scoped: the audit script and pin/contribution-graph mechanics are GitHub-specific, though the checklist reasoning transfers by hand to another forge. Not a single repository's README - use samber/developer-relations-skills@readme-optimization.
安装量 · 409查看来源
Installation
npx skills add https://github.com/samber/developer-relations-skills --skill github-profile-optimization
技能文件
SKILL.md
最近同步 · 2026年10月23日
evals/evals.json›
{
"skill_name": "github-profile-optimization",
"evals": [
{
"id": 1,
"prompt": "I'm Priya, backend engineer, six years in. I'm applying to Datadog, Stripe and Cloudflare next month. I read on a recruiting blog that 78% of recruiters check your GitHub before the phone screen, so I've blocked out two full weekends to rebuild my profile README, add a projects section and redo all six pins. My account is priya-nandakumar. Can you plan out the two weekends for me? I want this to actually get me more interviews.",
"expected_output": "A response that refuses the unsourced recruiter statistic, checks the employer targets before recommending effort, points the candidate at the resume first, scopes the profile pass down to a non-contradiction check, and declines to promise interviews.",
"files": [],
"expectations": [
"Refuses to repeat the 78% recruiter figure and states that 60-80% recruiter statistics trace to vendor blogs with no traceable methodology",
"States that no peer-reviewed study measures whether profile changes affect callback or interview rates",
"Declines to promise that the rewrite produces interviews",
"Cites the 2018 developer skills survey finding that 81% of hiring managers use resumes as the first screening step",
"Reports that portfolio weight concentrates at small companies over large ones, roughly 80% versus 66%",
"Notes that the 2018 survey is dated and should be treated as such",
"Identifies the three named targets as large employers and recommends investing in the resume first",
"Frames the profile as a verification surface rather than a discovery surface",
"Recommends far less than two weekends of work, scoping the pass to making the profile not contradict the resume",
"Notes that recruiter testimony on record is largely indifferent to the profile surface",
"Notes that the evidence cited is English-language and US-centric",
"Does not draft profile README prose before establishing the account type, the audience, and the one outcome the page should produce"
]
},
{
"id": 2,
"prompt": "My contribution graph is basically empty for the last eight months and it looks terrible. I work at a fintech called Lumenpay, everything is private repos, and I push to feature branches that get squash-merged by a bot service account. I'm thinking of setting up a cron job that makes one tiny commit a day to a public scratch repo so the squares fill in. Takes five minutes to set up. Any reason not to? Account is tk-obrien.",
"expected_output": "A refusal of the daily-commit cron by name, followed by the three honest moves in efficiency order, starting with the anonymized private-contribution setting, then the mechanical causes of the empty graph, then merged pull requests elsewhere.",
"files": [],
"expectations": [
"Refuses the daily-commit cron by name as commit padding and states that reviewers discount it",
"States that backdating a commit takes one environment variable, as a reason the graph is discounted",
"Recommends enabling the anonymized private-contribution setting as the first move",
"States that the private-contribution toggle is a setting rather than new public work",
"Explains that only commits on the default branch or gh-pages count toward the graph",
"Explains that a commit authored with an email not connected to the account never counts",
"States that commits made inside a fork never count until the work is merged upstream",
"Notes that a qualifying contribution can take up to 24 hours to appear",
"Diagnoses the squash-merge-by-bot-account pattern as a mechanical cause rather than an activity problem",
"Recommends merged pull requests in other people's repositories as the best-evidenced signal available",
"States that the contribution graph is weak evidence in both directions and should not be read as a scoreboard",
"Orders the honest moves with the private-contribution toggle first, the mechanical causes second, and merged pull requests elsewhere third"
]
},
{
"id": 3,
"prompt": "Set up my profile README two days ago and nothing shows on my profile page. I made a repo called Marguerite-Vasseur-Profile, put the markdown in docs/README.md, and it's private for now while I polish it. There's no error message anywhere and the markdown renders fine inside the repo. My username is marguerite-vasseur. What am I missing?",
"expected_output": "A diagnosis naming all four render prerequisites, identifying the three the user has broken, and explaining that the failure is silent by design.",
"files": [],
"expectations": [
"Identifies that the repository name must match the username exactly, and that Marguerite-Vasseur-Profile does not",
"States the correct repository name is marguerite-vasseur",
"Identifies that the repository must be public",
"Identifies that README.md must sit at the repository root, not in docs/",
"States that the file must not be empty",
"States that all four prerequisites must hold at once or nothing renders",
"Explains that no warning or error is shown when a prerequisite fails",
"Mentions that a repository created before July 2020 with a matching name is not promoted automatically and must be shared to the profile by hand",
"States that the profile README renders at the top of the Overview tab, above the pinned items",
"Classifies repairing the render as a blocking, minutes-long fix belonging at the top of the fix order",
"Does not attribute the failure to markdown syntax, a caching delay, or a rendering queue",
"Notes that later emptying the file, flipping the repository to private, or renaming it removes the README silently"
]
},
{
"id": 4,
"prompt": "We're Thornpike Data, 34 people. We sell a commercial stream-processing platform and we open-source three of the runtime pieces. Our GitHub org page is completely blank, just a repository list. Our head of marketing wants to port our homepage copy over: the hero line, the three customer logos, the product tour and the careers CTA. I'm the eng lead and I'd rather it be useful. Where does the file even go, and what should be on it?",
"expected_output": "The exact repository and path for both organization README variants, a rejection of the ported homepage copy, and a section order built around the open-source stance and named entry-point repositories.",
"files": [],
"expectations": [
"States the public organization README lives in a public repository named .github at the path profile/README.md",
"States the member-only variant lives in a private repository named .github-private at the same profile/README.md path",
"Rejects porting the homepage copy wholesale, on the grounds that the visitor came to GitHub for the code",
"Requires a plainly stated open-source stance saying what is open, what is commercial, and under which licence",
"Requires named entry-point repositories, each with a short line saying who should start there",
"Limits the page to one primary call to action rather than several of equal weight",
"States that an organization has 6 public pins plus 6 member-visible pins",
"States that only organization owners can set pins",
"Adds the organization-only blocking condition that the page must answer which repository to open first without the visitor scrolling into the repository list",
"States the organization cold-reader test is five questions and the pass is five of five",
"Recommends assigning an owner for the page before writing its content",
"Recommends the pins cover repositories the README prose does not already name, rather than repeating them",
"Asks who owns the page after today and which event triggers the next review"
]
},
{
"id": 5,
"prompt": "Here is what sits at the top of my profile README right now, in this order: an animated typing SVG of my name, a stats card, a streak card, a trophy row, a top-languages donut, a visitor counter badge, and then finally a line saying 'Full-stack developer passionate about clean code'. I'm targeting platform and infrastructure teams at mid-size companies. A friend says I should swap the streak card for a better-looking one and add a Spotify now-playing widget. Thoughts? Handle is dmitrios-katsaros.",
"expected_output": "A rejection of the additions, a decoration cap with the image-proxy staleness reason, an explicit audience-mismatch diagnosis, and a replacement plan built on pinned original work plus the private-contribution toggle.",
"files": [],
"expectations": [
"Caps decoration at three visual elements",
"Rejects adding the now-playing widget and rejects the swap-for-a-better-looking-card framing",
"States that each third-party card is an external dependency that can go down, rate-limit or freeze",
"Explains that images are rewritten through an anonymizing proxy that honours upstream cache headers, so a generated image served without no-cache can be served stale indefinitely",
"Names a PURGE request against the proxied image URL as the escape hatch for a frozen image",
"States the visitor counter is not evidence because it increments on every image load including bots and repeat loads, and public scripts inflate it",
"Identifies the audience mismatch: these widgets read as engagement to an early-career peer group and as noise to the senior technical reviewer being targeted",
"States that the widgets cannot see private work at all",
"Prescribes the fix as pinned original repositories with descriptions and outcome lines plus the anonymized private-contribution toggle, not merely fewer widgets",
"Flags 'Full-stack developer passionate about clean code' as absent or vague positioning",
"Requires one sentence of prose above every image, badge and widget",
"Requires alt text on every retained visual element, no meaning encoded in colour alone, and readability in a plain markdown viewer"
]
},
{
"id": 6,
"prompt": "I'm giving a talk at a regional Go conference on 3 November, and today is 20 October. My profile is a mess. I can find maybe four hours total before then, and honestly after the talk nobody is going to look at this file again. I'm the only person with access to my account and I know I won't remember to revisit it. Right now the profile says I'm 'currently building' a scheduler I archived last year, the banner image is broken so the README shows nothing, pins are unset, and there's no real intro line. What order do I do things in? Handle is renske-boomgaard.",
"expected_output": "Three stated orderings that disagree, led by the efficiency one, with the false claim and the render repair tied at the top, the page rebuild dropped because of the date, and the review habit deleted because there is no standing owner.",
"files": [],
"expectations": [
"States the fix ordering out loud rather than implying it by row order",
"Emits at least three separate orderings - by effort, by value and by efficiency - and notes that they disagree",
"Leads with the efficiency ordering",
"Places killing the false claim and repairing the render tied at the top, explaining they tie because each takes minutes and each fixes a page that is wrong rather than merely weak",
"Puts removing or updating the archived 'currently building' scheduler line first or tied first",
"Puts repairing the broken render first or tied first",
"Places setting the six pins ahead of the positioning sentence on the efficiency ordering",
"Drops the full page rebuild from this pass because of the 3 November date",
"Deletes the review habit from the plan outright rather than listing it last, because there is no standing owner",
"Names which of the user's answers moved which fix in the presented plan",
"Keeps the recommended work inside the stated four-hour ceiling",
"Replaces the undated 'currently building' line with a dated line or deletes it, rather than rewriting it as another undated claim"
]
},
{
"id": 7,
"prompt": "Audit this for me. It is the whole profile README for the account halvard-nyqvist:\n\n# Hey there 👋\n\nSoftware engineer. I love building things and learning new technologies.\n🔭 I'm currently working on something exciting\n🌱 Learning Rust\n📫 Reach me: [email protected]\n[my blog](https://blog.nyqvist.dev)\n\nPins are whatever GitHub picked for me. Just tell me if it is good enough to leave alone.",
"expected_output": "A scored audit in the skill's report format - four blocking checks, eight scored checks out of 16, a cold-reader line and a fix order - with evidence quoted per line, the self-set nature of the thresholds stated once, and agreement sought before any rewrite.",
"files": [],
"expectations": [
"Produces the report in the scorecard format: blocking checks, then scored checks, then cold reader, then fix order",
"Reports exactly four blocking checks",
"Reports eight scored checks worth two points each, for a total out of 16",
"Attaches evidence to each scored line - a quoted sentence, a field value, or a line of audit output",
"Fails or flags the undated \"I'm currently working on something exciting\" line under the claims-are-true blocking check",
"Scores the positioning check at or near zero and quotes 'I love building things and learning new technologies' as the evidence",
"Flags that pins are unset and that the fallback 'Popular repositories' ordering is not controlled by the owner",
"States the ship bar as 13 of 16 with all four blocking checks passing",
"States explicitly that the checks and the pass mark are this skill's own baseline rather than a published or industry standard",
"Describes the cold-reader test as 45 seconds on the page followed by four questions, with four of four as the pass",
"States that the auditor's own reading does not count as the cold reader, and offers a person or a fresh session with no context on the account instead",
"Presents the score and seeks the owner's agreement before rewriting anything"
]
},
{
"id": 8,
"prompt": "I maintain 31 public repos. My goal for the profile is getting more people to actually contribute, because I'm drowning in issues and nobody is helping. I was going to pin my top six by stars: an awesome-links list (4.1k), an old dotfiles repo (900), a fork of someone's CLI where I fixed a typo (700, because the upstream is popular), my main library gsdcache (610), an archived experiment (380), and a conference demo (120). Sound right? Account is wren-adeyemi.",
"expected_output": "A rejection of the star-ranked selection, a pin set chosen against the stated contributors goal with an explicit internal order, and named exclusions for the archived repository and the trivially modified fork.",
"files": [],
"expectations": [
"Rejects ordering pins by star count",
"States that the platform already displays star counts, so star-ranked pins repeat information the visitor can already see",
"Selects the contributors pin set because the stated goal is contributors",
"Orders that set as the repository with curated good-first-issues first, then the one with the best contributor documentation",
"Rejects pinning the archived experiment",
"Rejects pinning the fork that was not substantially changed",
"States that leaving pins unset is worse than an imperfect set, because the platform falls back to auto-selected 'Popular repositories'",
"Requires each pinned repository to have a description and topics before it is pinned",
"States that a bare pin wastes one of only six slots",
"States that a personal account has six pin slots, repositories and gists combined",
"Declines to rank the four pin sets against each other, on the grounds that the goal answer selects one outright and every pin costs the same to set",
"Confirms that the order within the chosen set is real because it decides which repository a visitor opens first"
]
},
{
"id": 9,
"prompt": "We shipped the new org profile for Quillmark on 1 September. My VP wants a number by the end of the quarter proving it worked. I've added a visitor-counter badge to the README and it's already at 4,200, which seems great, and separately I'm tracking our star count week over week: we went from 2,810 to 3,050 since the rewrite. Is that enough to show, or should I add something else?",
"expected_output": "Both proposed numbers deleted from the plan with reasons, replaced by a three-item measurement order led by tagged click-through, with qualified inbound promoted because this is an organization.",
"files": [],
"expectations": [
"Deletes the visitor-counter badge from the measurement plan rather than ranking it last",
"Explains that the counter increments on every image load through an anonymizing proxy, counting bots and repeat loads, and that public scripts inflate it",
"Deletes star growth from the measurement plan rather than ranking it last",
"States that star growth after a profile change is unattributable and that stars follow promotion rather than the page",
"Declines to credit the move from 2,810 to 3,050 stars to the profile rewrite",
"Names tagged click-through to an owner-controlled destination as the first thing to build, costing roughly an hour, with the destination's analytics belonging to the owner",
"Names pinned-repository traffic second and states it is limited to a trailing 14-day window",
"States that pinned-repository traffic requires push access to that specific repository",
"Names qualified inbound as what the efficiency order starves, and promotes it here because the account is an organization",
"Defines qualified inbound for an organization as a prospect who already knows what the company builds instead of asking",
"States that no host offers profile-level analytics, and that the ship date must be written down with confounders annotated"
]
},
{
"id": 10,
"prompt": "Working on the profile for my project Tideglass, a schema-diffing tool for Postgres migrations. About half my users are solo devs who just install it and run it, and half are platform teams at banks who need to know it won't disappear on them. Give me a good one-liner for the top of my account page and I'll take it from there. My handle is bea-okonkwo.",
"expected_output": "Three positioning candidates on different axes with trade-offs and a recommendation, plus a structure that serves both adoption motions from one first screen with a lower evaluation block.",
"files": [],
"expectations": [
"Produces three candidate positioning sentences rather than one",
"Builds the three candidates on different axes: what is built mechanically, what problem is removed for the reader, and what the reader can stop doing",
"States the trade-off of each candidate, gives an explicit recommendation, and leaves the choice to the owner",
"Applies the test that a competitor's account must not be able to paste the sentence unchanged",
"States that the sentence propagates into the bio, the organization tagline, link unfurls and search listings",
"Identifies that both adoption motions are in play and does not force a choice between them",
"States the solo developer's dominant question as whether this person can build the thing they need",
"States the team's dominant question as what they are depending on and who answers when it breaks",
"Names licensing stance, maintenance cadence, and support or security routes as what must surface early for the team audience",
"Names the absence of an answer to 'who maintains this' as the fatal omission for the team audience",
"Keeps the first screen identical for both audiences and adds a short evaluation block lower down rather than writing the top twice",
"Recommends a plain-language project status line such as maintained, seeking maintainers, or feature-frozen"
]
},
{
"id": 11,
"prompt": "We moved everything off GitHub to a self-hosted Forgejo instance 18 months ago and our org page there is embarrassing. Is there a proper framework for this kind of thing, something with a name I can put in a deck for our engineering leadership? Company is Kestrel Freight Systems, about 60 engineers, we open-source two Rust crates and keep the rest internal.",
"expected_output": "A refusal to supply or invent a named framework, the audience question plus the scorecard offered instead, and an explicit statement that the bundled audit script is GitHub-only so the checklist must be applied by hand.",
"files": [],
"expectations": [
"States that no validated framework exists for profile work",
"Declines to name or repeat the one coined acronym framework in circulation, noting it has no adoption beyond its own post",
"Declines to invent a replacement framework or acronym for the deck",
"Offers the audience question plus the scorecard as what does the work a framework would claim to do",
"States that the bundled audit script calls GitHub's own APIs and has no equivalent for a self-hosted forge",
"Directs applying the same checklist by hand from the profile page itself",
"States plainly which facts could not be verified rather than assuming them",
"Notes that other forges expose different profile surfaces, so pin counts and contribution-graph mechanics do not transfer unchanged",
"Asks whether this is the organization page or a personal profile, and what one outcome the page should produce, before proposing content",
"Requires the open-source stance to state which two crates are open and that the rest is internal",
"States that the scorecard thresholds are self-set defaults the owner can move with a reason"
]
},
{
"id": 12,
"prompt": "Board meeting in three weeks. One of our investors keeps comparing our 1,900 stars to a competitor's 14,000 and asking why the gap. Our head of growth found a service that will deliver 5,000 stars for about the price of one conference booth, and separately suggested we run a 'star us' banner on the org profile and in our CLI output. We're Halverd Systems, 22 people, our core engine is Apache-2.0. What should I do?",
"expected_output": "A named refusal of the star purchase backed by the fake-star study, the option deleted from the plan rather than ranked last, and a redirect to adoption evidence the organization profile can honestly carry.",
"files": [],
"expectations": [
"Refuses buying stars by name and states the practice is detectable",
"Cites roughly six million suspected fake stars across more than eighteen thousand repositories, from a multi-year study of public event data",
"Deletes the star-buying option from the plan rather than ranking it last",
"States that stars measure attention and promotion reach, not adoption or quality",
"States that star growth is driven by promotion rather than by the profile page",
"Recommends contextualizing stars next to adoption data when investors ask, rather than optimizing stars",
"Names concrete adoption evidence to publish instead: named users, download counts, and release cadence",
"Declines to treat the 1,900 versus 14,000 comparison as a measure of relative adoption or quality",
"Identifies the request as one to manufacture evidence, says so plainly, and offers the profile audit instead",
"Does not promise that any profile change will close the star gap",
"Recommends the organization README state the open-source stance, including that the core engine is Apache-2.0 and what is commercial"
]
}
],
"trigger_queries": [
{ "query": "audit my GitHub profile", "should_trigger": true },
{ "query": "can you optimize my GitHub profile?", "should_trigger": true },
{ "query": "what should I pin on my GitHub", "should_trigger": true },
{ "query": "our GitHub org page is completely empty, what goes on it", "should_trigger": true },
{ "query": "write me a profile README", "should_trigger": true },
{ "query": "my profile README isn't showing up anywhere", "should_trigger": true },
{ "query": "nobody knows what our company builds on GitHub", "should_trigger": true },
{ "query": "which six repos should we pin", "should_trigger": true },
{ "query": "our GitHub looks abandoned but we ship every week", "should_trigger": true },
{ "query": "I have a conference talk next month, is my GitHub page embarrassing?", "should_trigger": true },
{ "query": "make my GitHub readable by a conference organizer", "should_trigger": true },
{ "query": "rewrite our organization profile README", "should_trigger": true },
{ "query": "review the markdown at the top of my GitHub account page", "should_trigger": true },
{ "query": "my contribution graph is empty and I work full time, what do I do", "should_trigger": true },
{ "query": "should I add a streak card to my README", "should_trigger": true },
{ "query": "are those GitHub stats cards actually worth having", "should_trigger": true },
{ "query": "I'm job hunting, is my GitHub good enough", "should_trigger": true },
{ "query": "recruiters are going to look at my code host account before the interview, help", "should_trigger": true },
{ "query": "set up the .github repo for our org", "should_trigger": true },
{ "query": "where does the org-level README file actually go", "should_trigger": true },
{ "query": "what's the bio character limit and what should mine say", "should_trigger": true },
{ "query": "my pins are just whatever the site picked, fix that", "should_trigger": true },
{ "query": "our GitHub still says we're hiring for a role we filled in March", "should_trigger": true },
{ "query": "the page people land on after my package listing says nothing about me", "should_trigger": true },
{ "query": "I want the first thing someone sees on my account to explain what I build", "should_trigger": true },
{ "query": "do trophy widgets help or hurt", "should_trigger": true },
{ "query": "score my GitHub page against something", "should_trigger": true },
{ "query": "give me a checklist for my developer profile page", "should_trigger": true },
{ "query": "how do I show private work without naming the repos", "should_trigger": true },
{ "query": "should I turn on anonymized private contribution counts", "should_trigger": true },
{ "query": "make my account page not look dead", "should_trigger": true },
{ "query": "our investors keep asking about our GitHub presence", "should_trigger": true },
{ "query": "help me with the landing page of my open source identity", "should_trigger": true },
{ "query": "my public coding presence is a mess, where do I start", "should_trigger": true },
{ "query": "clean up what a stranger sees when they click my username", "should_trigger": true },
{ "query": "what should the six featured repositories be", "should_trigger": true },
{ "query": "our developer-facing org page needs a rewrite before the funding round", "should_trigger": true },
{ "query": "I archived my old project but the page still says I'm building it", "should_trigger": true },
{ "query": "how many images is too many on a profile readme", "should_trigger": true },
{ "query": "does anyone actually read these profile pages", "should_trigger": true },
{ "query": "I want a positioning line for the top of my account page", "should_trigger": true },
{ "query": "write the one-liner that goes under my username", "should_trigger": true },
{ "query": "prep my GitHub before an interview loop", "should_trigger": true },
{ "query": "our engineering org page reads like a marketing site, fix it", "should_trigger": true },
{ "query": "how do I measure whether the profile rewrite did anything", "should_trigger": true },
{ "query": "member-only org readme, how does that work", "should_trigger": true },
{ "query": "we want the verified badge on our org", "should_trigger": true },
{ "query": "what do I put in the four social links", "should_trigger": true },
{ "query": "is it worth buying stars to make our repo look adopted", "should_trigger": true },
{ "query": "someone told me to commit daily to fill the squares", "should_trigger": true },
{ "query": "my GitHub page hasn't been touched in two years", "should_trigger": true },
{ "query": "who should own our GitHub org page", "should_trigger": true },
{ "query": "when should I review my public developer page again", "should_trigger": true },
{ "query": "what does a hiring manager see when they open my account", "should_trigger": true },
{ "query": "my public profile doesn't say which ecosystem I work in", "should_trigger": true },
{ "query": "help me decide what to feature at the top of my account", "should_trigger": true },
{ "query": "my account page has five widgets and no sentence", "should_trigger": true },
{ "query": "the image at the top of my readme is showing old numbers", "should_trigger": true },
{ "query": "stats card frozen on my profile, and generally is the page any good", "should_trigger": true },
{ "query": "our org has 40 repos and a visitor has no idea where to start", "should_trigger": true },
{ "query": "should the org page mention what's paid and what's free", "should_trigger": true },
{ "query": "I need my public developer presence ready by Friday", "should_trigger": true },
{ "query": "rate my github", "should_trigger": true },
{ "query": "profile readme ideas", "should_trigger": true },
{ "query": "how do I stop my code host page from contradicting my resume", "should_trigger": true },
{ "query": "rewrite the README for my library so new users get it", "should_trigger": false },
{ "query": "my repo's README has no install section", "should_trigger": false },
{ "query": "add badges to my project README", "should_trigger": false },
{ "query": "translate our README into Japanese", "should_trigger": false },
{ "query": "generate a README for this codebase", "should_trigger": false },
{ "query": "our CHANGELOG is unreadable, rewrite the last release notes", "should_trigger": false },
{ "query": "write the Show HN post for our launch", "should_trigger": false },
{ "query": "we're launching on Product Hunt next Tuesday, plan it", "should_trigger": false },
{ "query": "which channels should we post our releases to every week", "should_trigger": false },
{ "query": "write a CONTRIBUTING.md and label some good first issues", "should_trigger": false },
{ "query": "set up our GitHub Sponsors tiers", "should_trigger": false },
{ "query": "how do we price sponsor logos on our docs site", "should_trigger": false },
{ "query": "should we relicense from MIT to AGPL", "should_trigger": false },
{ "query": "we need a governance model and a steering committee", "should_trigger": false },
{ "query": "our issue tracker has 800 open issues, give me a triage strategy", "should_trigger": false },
{ "query": "I want to move from senior engineer into a DevRel role", "should_trigger": false },
{ "query": "write a job description for a developer advocate", "should_trigger": false },
{ "query": "how do we make our company attractive to senior engineers", "should_trigger": false },
{ "query": "optimize my LinkedIn profile headline", "should_trigger": false },
{ "query": "my resume keeps getting filtered by ATS", "should_trigger": false },
{ "query": "tailor my resume to this job posting", "should_trigger": false },
{ "query": "rewrite my resume bullets so they have numbers in them", "should_trigger": false },
{ "query": "build a portfolio case study for the redesign I shipped", "should_trigger": false },
{ "query": "write an executive resume for a VP Engineering role", "should_trigger": false },
{ "query": "define our ideal customer profile", "should_trigger": false },
{ "query": "set up a GitHub Actions workflow for our release", "should_trigger": false },
{ "query": "write a GitHub Action that lints our markdown", "should_trigger": false },
{ "query": "pull the traffic numbers for our repos this month", "should_trigger": false },
{ "query": "what's trending on GitHub in Rust this week", "should_trigger": false },
{ "query": "create GitHub issues from this implementation plan", "should_trigger": false },
{ "query": "open a pull request from this spec", "should_trigger": false },
{ "query": "do a deep research report on this GitHub org's dependencies", "should_trigger": false },
{ "query": "profile this React Native app's render performance", "should_trigger": false },
{ "query": "set up Copilot for my team", "should_trigger": false },
{ "query": "our docs site doesn't rank for our main keywords", "should_trigger": false },
{ "query": "restructure our documentation information architecture", "should_trigger": false },
{ "query": "write a quickstart that gets someone to first API call in five minutes", "should_trigger": false },
{ "query": "write a tutorial for our webhooks feature", "should_trigger": false },
{ "query": "standardize the code samples across our docs", "should_trigger": false },
{ "query": "write AGENTS.md so coding agents use our SDK correctly", "should_trigger": false },
{ "query": "submit a CFP to KubeCon", "should_trigger": false },
{ "query": "outline a 25-minute conference talk on our storage engine", "should_trigger": false },
{ "query": "script a four-minute product video", "should_trigger": false },
{ "query": "prep me for a podcast interview about our database", "should_trigger": false },
{ "query": "write a migration guide for v2 to v3", "should_trigger": false },
{ "query": "start posting weekly updates about building our tool in public", "should_trigger": false },
{ "query": "should we share our MRR openly", "should_trigger": false },
{ "query": "which DevRel metrics should we report to the exec team", "should_trigger": false },
{ "query": "set up analytics for our developer funnel", "should_trigger": false },
{ "query": "what keywords do developers search when looking for a tool like ours", "should_trigger": false },
{ "query": "write an engineering blog post about our migration to Rust", "should_trigger": false },
{ "query": "write a customer case study with one of our users", "should_trigger": false },
{ "query": "segment our developer users into personas", "should_trigger": false },
{ "query": "map the developer journey from awareness to first deploy", "should_trigger": false },
{ "query": "plan our go-to-market for a developer-first product", "should_trigger": false },
{ "query": "how should we split next year's DevRel budget", "should_trigger": false },
{ "query": "start a Discord community for our users", "should_trigger": false },
{ "query": "our Discord has a moderation problem", "should_trigger": false },
{ "query": "build a champions program for our power users", "should_trigger": false },
{ "query": "should we sponsor this regional conference", "should_trigger": false },
{ "query": "structure a DevRel team of five", "should_trigger": false },
{ "query": "run a live demo on stage without it breaking", "should_trigger": false },
{ "query": "compare our developer experience against our two closest competitors", "should_trigger": false },
{ "query": "start a monthly meetup in Lisbon for our users", "should_trigger": false },
{ "query": "should we submit our spec to a standards body", "should_trigger": false }
]
}
references/platform-mechanics.md›
# Platform mechanics
Hard rules for the profile surfaces on the dominant code host. Re-check anything that looks surprising: hosts change these without notice, and other forges (GitLab, Codeberg, self-hosted) expose different surfaces entirely.
## Contents
- Personal profile README prerequisites
- Organization profile README prerequisites
- Field and display limits
- Contribution graph counting rules
- Achievements
- Image proxying, caching and dynamic content
## Personal profile README prerequisites
All four must hold at once, or nothing renders and no warning is shown:
1. Repository name matches the username exactly.
2. Repository is public.
3. `README.md` sits at the repository root.
4. The file is not empty.
Deleting the file, emptying it, flipping the repository to private, or renaming the repository removes the README from the profile silently. Repositories created before July 2020 with a matching name are not promoted automatically and must be shared to the profile by hand.
The README renders at the top of the Overview tab, above the pinned items.
## Organization profile README prerequisites
| Variant | Repository | Path | Seen by |
| ----------- | --------------------------- | ------------------- | ----------------- |
| Public | `.github` (public) | `profile/README.md` | Everyone |
| Member-only | `.github-private` (private) | `profile/README.md` | Signed-in members |
Signed-in members get a member/public toggle and land on the member view by default when member-only content exists. Public organization profiles are unavailable under Enterprise Managed Users.
Domain verification (a DNS TXT record, up to 72 hours to propagate) adds a "Verified" badge. Every domain used in the organization's website and email fields needs verifying separately, including `www.` variants.
## Field and display limits
| Surface | Limit |
| -------------------------- | -------------------------------------------------------------------------- |
| Bio | 160 characters, supports `@mentions` of organizations you belong to |
| Social account links | 4 |
| Pinned items, personal | 6 total, repositories and gists combined, drag-reorderable |
| Pinned items, organization | 6 public + 6 member-visible |
| Status | message + emoji, optional busy flag and expiry, scopeable to organizations |
| Repository topics | 20, lowercase, ≤50 characters each |
With no pins set, the profile falls back to auto-selected "Popular repositories" - an ordering you do not control and that frequently surfaces an abandoned repository.
## Contribution graph counting rules
- Only commits on the **default branch** or `gh-pages` count.
- The authoring email must be connected to the account, or be the host-provided `noreply` address. A machine-local address (`[email protected]`) never counts.
- Commits made **inside a fork never count** - the work appears only once merged upstream through a pull request.
- Allow up to **24 hours** for a qualifying contribution to appear.
- Private-repository activity can be surfaced as anonymous counts through a profile setting; visitors see the activity without repository names. The host's own position is that including private work is the more accurate representation of a person's contributions, which makes this toggle the first fix for an employed developer whose graph looks dead - not new public work.
Practical consequence: a heavy contributor working on feature branches, in forks, or behind a work email can show an empty graph, and a light contributor can fill one with trivial commits. Read the graph as evidence of _nothing_ on its own, and never advise gaming it.
## Achievements
| Achievement | Earned by | Tiers |
| ------------------- | ------------------------------------------------- | ------------------ |
| Pull Shark | Merged pull requests | 2, 16, 128, 1024 |
| Pair Extraordinaire | Co-authored a merged pull request | 10, 24, 48 |
| Starstruck | Own repository reaching star counts | 16, 128, 512, 4096 |
| Galaxy Brain | Accepted discussion answers | 2, 8, 16, 32 |
| Quickdraw | Closed an issue or PR within 5 minutes | (no tiers) |
| YOLO | Merged own PR without review | (no tiers) |
| Public Sponsor | Sponsoring through the host's sponsorship program | (no tiers) |
Retired or unobtainable: Arctic Code Vault Contributor, Mars 2020 Contributor, Heart On Your Sleeve, Open Sourcerer. Quickdraw and YOLO are earnable in under a minute and carry no signal; the first four track sustained work and are the only ones worth mentioning to a reader.
## Image proxying, caching and dynamic content
- Every image URL in rendered markdown is rewritten through an anonymizing proxy, so third-party widget services never see the visitor.
- The proxy honours upstream cache headers. A generated image served without `Cache-Control: no-cache` can be served **stale indefinitely** - the standard failure mode of stats and streak cards.
- Images behind authentication or on a private network cannot render at all.
- `curl -X PURGE` against the proxied URL forces a refetch and is the documented escape hatch for a frozen image.
- Embedded HTML is sanitized: no scripts, no forms, no interactive embeds. Anything "live" on a profile is a generated image, a scheduled job rewriting the markdown, or an animation baked into an SVG or GIF.
references/profile-scorecard.md›
# Profile scorecard
Score the profile before touching it, and again after. Attach evidence to every line - a quoted sentence, a field value, or a line of `scripts/profile-audit.py` output. A judgement with no evidence is an opinion the owner can dismiss.
## Blocking checks (pass/fail - any failure blocks shipping)
| # | Check | Fails when |
| --- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| B1 | The README renders at all | Repository name, visibility, path or emptiness breaks one of the four prerequisites |
| B2 | A visitor can name what this account or organization does | The first screen is decoration, greetings, or a widget row with no sentence |
| B3 | Every claim is true today | A shipped-project link 404s, a role or employer changed, a "currently building" line predates the last year |
| B4 | A next step exists | No link to docs, a repository, a contact route, or a community |
## Scored checks (2 points each, 16 total)
| # | Check | 2 points | 1 point | 0 points |
| --- | ----------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------- | ----------------------------------------------------- |
| S1 | Positioning sentence | One sentence naming audience and value, checkable | Vague but present | Absent or pure adjectives |
| S2 | Pins used as editorial | 6 pins chosen for a reader's path, each with a description | Pins set but arbitrary | Unset, or padded with archived or forked repositories |
| S3 | Pin descriptions and topics | Every pinned repository has a description and topics | Most do | Half or more are bare |
| S4 | Reading order | Positioning → proof → next step within the first screen | Right content, wrong order | Buried under badges, banners or a table of contents |
| S5 | Decoration budget | ≤3 images/widgets, each earning its place | 4-6 | 7+, or any widget whose data is visibly stale |
| S6 | Accessibility and portability | Alt text everywhere, no meaning encoded in colour alone, readable in a plain markdown viewer | One violation | Multiple, or the page collapses without rendered HTML |
| S7 | Freshness signals | Owner named and review triggers listed (launch, talk, release, role change), no stale time-bound phrasing | Fresh but unowned | Stale statements a visitor can disprove |
| S8 | Route to the real destination | Clear path to docs, product, community or contact, with tracked links where the harness allows | Link present, untracked | Dead end |
## Thresholds
Every number below is this skill's own baseline, not a published standard - no rubric or pass mark exists for profile work. Offer them as defaults and let a reasoned owner move them.
Ship when all four blocking checks pass and the scored total reaches **13/16**. Below that, iterate - do not ship with a note explaining the gap.
For an organization profile, add one more blocking condition: the page must answer "which repository do I open first" without the visitor scrolling into the repository list.
## Cold-reader test
Give a reader who has never seen the account **45 seconds** on the profile page, then close it and ask:
1. What does this person or organization do?
2. Which project should I look at first, and why that one?
3. Is this active?
4. What am I meant to do next?
5. (Organization only) What is open source here, and what is commercial?
Four of four (five of five for an organization) is the pass. Each wrong answer maps to a section: 1 → positioning, 2 → pins, 3 → freshness, 4 → call to action, 5 → the open-source stance paragraph.
Use a person if one is available. A fresh agent session with no prior context on the account is an acceptable substitute; your own reading is not, because you already know the answers.
## Report format
```
PROFILE AUDIT - <account> (<personal | organization>)
Goal on record: <the one outcome this page serves>
Blocking
B1 renders PASS
B2 identifiable FAIL - first screen is a trophy row, no sentence
B3 claims true FAIL - "currently building X" - X archived 14 months ago
B4 next step PASS
Scored 9/16
S1 positioning 1 "full-stack developer passionate about code"
S2 pins 0 pins unset; fallback surfaces an archived fork first
...
Cold reader 2/4 - reader could not answer 2 or 3
Fix order (return per hour spent)
1. B3 - remove or update the two false claims
2. S2 - set six pins, flagship first
3. B2 - one positioning sentence above everything else
moved by owner's answers: hard date on 12 Nov dropped the page rebuild from this pass
```
Order the fix list using SKILL.md § Order the fixes, and re-rank it against the owner's deadline, durability and effort ceiling. Name in the report which answer moved which fix.
references/profile-skeletons.md›
# Profile skeletons and worked examples
Pick the skeleton matching what the _reader_ is deciding, not what the account happens to contain. Every skeleton is a starting order, not a required section list - delete anything the account cannot fill honestly.
## Contents
- Personal: maintainer of a used project
- Personal: DevRel practitioner or advocate
- Personal: engineer building credibility
- Organization: public profile
- Organization: member-only profile
- Worked examples, positive and negative
- Observed patterns on shipped organization profiles
## Personal: maintainer of a used project
Reader is deciding whether to use, trust, or contribute to your work.
1. One sentence: what you build and for whom.
2. The projects, three to six lines, each `name - what it does - who it is for`. No stars.
3. Project status in plain words: maintained, seeking maintainers, feature-frozen.
4. How to reach you for what: bug reports here, security there, commercial questions elsewhere.
5. Optional: funding route, in one line.
Pins carry the weight here: flagship first, then the repositories a contributor or integrator actually opens next.
## Personal: DevRel practitioner or advocate
Reader is a conference organizer, a hiring manager, a potential collaborator, or a developer who just watched your talk.
1. One sentence: the ecosystem you work in and the audience you serve.
2. Recent public work: talks, posts, videos - three items with links, newest first.
3. What you are working on now, with the month it was last true.
4. Where else you are: the four social links plus a personal site.
5. Speaking or collaboration availability, if you want inbound.
Pins here are portfolio artefacts - demos, workshop material, tools you built for talks - not necessarily your most-starred repositories.
## Personal: engineer building credibility
Reader is evaluating capability from public evidence.
1. One sentence: what you do and the stack you do it in.
2. Two or three projects with an outcome each ("handles N requests/day", "used by X").
3. Contributions to other people's projects, linked to merged pull requests rather than claimed.
4. Contact route.
Skip stats widgets entirely: they measure activity, and the reader is judging judgement. The contribution graph is weak evidence in both directions, so let merged pull requests carry the proof.
## Organization: public profile
Reader is a developer sent here from a search result, a talk, a package page, or a job posting.
1. Positioning line: what the organization builds, in the visitor's vocabulary.
2. The open-source stance: what is open, what is commercial, under which licence. One short paragraph, stated plainly.
3. Entry points: two to five named repositories with a one-line "start here if you want to…".
4. One primary call to action: documentation, community, or careers - pick one, not three.
5. Optional: how to contribute, and where support actually happens.
Pins should not simply repeat the repositories named in the README prose; use them to cover a second layer (runtime components, SDKs, examples) so the two surfaces together give a fuller tour.
## Organization: member-only profile
Only build one if someone owns it. Useful content: paved-road repositories, internal onboarding entry points, who to ask for what. It rots faster than the public one because nobody outside sees it - assign an owner and a review date or skip it.
## Worked examples, positive and negative
**Positioning line - personal**
- Weak: `Full-stack developer passionate about clean code and new technologies.` Unfalsifiable, describes half the platform.
- Strong: `I maintain the Rust client for <protocol> and write about database internals. Most of my public work is storage-layer tooling.`
**Positioning line - organization**
- Weak: `We are building the future of developer productivity.` No product, no audience, no verifiable claim.
- Strong: `The Postgres development platform - hosted Postgres with auth, storage and realtime, most of it open source.` Names the technology, the surface area, and the licensing stance.
**Project list entry**
- Weak: `⭐ awesome-thing - 2.3k stars!` Stars are already displayed by the platform; repeating them adds nothing and dates instantly.
- Strong: `awesome-thing - schema diffing for Postgres migrations. Start here if you review migrations in CI.`
**Status line**
- Weak: `🔭 I'm currently working on something exciting!` Unverifiable, and reads as abandoned six months later.
- Strong: `Maintained. Reviewing pull requests weekly; last release 2026-07. Not accepting new feature requests until the 3.0 branch lands.`
**Decoration**
- Weak: a stats card, a streak card, a trophy row, a visitor counter and a typing animation above the first sentence. Five external dependencies, each of which can freeze in the image proxy, and no information a reader can act on.
- Strong: one project banner with alt text, or nothing at all.
**Call to action**
- Weak: five links of equal weight (docs, blog, Discord, Twitter, newsletter, careers).
- Strong: one bolded primary route plus a short "elsewhere" line.
**Audience mismatch - the most expensive mistake here**
An engineer targeting infrastructure teams ships a streak card, a trophy row and a language-percentage donut above their first sentence. It reads as engaged to an early-career peer group and as noise to the senior reviewer they are actually trying to reach - and none of the three widgets can see the private work that is most of their output. The fix is not fewer widgets; it is three pinned original repositories, each with a description and an outcome line, plus the anonymized private-contribution toggle enabled.
**Employed developer with an empty graph**
- Weak: "commit something small every day to rebuild the streak." That is padding evidence, it is visible as padding, and it fixes nothing about the private work it is meant to represent.
- Strong: enable anonymized private-contribution counts, then link two merged pull requests in other people's repositories. Both are checkable; a streak is not.
**Answering "how do I get more stars"**
- Weak: pointing at trending mechanics or promotion cadence as if the profile drove it.
- Strong: naming what stars measure (attention and promotion reach, not adoption or quality), noting that buying them is a detectable, industrialized practice, and redirecting to adoption evidence the page can honestly carry - named users, download counts, release cadence.
## Observed patterns on shipped organization profiles
Read live on 2026-08-26 - treat as evidence of convention, not as a template to copy:
- **Supabase** - tagline "The Postgres Development Platform", verified on two domains. Pins run flagship first, then the runtime components an integrator opens next (realtime, postgres, postgres-meta, client library, auth). Pin order is an architecture tour, not a star ranking.
- **Grafana Labs** - README opens on a banner, then an open-source stance paragraph, then a named four-project block, then "Work with us" linking careers. Pins deliberately add projects the prose does not name (k6, Pyroscope), so the two surfaces cover different ground.
- **Vercel** - one-line positioning, pins mixing the famous open-source asset, the commercial CLI, and newer strategic bets.
None of the three uses stats widgets, visitor counters or trophy rows. All three have a verified domain badge.
references/published-findings.md›
# Published findings on profile work
What is known about whether profile work pays off, which figures are published and which are self-set, and which claims to refuse. Read this before quoting any figure to a user, and before promising a result.
## Contents
- Published claims and their sources
- Self-set baselines (not industry standards)
- Claims to refuse
- Audience divergence
- Practitioner voices
- Why no named framework appears
## Published claims and their sources
| Claim | Source |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Activity traces read as "more reliable and verifiable than a static list of individuals' skills", but only when cheap to verify; the strongest signals are activity history and work on high-status projects | Marlow & Dabbish, CSCW 2013 (predates profile READMEs entirely) |
| Platform activity is only a _partial_ proxy for expertise: high feature values correlate with expertise, but "the proxy fails in the case of developers with low feature values, who can be both experts and novices" | Montandon et al., MSR 2019, tested on 575 developers across three large projects |
| 81% of hiring managers use resumes as the first screening step; small companies weight portfolios more than large ones (80% vs 66%); C-level respondents valued public projects above years of experience | HackerRank 2018 Developer Skills Report (39,000+ developers, 7,000+ employers); the only figure in this space with a disclosed methodology |
| ~6.0 million suspected fake stars across 18,617 repositories running star campaigns, detected over 20TB of public event data (July 2019 – December 2024) | He et al., "Six Million (Suspected) Fake Stars on GitHub", arXiv:2412.13459, ICSE '26 |
| Star growth is driven by promotion, not quality; stars measure attention and reach | Borges & Valente, _Journal of Systems and Software_, 2018 |
| Profile READMEs launched July 2020, quietly; the practice grew out of hobbyist curation lists formed within days, not out of a professional discipline | Simon Willison's dated post (10 July 2020) and the curation repositories that followed it |
| Public-code filters exclude contractors under NDA, people who cannot publish for licensing or security reasons, and compound an existing time-privilege gap | Ashe Dryden, "The Ethics of Unpaid Labor and the OSS Community" |
| "GitHub is all the public work you've ever done, unordered, unfiltered and unexplained. It tells no story and provides no context" | James Coglan, 2013 |
| Measurement is the top unsolved problem in the field (67.3% naming it), and profile-level measurement is not even a tracked category | 10th Annual State of Developer Relations Report |
Two absences matter as much as the published claims:
- No peer-reviewed study measures whether profile changes affect callback rates, and the audit study that would settle it has never been run, so never promise a hiring outcome from profile work.
- No host offers profile-level analytics: repository traffic exists, is limited to 14 trailing days, and requires push access to that specific repository.
## Self-set baselines (not industry standards)
Present these as working defaults, revisable by the owner. Never present them as a published standard.
| Baseline | Value | Why this number |
| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------------------ |
| Scored pass mark | 13 of 16 | Leaves room for one weak area without letting two through |
| Blocking checks | 4, all must pass | Each one is a failure a visitor notices in the first screen |
| Cold-reader window | 45 seconds | Approximates a scan, not a read |
| Cold-reader pass | 4 of 4 (5 of 5 for an organization) | A profile that answers three of four still misroutes a quarter of visitors |
| Decoration cap | 3 visual elements | Each third-party image is a dependency that can freeze in the image proxy |
| Pin count to fill | All 6 | The platform's own limit, and the fallback ordering is worse than any deliberate one |
| Positioning candidates | 3 | Enough to escape the first phrasing, few enough to decide in one pass |
## Claims to refuse
- "60-80% of recruiters check GitHub." Vendor-blog figures citing unnamed "industry surveys" with no traceable methodology. Do not repeat them, even hedged.
- Any promise that a profile rewrite produces interviews, stars, contributors or signups. No study measures this effect in either direction.
- A view-counter badge as evidence anything worked: it increments on every image load through the anonymizing proxy, counting bots and repeat loads, and public scripts inflate it trivially.
- A dense contribution graph as evidence of skill. Backdating a commit is one environment variable, and public tools paint arbitrary shapes into the graph.
- Any specific achievement threshold as durable; achievements are a public preview and the tiers change without notice.
## Audience divergence
The same tactic is a plus for one reader and a cost for another, which is why the skill asks who the profile is for before it advises anything.
| Constituency | Goal | Optimizes | Where advice conflicts |
| --------------------- | ---------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Maintainers | Adoption, contributors | Repository READMEs, contribution guides, organization profile | Reject star-chasing; want real adoption evidence |
| Companies | Awareness, funnel | Organization README, pins, verified badge | Have an investor-optics incentive to care about stars while knowing they are vanity |
| Job-seeking engineers | Get hired | Personal README, pinned original work, activity | Told to optimize a surface many reviewers never open |
The sharpest conflict: maintainer culture reads streak and trophy widgets as noise, while job-seeker advice promotes them. A profile that impresses an early-career peer group can cost credibility with a senior reviewer.
Staged guidance that follows from this:
- **Job seekers, stage 1**: treat the profile as a verification surface, not a discovery surface. Make the resume and a searchable professional profile strong first, then make sure the code host does not contradict them.
- **Job seekers, stage 2**: invest deeper only when the target is small, founder-led, or infrastructure/open-source heavy, where the portfolio genuinely carries weight. Then pin three to six original repositories, enable anonymized private-contribution counts, and skip decorative widgets.
- **Companies, stage 1**: assign ownership before content. The organization profile is a governed brand asset; only organization owners can set pins.
- **Companies, stage 2**: refuse the vanity trade. Never buy stars or tolerate farming; publish adoption evidence (named users, downloads, release cadence) instead. If investors ask for stars, contextualize them next to adoption data rather than optimizing them.
- **Maintainers**: put real adoption evidence in the profile prose, which is the counter-norm serious maintainers already endorse.
## Practitioner voices
- **swyx**, on profile-adjacent metrics he has been asked to track: "GitHub stars on my demos (yuck), traffic attributed to my Google Analytics UTM tag (yuck yuck)... ultimately not meaningful."
- **Braydon Coyer**, on decoration: developers "inject a bunch of 'cool' widgets and badges" when a profile "should highlight what makes you unique."
- **Dewan Ahmed**: developer relations "has the same attribution problem as marketing with none of the agreed proxies."
- A recruiter, on Blind: "I mostly use github to, uh, confirm/find your email." Another: "Interviewed over 150 people. Never looked at any GitHub."
Treat forum testimony as directional counter-evidence to the hype, not as survey data.
## Why no named framework appears
One marketing post coins an acronym framework for profile decisions. It has no evidence base, no adoption outside its own post, and no citations from other practitioners.
Profile optimization is not a headline conference topic in the field, and the discipline has no validated goal-to-decision model, so naming an invented framework would borrow authority the practice has not earned. Use the audience question and the scorecard instead.
Scope limit on everything above: the studies cited are English-language and US-centric. They do not cover hiring and developer-relations practice elsewhere; say so if a user's context is outside that scope.
scripts/profile-audit.py›
#!/usr/bin/env python3
"""Emit mechanical facts about a public GitHub personal or organization profile.
Usage: profile-audit.py <username-or-org>
Reads the public REST API; no authentication required. Set GITHUB_TOKEN to raise
the hourly rate limit and to include pinned items, which are only exposed through
the authenticated GraphQL API. Judgement stays with the caller: this script
reports numbers and never says whether they are good.
"""
import json
import os
import re
import sys
import urllib.error
import urllib.request
API = "https://api.github.com"
WIDGET_HOSTS = [
"github-readme-stats",
"github-readme-streak-stats",
"github-profile-trophy",
"readme-typing-svg",
"github-readme-activity-graph",
"visitor-badge",
"komarev.com/ghpvc",
"hits.seeyoufarm.com",
"wakatime",
"spotify-github-profile",
"leetcode",
]
BIO_LIMIT = 160
SOCIAL_LIMIT = 4
PIN_LIMIT = 6
def get(path, accept="application/vnd.github+json"):
req = urllib.request.Request(API + path, headers={"Accept": accept, "User-Agent": "profile-audit"})
token = os.environ.get("GITHUB_TOKEN")
if token:
req.add_header("Authorization", "Bearer " + token)
try:
with urllib.request.urlopen(req, timeout=20) as resp:
body = resp.read().decode("utf-8", "replace")
return json.loads(body) if accept.endswith("json") else body
except urllib.error.HTTPError as err:
if err.code == 404:
return None
if err.code in (403, 429):
sys.exit("RATE LIMITED or FORBIDDEN on %s — set GITHUB_TOKEN and retry" % path)
raise
def graphql_pins(login):
token = os.environ.get("GITHUB_TOKEN")
if not token:
return None
query = (
'{"query":"{ repositoryOwner(login: \\"%s\\") { pinnedItems(first: 6, types: [REPOSITORY, GIST]) '
'{ totalCount nodes { ... on Repository { nameWithOwner stargazerCount pushedAt } '
'... on Gist { name } } } } }"}' % login
)
req = urllib.request.Request(
"https://api.github.com/graphql",
data=query.encode(),
headers={"Authorization": "Bearer " + token, "User-Agent": "profile-audit"},
)
with urllib.request.urlopen(req, timeout=20) as resp:
return json.loads(resp.read().decode())["data"]["repositoryOwner"]["pinnedItems"]
def readme_facts(text):
images = re.findall(r"!\[([^\]]*)\]\(([^)]+)\)", text)
html_images = re.findall(r"<img\s[^>]*>", text, re.I)
no_alt = [src for alt, src in images if not alt.strip()]
no_alt += [tag for tag in html_images if not re.search(r"alt\s*=", tag, re.I)]
widgets = sorted({w for w in WIDGET_HOSTS if w in text})
links = re.findall(r"\]\((https?://[^)]+)\)", text)
stale_phrases = [
p
for p in ["currently working on", "🔭", "right now I", "this year", "2019", "2020", "2021", "2022", "2023"]
if p.lower() in text.lower()
]
return {
"words": len(text.split()),
"images": len(images) + len(html_images),
"images_without_alt": len(no_alt),
"widgets": widgets,
"links": len(links),
"headings": re.findall(r"^#{1,6} .*", text, re.M),
"time_bound_phrases": stale_phrases,
}
def main():
if len(sys.argv) != 2:
sys.exit(__doc__)
login = sys.argv[1].strip().strip("/").split("/")[-1]
owner = get("/users/" + login)
if owner is None:
sys.exit("NOT FOUND: no user or organization named %s" % login)
is_org = owner.get("type") == "Organization"
if is_org:
# /users/<org> omits is_verified and twitter_username; /orgs/<org> carries them.
owner.update(get("/orgs/" + login) or {})
print("TARGET: %s (%s)" % (login, "organization" if is_org else "user"))
print("FOLLOWERS: %s PUBLIC REPOS: %s CREATED: %s" % (owner.get("followers"), owner.get("public_repos"), owner.get("created_at")))
bio = owner.get("bio") or owner.get("description") or ""
print("\nPROFILE FIELDS")
print(" name: %r" % (owner.get("name") or ""))
print(" bio/description: %d/%d chars %s" % (len(bio), BIO_LIMIT, "EMPTY" if not bio else ""))
print(" website: %r" % (owner.get("blog") or ""))
print(" company: %r location: %r" % (owner.get("company") or "", owner.get("location") or ""))
if owner.get("is_verified") is not None:
print(" verified domain badge: %s" % owner.get("is_verified"))
if not is_org:
socials = get("/users/%s/social_accounts" % login) or []
print(" social links: %d/%d %s" % (len(socials), SOCIAL_LIMIT, [s.get("url") for s in socials]))
print("\nPROFILE README")
if is_org:
meta = get("/repos/%s/.github/contents/profile/README.md" % login)
location = "%s/.github → profile/README.md" % login
commits = get("/repos/%s/.github/commits?path=profile/README.md&per_page=1" % login)
else:
meta = get("/repos/%s/%s/readme" % (login, login))
location = "%s/%s → README.md" % (login, login)
commits = get("/repos/%s/%s/commits?path=README.md&per_page=1" % (login, login))
if not meta:
print(" MISSING at %s — the profile page shows no README" % location)
else:
print(" found at %s (%s bytes)" % (location, meta.get("size")))
if commits:
print(" last edited: %s" % commits[0]["commit"]["committer"]["date"])
else:
repo = get("/repos/%s/.github" % login) if is_org else get("/repos/%s/%s" % (login, login))
if repo:
print(" last push to the hosting repository: %s" % repo.get("pushed_at"))
with urllib.request.urlopen(urllib.request.Request(meta["download_url"], headers={"User-Agent": "profile-audit"}), timeout=20) as resp:
raw = resp.read().decode("utf-8", "replace")
facts = readme_facts(raw)
print(" words: %d links: %d images: %d (%d without alt text)" % (facts["words"], facts["links"], facts["images"], facts["images_without_alt"]))
print(" headings: %s" % (facts["headings"] or "(none)"))
if facts["widgets"]:
print(" third-party widgets: %s [each is an external dependency the image proxy can cache stale]" % ", ".join(facts["widgets"]))
if facts["time_bound_phrases"]:
print(" time-bound phrasing found: %s [check it is still true]" % ", ".join(facts["time_bound_phrases"]))
print("\nPINNED ITEMS")
pins = graphql_pins(login)
if pins is None:
print(" UNAVAILABLE without GITHUB_TOKEN — read them off the profile page instead (limit %d)" % PIN_LIMIT)
else:
print(" %d/%d used" % (pins["totalCount"], PIN_LIMIT))
for node in pins["nodes"]:
print(" %s" % json.dumps(node))
print("\nMOST-STARRED PUBLIC REPOSITORIES (what a visitor finds when pins are unset)")
repos = get("/users/%s/repos?per_page=100&type=owner&sort=updated" % login) or []
top = sorted(repos, key=lambda r: r.get("stargazers_count", 0), reverse=True)[:8]
for repo in top:
flags = []
if not repo.get("description"):
flags.append("no description")
if not repo.get("topics"):
flags.append("no topics")
if repo.get("archived"):
flags.append("archived")
if repo.get("fork"):
flags.append("fork")
print(" %-40s %6d★ pushed %s %s" % (repo["name"], repo.get("stargazers_count", 0), (repo.get("pushed_at") or "")[:10], ", ".join(flags)))
if len(repos) == 100:
print(" (first 100 repositories only — re-run against the full list if the account has more)")
if __name__ == "__main__":
main()
SKILL.md›
---
name: github-profile-optimization
description: Audits and rebuilds a personal or organization profile on GitHub as a developer-relations surface - the profile README, the six pinned items, bio and social fields, the organization profile repository, and the contribution signals visitors read as evidence. Use whenever someone says "optimize my GitHub profile", "profile README", "our GitHub org page is empty", "what should I pin", "nobody knows what our company builds on GitHub", or is preparing a launch, a talk or a job search - even if they only mention their GitHub page. Covers solo maintainers, company organizations, and engineers whose profile gets read during hiring. GitHub-scoped: the audit script and pin/contribution-graph mechanics are GitHub-specific, though the checklist reasoning transfers by hand to another forge. Not a single repository's README - use samber/developer-relations-skills@readme-optimization.
license: MIT
metadata:
author: Samuel Berthe
version: "1.0.2"
---
# GitHub Profile Optimization
You are working on the page a developer lands on after a talk, a package listing, a search result, or a job posting; it's the one an evaluator opens to decide whether the people behind a project are real. Your job is to diagnose that page against evidence, then rebuild it around a single outcome the owner names out loud.
Two constraints shape everything:
- The profile README and the six pinned items are the only editorial control the account has; everything else on the page (stars, languages, the contribution graph) is generated and cannot be argued with.
- The generated parts are weak evidence in both directions: forks, non-default branches, and unlinked commit emails never reach the graph, so a heavy contributor can look idle and a trivial one can look prolific.
## Calibrate what you promise
Most advice in this genre comes from people with a tool or a course to sell, and the independent evidence is thinner than they let on. Read [./references/published-findings.md](./references/published-findings.md) before quoting a figure or forecasting a result. What it settles:
- The profile is a **verification** surface, not a discovery one. Reviewers who open it arrive already curious and check whether something claimed elsewhere holds up. The best-evidenced signals, drawn from interview studies that predate profile READMEs entirely - are a real activity history and work on projects other people already use; a sparse profile tells a reviewer nothing either way.
- **Every threshold here is self-set.** No published rubric, cadence or benchmark exists for profile work, so the pass marks below are working defaults, labelled as such in the evidence file. Offer them as defaults the owner can move, never as an industry standard.
- **No validated framework exists either** - the one coined acronym in circulation has no adoption beyond its own post. Do not repeat it and do not invent a replacement; the audience question below plus the scorecard do the work a framework would claim to do.
Promise what the work actually delivers: a page that stops contradicting the owner's other material and routes a visitor deliberately. Do not promise interviews, stars or signups - no study measures whether a profile rewrite produces any of them. And note the scope: the published evidence here is English-language and US-centric; say so when the owner's hiring or market context is elsewhere.
Stay on the profile surfaces. Route to a sibling skill when the user's real problem is one of these, rather than stretching the profile to carry it:
- A single repository's README: samber/developer-relations-skills@readme-optimization
- The launch announcement: samber/developer-relations-skills@oss-launch
- Ongoing channel presence: samber/developer-relations-skills@oss-distribution-strategy
- The first-contribution path: samber/developer-relations-skills@oss-contributor-onboarding
- Sponsorship tiers and funding goals: samber/developer-relations-skills@oss-sponsors-fundraising
- Career positioning, interviews and progression: samber/developer-relations-skills@devrel-career
Typical invocations: "audit my GitHub profile", "rewrite our org profile README", "which six repos should we pin", "our GitHub looks abandoned but we ship weekly", "make my profile readable by a conference organizer".
Some asks deserve a redirect rather than a rewrite. "Get me more stars" and "fill my contribution graph" are requests to manufacture evidence, and "make my profile rank" asks for a lever the platform does not have. Say which it is, explain what it would cost in front of the reviewers who matter, and offer the audit instead - the goal underneath is usually legitimate even when the ask is not.
## Interview
Ask one question at a time, offer choices where you can, and skip anything you can determine yourself from the audit output. Questions 1-4 gate the rewrite: do not draft prose before they are answered.
**Memory: Store a few info about the current task or project context. When memory lives in a file, use `devrel-context.md`; if a different memory system is in use, rely on that instead. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.**
1. Which account, and is it a personal profile or an organization?
2. Are you a maintainer after adoption and contributors, a company building developer awareness, or an engineer whose profile faces hiring scrutiny? Everything downstream branches on this answer.
3. What is the one outcome this page should produce more of: project adoption, contributors, inbound from companies, speaking and collaboration invitations, job or client leads, or sponsorship?
4. Who lands here most: developers arriving from a repository or package page, developers arriving from a talk or article, hiring managers and recruiters, or company evaluators sizing up the team behind a tool?
5. Individual adoption or company adoption? A developer deciding alone reads for capability; a team reads for maintenance, licensing and who to call when it breaks. Both is a valid answer.
6. What must the reader be able to do next - open a specific repository, read the docs, join a community, book a call, or contact you?
7. What is honestly true right now about activity: shipping weekly, maintaining, between projects, or dormant?
8. Anything on the page you are attached to and do not want touched?
9. For an organization: what is open source and what is commercial, and do you want that stated plainly?
10. Who owns this page after today, and what event will trigger the next review?
11. Is there a date this has to be right by - a launch, a talk, a funding round, an interview loop - or is it just overdue?
12. Do you want a one-off clean-up before that date, or a page that keeps working: a positioning sentence and a review habit you reuse for years?
13. What is your ceiling - an afternoon, a week of someone's time, a standing owner, a sign-off from legal or marketing on what you can say publicly?
Question 10 is not administrative. An unowned profile keeps a claim that was true when written, and a stale claim costs more trust than an empty page.
Answers 11-13 re-rank the fix order in Step 2; say which answer moved which fix when presenting it:
- A hard date promotes the near-zero fixes and drops the full page rebuild from this pass.
- A compounding mandate promotes the positioning sentence, which propagates into the bio, the org tagline and every link unfurl, and promotes the review habit that would otherwise never win on ratio.
- A ceiling with no standing owner deletes that habit outright rather than logging it as future work.
If question 2 lands on the hiring case, check the target before recommending much work. The one survey in this space with a disclosed methodology (from 2018, so treat it as dated) found portfolio weight concentrated at small and founder-led companies, and the recruiter testimony on record is largely indifferent to the surface.
A candidate aiming at large employers should invest in the resume first and use the profile only to avoid contradicting it. The staged, per-audience guidance is in [./references/published-findings.md](./references/published-findings.md).
## Step 1 - Collect the facts
Never audit from memory of what good profiles look like.
1. Run `scripts/profile-audit.py <account>` if the profile lives on GitHub and you can execute commands and reach the network - the script calls GitHub's own REST and GraphQL APIs and has no equivalent for GitLab, Codeberg or a self-hosted forge. It reports profile fields against their limits, whether the profile README renders and where it lives, its word/link/image counts, third-party widgets, time-bound phrasing, and the repositories a visitor finds when pins are unset. Set `GITHUB_TOKEN` to include pinned items and raise the rate limit. On any other host, apply the same checklist by hand from the profile page itself.
2. If you cannot run the script, open the profile page yourself (browse it, or ask the user to paste the README and list the pins). Say plainly which facts you could not verify instead of assuming them.
3. Open every link on the page and record the dead ones - a dead link fails a blocking check and takes minutes to fix.
4. Read the pinned repositories as a stranger would: does each have a description, topics, and a recent push?
5. If your environment has persistent memory, load any stored positioning statement, audience definition or competitor list for this account and reuse it rather than re-deriving it.
The script reports facts, not judgements. Fifteen images is not automatically wrong; it is a question to answer.
## Step 2 - Score the page
Work through [./references/profile-scorecard.md](./references/profile-scorecard.md) and produce its report format verbatim: four blocking checks, eight scored checks worth two points each, then the fix order below.
Attach evidence to every line - a quoted sentence, a field value, a line of script output. Present the score and get the owner's agreement before rewriting. A constraint you cannot see from outside (an employer policy, a deliberate minimalism) can justify a check you scored zero, and the owner is sometimes right.
Say once, when presenting the score, that the checks and the pass mark are this skill's own baseline rather than a published standard. An owner who moves the bar with a reason is not failing the audit; an owner who moves it because the page is easier to leave alone is.
### Order the fixes
Order the fix list by what each returns per hour spent, not by how much damage it undoes and not by how fast it is to finish - the three orderings disagree, so state them and lead with the last:
- effort, least first: `false claims == render prerequisites > private-contribution toggle > pins > positioning sentence > page rebuild > review habit`
- value, most first: `false claims > positioning sentence > pins > page rebuild > render prerequisites > review habit > private-contribution toggle`
- efficiency, do first: `false claims == render prerequisites > pins > positioning sentence > private-contribution toggle > page rebuild > review habit`
Killing a false claim and repairing the render tie on both axes, which is why they tie on efficiency. Each takes minutes, each is blocking, and each fixes a page that is _wrong_ rather than one that is merely weak - a reader cannot evaluate either kind of broken page at all. The private-contribution toggle sits lower than its near-zero effort suggests because it only helps the specific account whose public graph misrepresents real private work; for everyone else it changes nothing.
Default to the top three, an afternoon between them. Move to the positioning sentence when the owner can already say what the account is for, and to the page rebuild only when the cold-reader test fails on questions the top rungs do not touch.
The review habit is what this order starves: it is a standing job against fixes that land in minutes, so it loses every round. It is the only item that stops the page drifting false again, the failure this whole skill treats as most expensive.
Promote it above everything when:
- Answer 7 is "shipping weekly" or the account belongs to an organization, where the page goes stale fastest and nobody notices.
- This is the second audit of the same account.
The ordering is a default, not a law, and it shifts with who executes it. Re-rank it against what you already know:
- An owner with an existing positioning sentence from a launch or a talk gets that rung nearly free and should take it first.
- An account whose pins are already deliberate drops that row rather than re-deciding it.
Delete every fix answer 13's ceiling rules out instead of listing it last - an organization with no marketing sign-off does not get a "state what is commercial" line parked at the bottom of the plan, it gets that row removed and the reason recorded.
## Step 3 - Fix what is false before improving what is weak
These are the top rung of the fix order, and they hold that place on the ratio rather than in spite of it: each costs minutes, and each removes something that makes the page actively wrong instead of merely weak.
1. Remove or update every claim a reader can disprove: archived "currently building" projects, former employers, dead links, superseded roles.
2. Repair anything that breaks the render - see [./references/platform-mechanics.md](./references/platform-mechanics.md) for the four prerequisites that make a profile README appear at all, and the organization equivalents.
3. Replace a stale time-bound line with a dated one, or delete it. "Currently exploring X" with no date is a claim about today that nobody updates.
Only then move on to positioning and structure.
## Step 4 - Brainstorm the positioning before writing it
Do not reach for the first phrasing. Draft three candidate positioning sentences on different axes - what you build mechanically, what problem you remove for the reader, what the reader can stop doing. Present them with the trade-off of each plus your recommendation. Let the owner choose.
This sentence propagates into the bio, the organization tagline, link unfurls and search listings, so it earns the extra pass. Test each candidate against one question: could a competitor's account paste this sentence unchanged? If yes, it says nothing.
## Step 5 - Rebuild the page
Pick the skeleton from [./references/profile-skeletons.md](./references/profile-skeletons.md) that matches what the reader is deciding - maintainer, DevRel practitioner, engineer building credibility, or organization. Draft one section at a time and get agreement before moving on; a profile rewritten in one pass gets rejected in one pass.
Adjust for how adoption happens, because the two motions diverge after the first screen:
| | Individual developer adopts alone | Team or company adopts |
| ------------------ | ------------------------------------------------- | ------------------------------------------------------------------ |
| Dominant question | Can this person build the thing I need? | What are we depending on, and who answers when it breaks? |
| Must surface early | The work itself, running, with an entry point | Licensing stance, maintenance cadence, support and security routes |
| Proof that lands | Merged pull requests, a demo, a readable codebase | Named users, release cadence, funding model, team visibility |
| Fatal omission | No obvious first repository | No answer to "who maintains this" |
The first screen is identical in both cases: who this is, what they build, which project to open first. Serve both audiences by adding a short evaluation block lower down, not by rewriting the top twice.
Rules that apply to every skeleton:
1. Put one sentence of prose above every image, badge and widget.
2. Cap decoration at three visual elements, each with alt text and each earning its place. Third-party stats and streak cards are external dependencies that the host's image proxy can cache stale indefinitely; a frozen widget is worse than no widget.
3. Say what is _not_ true: what you are not maintaining, what is commercial, what you will not take feature requests on. This is the highest-trust content on the page and it costs one line.
4. Give each pinned repository a description and topics before pinning it - a bare pin wastes one of six slots. This skill only requires that they exist; for how to write them well, see samber/developer-relations-skills@readme-optimization's furniture step.
5. Keep the page readable where rendered HTML is stripped: no meaning encoded in colour alone, no instruction that exists only inside an image.
Run the finished prose through your preferred humanizer skill. Profile copy that reads as generated undercuts the exact credibility the page exists to build.
## Step 6 - Set the pins deliberately
Six pins (six public plus six member-visible for an organization) are the only control you have over what a visitor clicks next. Choose them against the goal from question 3, not by star count.
These four sets are not ranked against each other and should not be: answer 3 selects one outright, and every pin costs the same nothing to set, so an efficiency order across them would be invented precision. The order _within_ each set is real - it decides which repository a visitor opens first.
- **Adoption**: flagship first, then the SDK or integration a new user needs second.
- **Contributors**: the repository with curated good-first-issues, then the one with the best contributor docs.
- **Credibility or hiring**: the work that shows judgement, even at low stars - a well-reviewed tool beats a popular list of links.
- **Organization**: an entry-point tour rather than a leaderboard; cover repositories the README prose does not already name, so the two surfaces together give a fuller picture.
Never pin an archived repository, a fork you did not substantially change, or an empty placeholder. Leaving pins unset is worse: the platform then auto-selects "Popular repositories", which often surfaces something abandoned.
## Step 7 - Handle contribution signals honestly
Read [./references/platform-mechanics.md](./references/platform-mechanics.md) before commenting on the graph or the achievements.
Three honest moves are available, and they are an order of magnitude apart:
- efficiency, do first: `private-contribution toggle > mechanical graph causes > merged pull requests elsewhere`
- Reach for the private-contribution toggle first when an employed developer's graph looks dead. It is one setting, and most of their work is private - so "freshness" here is a setting, not new public work.
- Fix the mechanical causes of a misleadingly empty graph next: unlinked commit emails, work that only ever lands on feature branches, contributions made in forks that never merged upstream. An hour to diagnose, then a habit to keep.
- Merged pull requests in other people's repositories are what this order starves: a quarter of real work, so they never win on ratio. They are still the single best-evidenced signal in the whole skill, since reviewers in the interview studies weight work on projects other people already use above everything else on the page. Promote them to first when answer 3 is credibility, hiring or collaboration invitations - nothing cheaper substitutes for them there, and they are checkable where the graph is not.
- Never advise commit padding, streak farming, star buying, or gaming the achievements. Reviewers who follow this space already discount all three signals:
- Backdating a commit takes one environment variable.
- Public tools paint pictures into the graph.
- Star fraud runs at industrial scale: a five-and-a-half-year study of public event data counted roughly six million suspected fake stars across more than eighteen thousand repositories.
- Refuse these asks by name when an owner makes one: say what the tactic is, that reviewers discount it, and what you would do instead. They are deleted from the menu, not ranked last on it - a tactic parked at the bottom of a plan comes back as scope, and this one comes back as fabricated evidence.
- Treat streak and trophy widgets as a credibility trade, not a neutral decoration: they read as noise to senior technical reviewers and cannot see private work at all.
## Step 8 - Verify, then keep it alive
1. Re-run the scorecard. Ship when all four blocking checks pass and the scored total reaches **13/16** - this skill's own baseline, not a published bar. Below it, iterate rather than shipping with a caveat.
2. Run the cold-reader test from the scorecard: 45 seconds on the page, then four questions (five for an organization). Every answer correct is the pass - four of four, five of five for an organization. A fresh agent session with no context on the account is an acceptable stand-in when no person is available; your own reading is not.
3. Record the owner and the **events** that trigger the next review - a launch, a talk, a funding round, a major release, a role change, a job search. No evidence supports a fixed calendar cadence, and a quarterly reminder nobody honours is worse than a trigger list the owner recognizes. Put the list and the last-reviewed date in the file as a comment if nothing else will hold it.
4. If your environment has persistent memory, store the agreed positioning sentence, the audience, the goal and the final score, so the launch post, the conference bio and the docs landing page start from the same words.
## What to track afterwards
- efficiency, track first: `tagged click-through > pinned-repository traffic > qualified inbound`
Build each of the three in the order above:
- **Tagged click-through**: tagged links from the profile to a destination the owner controls - docs, product, community. It costs an hour to set up, the destination's analytics belong to the owner, and it is the only number here that survives scrutiny.
- **Pinned-repository traffic**: free but nearly useless on its own, limited to a trailing 14-day window and to repositories the owner can push to.
- **Qualified inbound**: what this order starves - reading it takes a standing habit and a quarter before it says anything. For an organization it is the only evidence the page changed anyone's behaviour, so promote it there and start counting from the ship date.
Qualified inbound reads differently per audience: for an organization it is a prospect who already knows what you build instead of asking, and for a practitioner it is a speaking or collaboration approach that references something the profile surfaces.
Everything else is partial. No host offers profile-level analytics, and nothing here isolates the profile's effect - write down the date you shipped, and annotate every confounder.
Delete two numbers from the plan rather than ranking them last:
- A README view-counter badge counts image requests through an anonymizing proxy (bots and repeat loads included) and public scripts inflate it, so it is decoration, not data.
- Star growth after a profile change is unattributable and, at the company level, actively gamed. Stars are known to follow promotion (a release, a talk, a mention elsewhere) rather than the page.
Assume the same of every other number here.
## Common failure modes
- **Decorating before diagnosing.** Adding widgets to a page whose first claim is false makes the false claim prettier. Score first.
- **One checklist for every audience.** A streak widget signals engagement to an early-career peer group and noise to the maintainer or hiring manager the owner actually needs to reach. Answer question 2 before recommending a single element.
- **Overselling the surface.** Nobody has measured whether a rewrite produces interviews or contributors; promising either invents an effect, and the owner notices when it never arrives. Promise clarity and consistency - the page genuinely delivers those.
- **Star-ranked pins.** The platform already shows star counts. Pins ordered by popularity waste the one editorial lever on repeating information the visitor can see.
- **Widget dependency.** Every third-party card is a service that can go down, rate-limit, or freeze in the image proxy. Keep at most one, and check it renders from a logged-out session.
- **Writing the organization profile as a second marketing site.** The visitor came to GitHub for the code. The page's job is to say which repository to open first and what is open source - the website already does the rest.
- **Treating the contribution graph as a scoreboard.** Advising anyone to fill it is advising them to fake evidence, and readers who know the counting rules discount the graph anyway.
- **Leaving the page unowned.** An unowned profile drifts false: the claim that was true when written stays up long after it stops being true. Name the owner and the review triggers in the same session as the rewrite.
- **Copying a template wholesale.** A profile that reads like ten thousand others is a profile the reader skips. Skeletons set the order; the sentences have to be the account's own.
## Reference
- [./references/published-findings.md](./references/published-findings.md) - which figures are published, which are self-set, the per-audience staged guidance, and the claims to refuse
- [./references/profile-scorecard.md](./references/profile-scorecard.md) - blocking and scored checks, thresholds, cold-reader test and report format
- [./references/profile-skeletons.md](./references/profile-skeletons.md) - per-audience section orders, worked positive and negative examples, and patterns observed on shipped organization profiles
- [./references/platform-mechanics.md](./references/platform-mechanics.md) - README prerequisites, field and pin limits, contribution-graph counting rules, achievements and image-proxy behaviour
- `samber/developer-platform-skills@github-engagement-playbook` - one pinned repository's own GitHub surfaces: Discussions, release notifications, topics, star policy