skills.rest
sndrgrdn
sndrgrdnCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

write-discoverable-code

Write code whose symbols, signatures, and files resolve through plain-text search.

Updated Apr 23, 2026
Search Tags:#documentation#refactoring#software design#code organization#grep#searchability#code naming
One-click install
npx skills add https://github.com/sndrgrdn/skills --skill write-discoverable-code-sndrgrdn
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: write-discoverable-code
Source: https://github.com/sndrgrdn/skills/tree/main/write-discoverable-code
Command: npx skills add https://github.com/sndrgrdn/skills --skill write-discoverable-code-sndrgrdn

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases become hard to navigate when a single grep returns dozens of ambiguous hits or none at all. This Skill guides naming, signatures, comments, and file organization so that one plain-text search lands on the exact definition with enough context to use it. ## Core Features & Use Cases - Searchable Naming: Rules for giving exported symbols, files, and error messages unique, domain-specific names that grep resolves to one definition. - Self-Describing Signatures: Guidance on explicit input/output types and doc comments so a search hit answers what enters, what returns, and which concepts are involved. - Search-Oriented Organization: Practices for one-concept-per-file structure, direct imports, colocated tests, and recording conventions in AGENTS.md. - Use Case: When refactoring a large TypeScript service, apply this Skill to rename generic symbols like handle or process into domain terms, split catch-all utils files, and add literal error prefixes so future searches resolve instantly. ## Quick Start Review this module and rename its symbols, comments, and files so every concept resolves through a single plain-text search.

Frequently Asked Questions about write-discoverable-code

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I make code symbols searchable with grep?▼

Give exported symbols the shortest name that greps uniquely, usually two to four words containing a domain term. Attach generic verbs to their object, keep one canonical spelling per concept, and maintain a single definition site per symbol.

How should I name files for better code navigation?▼

Name files after domain concepts rather than bare roles like config, types, utils, or handlers. Give each question-sized concept its own named file, keep index files as thin re-export entry points, and colocate tests with the behavior they specify.

What makes a good doc comment for searchability?▼

A good doc comment is one line stating the sharpest constraint the signature cannot show, plus the natural-language phrase a reader would search for. Comments that merely restate the name or signature add no value and should be removed.

Should I use barrel files and export star in my modules?▼

Prefer direct imports so the name-to-file mapping stays visible to search. Keep necessary barrels short and explicit, and avoid export star chains because they hide where a symbol is actually defined.

When does search-driven naming not work well?▼

It weakens when receivers or directory paths are treated as disambiguators, since they are absent from a search hit. Context only counts when a rigid project convention makes it visible at the use site, which should be recorded in AGENTS.md.

Related Skills

Explore More Software Engineering Skills→
cin12211cin12211
1

gitnexus-refactoring

Refactor code by renaming symbols and extracting modules with impact analysis.

Community
Advanced
WellApp-aiWellApp-ai
341

code-review

Detect hard-rule violations and quality issues in JavaScript/TypeScript code changes.

Official
Intermediate
LuisaGroupLuisaGroup
1.0k

project_structure

Documents LuisaCompute's layered architecture, module layout, compiler pipeline, and design patterns.

Official
Intermediate
mauromeddamauromedda
13

ast-grep

Search code structure across Go, Python, Bash, and Terraform/HCL.

Community
Advanced