reference-first skill
✓ VerifiedEnsures design decisions for APIs, schemas, and architectures are based on inspected, cited, and verified external or internal references.
- GitHub stars
- 119
- Files
- 5
- Last commit
- Nov 9, 2026
- License
- MIT
- Allowed tools
- —
What does the reference-first skill do?
reference-first ensures design decisions for APIs, schemas, and architectures are based on inspected, cited, and verified external or internal references.
Summary generated from the skill's SKILL.md.
About the reference-first skill
Architects and developers who need to design APIs, database schemas, or CI/CD pipelines use this skill to ensure their work is based on verified industry standards rather than assumptions. Instead of guessing how to implement a feature like authentication or pagination, an agent loads this skill to find, inspect, and cite existing open-source implementations, RFCs, or official product documentation. It produces a cited blueprint that details specific decisions and the sources justifying them before any code is written.
The process begins by checking for internal precedents using godmode:codebase-conventions to maintain repository consistency. If no internal pattern exists, the skill routes the task to appropriate channels such as GitHub search or specific reference libraries for system design and testing. It enforces a strict protocol of opening and reading documentation within the current session to avoid relying on outdated memory. This approach prevents common mistakes in error modeling, event formats, and module boundaries by requiring multiple credible candidates to be scored and synthesized into a final plan.
What an agent can do with it
- 1Designing a standardized APIAn agent should find and cite official documentation to define how a new webhook or error model should behave.
- 2Establishing database schemasA developer can use this to create data structures for common domains like billing or messaging based on proven shapes.
- 3Selecting technical librariesWhen choosing between different tools for a specific job, the skill evaluates them against quality and maintenance criteria.
- 4Setting up deployment pipelinesUse this to research and implement a professional test strategy or CI/CD release pipeline.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the reference-first skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the reference-first skill in Plugin
/plugin marketplace add NoobyGains/godmode /plugin install godmode@godmode
Install the reference-first skill in Claude Code
~/.claude/skills/reference-first/SKILL.md
$ npx degit NoobyGains/godmode/skills/reference-first ~/.claude/skills/reference-firstInstall the reference-first skill in Claude Code (project)
.claude/skills/reference-first/SKILL.md
$ npx degit NoobyGains/godmode/skills/reference-first .claude/skills/reference-firstInstall the reference-first skill in Codex
~/.agents/skills/reference-first/SKILL.md
$ npx degit NoobyGains/godmode/skills/reference-first ~/.agents/skills/reference-firstInstall the reference-first skill in Gemini CLI
~/.gemini/skills/reference-first/SKILL.md
$ npx degit NoobyGains/godmode/skills/reference-first ~/.gemini/skills/reference-firstInstall the reference-first skill in Claude.ai
npx degit NoobyGains/godmode/skills/reference-first reference-first && zip -r reference-first.zip reference-first # claude.ai → Customize → Skills → + → Create skill → Upload a skill → reference-first.zip
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablenoobygains/godmode/skills/reference-first is public and reachablegithub.com/noobygains/godmode/tree/HEAD/skills/reference-fir ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-09github.com/noobygains/godmode/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/noobygains/godmode/blob/HEAD/skills/reference-fir ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/noobygains/godmode/blob/HEAD/skills/reference-fir ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 176 linesgithub.com/noobygains/godmode/blob/HEAD/skills/reference-fir ↗Pass
SKILL.md
View on GitHubReference First
Most things you are asked to build have been built before by teams who spent months on them and fixed the incidents that followed. This skill routes each task to the right kind of reference, finds two or three good ones, and turns them into a short, cited blueprint before any code is written. Build on a named, inspected reference, never on what seems plausible.
The Prime Directive
NO DESIGN WITHOUT A NAMED, INSPECTED REFERENCE
No exceptions. No workarounds. No shortcuts.
A reference you remember is not a reference. A reference counts once you have opened it in this session, read the part you are borrowing, and can link to it.
When to Use
Required:
- Designing a public or internal API, webhook, event format or error model.
- Designing a database schema for a domain with known shapes (users and roles, bookings, orders, billing, content, messaging).
- Choosing a test strategy or setting up CI/CD for a project.
- Making an architecture or module-boundary decision.
- Building a feature that plausibly exists as a library, starter or open-source project (auth, uploads, search, queues, payments, editors, games).
- Picking between several libraries for the same job.
Skip:
- Adding code inside an existing codebase that already has a precedent for it. The precedent is the reference: invoke
godmode:codebase-conventionsinstead. - One-line fixes, renames, and changes whose shape the user has fully specified.
- The user has named the reference ("do it the way Stripe does pagination"). Open that reference and use it; skip the search.
Route First
Classify the task, then send it where the references live. One task can touch more than one row.
| The task is about | Route to |
|---|---|
| Code inside an existing repository | godmode:codebase-conventions (internal precedent beats external reference) |
| Any screen, page, component or visual design | godmode:ui-research, then godmode:ui-engineering |
| Architecture, hosting, databases, queues, auth strategy | godmode:system-design, with the architecture references |
| API, webhook, error format, schema | this skill, API and schema references |
| Test strategy, CI/CD, release pipeline | this skill, testing and CI references |
| A library, starter or open-source implementation | this skill, GitHub and registry search |
| A fact that can change (an API's current behaviour, a flag, a version, a limit) | godmode:grounding before you rely on it |
The libraries in references/ are starting points that were checked when they were written. They are not proof: re-open the page before you cite it, because documentation moves.
The Protocol
-
State the need in one sentence. What exactly must the reference answer? "How should list endpoints paginate" is a need; "API design" is not. Write it down; it keeps the search narrow.
-
Check the internal precedent first. If the repository already does this somewhere, that wins over any external reference unless the user agrees to change it. Hand off to
godmode:codebase-conventionsand stop here if a precedent exists. -
Pick the reference class. Use the route table. Within a class, prefer in this order: a published standard or RFC, the official documentation of a product known for the pattern, a mature open-source implementation, a curated list, a blog post. Lower rungs need more corroboration.
-
Find candidates. Search with at least three different phrasings across at least two channels (the reference library, GitHub search, a package registry, a web search). The method and query templates are in github-search.md. Stop at three to five serious candidates.
-
Inspect, do not skim. For each candidate, open the actual page, file or schema and read the part you intend to borrow. Record the URL, what it shows, the licence (for code), when it was last updated, and why it is credible. Drop any candidate you cannot open.
-
Score the candidates against the quality criteria below. Discard anything that fails a hard gate.
-
Synthesise. Take each concern from the reference that handles it best, and say which reference each decision came from. Resolve conflicts between references explicitly; do not average them. Mark what is genuinely new to this project.
-
Present and confirm. Show the user the blueprint before building when the choice is consequential (a public API shape, a schema, an architecture, a new dependency). Use the format below. Wait for a choice when the options differ materially; proceed when there is one clear winner and the user has already approved the direction.
-
Record the sources. Put the reference URLs in the design document or plan, next to the decision they justify, and in code comments where a non-obvious pattern was borrowed. A later reader must be able to follow the link and see why.
digraph reference_first {
rankdir=TB;
need [label="State the need"];
internal [label="Precedent in this repo?", shape=diamond];
conv [label="godmode:codebase-conventions", shape=box];
route [label="Route by domain"];
search [label="Search: 3 phrasings, 2 channels"];
found [label="Candidates found?", shape=diamond];
inspect [label="Open, read, score"];
none [label="Record searches;\ndesign deliberately"];
synth [label="Synthesise, cite, present"];
need -> internal;
internal -> conv [label="yes"];
internal -> route [label="no"];
route -> search -> found;
found -> inspect [label="yes"];
found -> none [label="no"];
inspect -> synth;
}
Reference Quality Criteria
| Criterion | Strong signal | Weak signal |
|---|---|---|
| Authority | Standard, RFC, or the vendor's own documentation | Unsourced blog post, AI-generated summary |
| Production use | Run by real organisations at the scale you need | Demo or tutorial code |
| Maintenance | Commits or doc updates in the last year | Archived, or untouched for years |
| Fit | Solves your stated need directly | Adjacent problem, needs heavy adaptation |
| Clarity | The pattern can be explained in a paragraph | You cannot tell which part does the work |
| Licence (code) | OSI licence compatible with the project | No licence file, or copyleft you cannot honour |
| Evidence | Tests, changelog, documented trade-offs | No tests, no docs |
Hard gates: you opened it this session; it does what you need; for copied code, the licence allows it.
Licence Compatibility
Ideas and patterns can be studied freely; code is covered by its licence. Before any code moves from a reference into the project:
- Read the reference's
LICENSEfile, not only the badge or the registry metadata (registries often sayNOASSERTIONor "see licence file"). - Check compatibility with the project's licence using the table in github-search.md.
- No licence means default copyright: study it, do not copy it.
- Keep required notices (an Apache-2.0
NOTICEfile, MIT copyright lines) with the copied code. - When unsure, re-implement the pattern from its description rather than copying, and tell the user.
Presenting the Blueprint
Need: <one sentence>
References inspected:
A) <name> - <url> - <licence if code> - <why credible>
Borrow: <the specific pattern>
B) <name> - <url> - ...
Borrow: <...>
Blueprint (recommended):
- <decision 1> (from A)
- <decision 2> (from B; A does X instead, rejected because ...)
- <decision 3> (new to this project; no reference covers it)
Searched and rejected: <what, and why>
When no reference fits after a real search, say so plainly: list the queries and channels, design deliberately, and mark the result as unreferenced so reviewers look harder at it.
Cognitive Traps
| Rationalisation | Truth |
|---|---|
| "I know how Stripe does this." | You remember a version of it. Open the page; Stripe now ships a new API version every month. |
| "This is too simple to need a reference." | Simple shapes (pagination, errors, IDs) are copied into every endpoint. Mistakes there multiply. |
| "Nothing like this exists." | You searched with one phrasing. Try three, including synonyms and the problem statement. |
| "One good reference is enough." | One reference gives you its blind spots. Two or three show which choices are deliberate. |
| "The user did not ask for research." | They asked for something that works. Ten minutes of reading is cheaper than a redesign. |
| "It is open source, so I can copy it." | Open source has licences. No licence means no permission. |
| "I will look for references if I get stuck." | By then the structure is set. References matter most before the first decision. |
| "The reference is old, so it is wrong." | Age is a prompt to check, not a verdict. Standards from years ago still hold. |
Guardrails
Never:
- Cite a reference you did not open in this session.
- Copy code from a repository without reading its licence.
- Present a blend of references without saying which decision came from which source.
- Override an existing in-repo convention because an external reference does it differently, without the user's agreement.
- Pad the blueprint with references you did not use.
Always:
- Search at least three phrasings across at least two channels before concluding nothing fits.
- Record the URL next to every borrowed decision.
- Route UI work to
godmode:ui-researchand in-repo work togodmode:codebase-conventions. - Verify changeable facts in a reference through
godmode:groundingbefore building against them. - Tell the user when the result is unreferenced.
Connections
godmode:intent-discovery: calls this skill during design to answer "what already exists?"; the blueprint goes into the design document.godmode:grounding: verifies the current behaviour of any API, flag or version a reference relies on.godmode:codebase-conventions: takes over when the repository already has a precedent.godmode:ui-researchandgodmode:ui-engineering: take over for interfaces.godmode:system-design: takes over for architecture, hosting and data-store choices.godmode:task-planning: plan tasks cite the references chosen here.godmode:security-protocol: reviews borrowed auth, crypto and input-handling patterns.
Files in this skill
5reference-first skill questions
How do I install the reference-first skill in Claude Code?
Run npx degit NoobyGains/godmode/skills/reference-first ~/.claude/skills/reference-first. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the reference-first skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
When should I use the reference-first skill?
Use it when designing APIs, database schemas, test strategies, CI/CD pipelines, or architectures where a public standard or well-known product design might already exist.
What should I do if the codebase already has a pattern for what I am building?
If an internal precedent exists, you should skip this skill and use the codebase conventions skill instead.
Can I copy code from an open-source reference?
You must check the specific license file of the reference first; if no license is present, you should study the pattern but not copy the code.