language-style-sampling
Skill2 starsChanged 56 days agoMITView on GitHub
Use when working in an unfamiliar language or matching an unfamiliar codebase style. Derives a style guide by sampling.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- artifact-handoffSkill
- catalogSkill
- changelog-qualitySkill
- change-splittingSkill
- code-structureSkill
- comment-qualitySkill
- evidence-disciplineSkill
- factual-integritySkill
- llm-tellsSkill
- plan-iteration-gateSkill
- pre-commit-checkSkill
- project-discoverySkill
- repo-hygieneSkill
- self-review-gateSkill
- skill-authoringSkill
- socratic-specSkill
- systematic-debuggingSkill
- upstream-hygieneSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Before authoring new skill or CONTRIBUTING style section for language/project whose CONTRIBUTING is sparse, or onboarding new repo.
- Distinctive: line 40
Verify by scoring real diffs:
- Distinctive: line 41
Run sampled rules against 2-3 recent diffs, note true positive rate.
- Distinctive: line 48
Not obviously short vague — number vs source.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Language Style Sampling — Derive Guide From Sample
Capability: produce checkable style rules for any project/language by sampling authoritative sources, not LLM prior.
When
Before authoring new skill or CONTRIBUTING style section for language/project whose CONTRIBUTING is sparse, or onboarding new repo.
Method
- Discover authoritative sources ordered:
- Language official style: Effective Go, PEP8 / Google Python Style, Rust API Guidelines, Mozilla JS Guide, clang-format doc, project's own CONTRIBUTING/HACKING.
- Sample 3-5 real files from canon (stdlib, well-maintained cited repo), not random snippets. Paste paths.
- Extract checkable rules — 5 categories:
- Naming: files, functions, predicate bools should_/is_/try_, constants, packages.
- Comment density: WHY not WHAT, where doc lives definition vs header, subtle logic MUST WHY.
- Error handling: return vs exception, wrapping, logging level, sentinel vs typed.
- Function length signal: typical ≤20 logical, hard 40 — what prompts extraction and how to name helper by intent theme.
- Trailing hygiene: public links only, banned class private paths, subject style if conventional commits enforced.
- Encode as checkable rules with example paths/hashes:
- Each cites source file + line or commit hash, not vague widely used.
- Distinguish rule (must) vs signal (exam trigger) vs anti-pattern (delete/rewrite).
- Positive framing: what it provides, not only exclusions.
- Verify by scoring real diffs:
- Run sampled rules against 2-3 recent diffs, note true positive rate. Rework if <50% actionable.
- Dogfood: ./scripts/check-hygiene.sh variant for language-specific lint if project has one.
Example generic
- Sampled src/handlers/ 3 files: avg function 18 lines, 2 helpers extracted by theme auth vs validation.
- Derived: Function length signal most ≤20 hard 40 → extract intent-named helpers with example paths src/handler_a.go:42 as evidence.
- Not obviously short vague — number vs source.
Anti-patterns
| Bad | Why | Better |
| "Use short names" | not checkable | "≤20 chars local, 2-3 words intent helper, predicate should_/is_ per code-structure" |
| Generates guide from memory without sampling | violates factual-integrity R0 never invent | Sample 3-5 files paste paths + cmd output |
| Copies kernel terms verbatim into Python project | wrong authority | Adapt signal not terminology — bisectable becomes CI must pass per commit in stack |
4Q
(a) Wrong? Rules invented without sampling? Examples use private paths? (b) Better way? Existing generic mechanism e.g. golangci-lint config — reuse rather than duplicate? (c) Missing? Rollback if new guide conflicts with upstream CONTRIBUTING, non-interference verification existing CI still green, boundary empty file/generated file, failure notification if guide drifts, who owns decision, what unblocks downstream. (d) Boundaries explicit? Which sources authoritative vs supplemental, which checks org-specific private overlay ~/.config/hygiene/extra-check.sh, scope positive: provides method that produces checkable guide sampled from canon, not list of excluded things.
Verification
ls -R <sample-path>/ | head -n 50; wc -l <sample-files>
./scripts/check-hygiene.sh HEAD 2>&1 | tail -n 20Related
- project-discovery Step0 ordered search upstream CONTRIBUTING
- code-structure helper extraction by theme predicate naming — this method derives those for new language
- comment-quality WHY rules sampled source shows where WHY required
- factual-integrity never invent — sampling as evidence
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.