Agent skill
LC FAQ Add
both languages, one pass
The interview FAQs are 49 documents across 12 sub-trees, and the
tree is 100% translated — 902 of 902 sections. So a new English answer does
not leave it "mostly translated": it leaves a hole nothing reports until someone next
runs status, and a Chinese page renders with an English gap in the middle.
/lc-faq-add writes both halves in the same change.
1 scope three candidates. The Kafka file's Scope line owns
consumer-group behaviour; the Streaming one owns
processing semantics. -> kafka, and said so.
2 place under "## 4) Consumer Groups" as "### 4-3) Rebalancing"
appended WITHIN the section — nothing renumbered,
so no anchor moved and no link had to follow
3 write leads with "a rebalance stops the whole group"
then the trigger list
```text timeline ```bash kafka-consumer-groups.sh
4 zh todo -> one key. Translated, both <!--CODE--> markers
in place. max.poll.interval.ms left in English.
5 gate build clean · e2e 80/80 · status faq 903/903
6 assumed the Streaming FAQ gained a "See also" pointing here
A real run: the Scope line picks the file, the section numbering decides where it goes, and the Chinese ships with it.
Why a skill and not a habit
Three ways an FAQ edit goes wrong
None of these are stylistic. Each one leaves the tree measurably worse in a way that is invisible in the diff.
17 of the 49 FAQs open with a Scope line, and it exists to stop two files growing into the same document. "Connection pooling" could plausibly land in db/, backend/ or java/ — where one exists, only the Scope line says which owns it.
Rule: read the Scope lines, not the filenames.
The FAQs are numbered documents — ## 3) then ### 3-2). Inserting in the middle renumbers everything after it, which moves their anchors.
Fix: append within the owning section, or sweep every link in the same change.
The tree is at 902/902. An untranslated new section is the only gap in it, and nothing reports the gap until the next status run.
Rule: the 中文 section ships in the same change.
One pass, no branches
Six steps, in order
Pick one to see what it does and the rule that step exists to enforce.
What lands in the tree
Where a file lives, and what that decides
The directory is the index category, and the H1 and lead paragraph are the card. None of it is configured anywhere.
# OOP FAQ <- the card title comes from the H1
> **Scope** — OOP fundamentals for Java interviews: the four pillars,
> interface vs abstract class, composition over inheritance, SOLID…
^ what this file owns, and what it does not
> **See also**: [`../../cheatsheet/ood_design.md`](…) — class-modeling
> prompts; [`java_design_pattern.md`](…) — the patterns these produce.
---
## 1) The Four Pillars of OOP <- numbering is positional
### 1-1) Encapsulation <- and so are the anchorsThe card description is summarised from the lead paragraph, so both the H1 and the opening are worth writing as something a reader would recognise on the index.
| Directory | Card category |
|---|---|
| doc/faq/java/ | Java |
| doc/faq/backend/ | Backend |
| doc/faq/db/ | Database |
| redis/ kafka/ flink/ sql/ | Redis, Kafka, Flink, SQL |
| doc/faq/spark/ | Spark & Hadoop |
| doc/faq/stream/ | Streaming |
| a file at the root | General |
An unmapped sub-directory becomes its own capitalised category rather than failing
— so a new directory is a decision about the index, and worth naming in the
report. The page name folds the sub-directory in:
doc/faq/java/faq_OOP.md → faqs/java_faq_OOP.html.
i18n/zh/faq/kafka/faq_kafka.md <- mirrors the English path
<!-- 7c1d… --> <- the key `todo` printed
### 4-3) 重新平衡（Rebalancing）
重新平衡會**讓整個 consumer group 停止處理**…
<!--CODE--> <- every marker, in order
<!--CODE-->
The full rules live in /lc-zh-translate —
structure from the English document, English anchor targets, API and command names in
English, no category / tier / kind. This skill
applies them to one section; that one drives a whole backlog.
Arguments are inferred, not interrogated
How to call it
/lc-faq-add kafka rebalancing
/lc-faq-add java virtual threads
add a question about virtual threads to the java FAQ
document this interview question
start a FAQ for gRPC| Left out | What happens |
|---|---|
| Which file | Decided by the Scope lines, not the filenames — and the deciding line is quoted in the report. |
| Which section | The one that owns the concept. Appended within it, so nothing renumbers. |
| The translation | Never left out. It ships in the same change. |
| The question | The one thing it will ask for. |
The guardrails
What it will not do
- Pick the file by topic name.Where a Scope line exists it is what stops two files growing into the same document, and the only thing that can settle an overlap.
- Drop a Scope line when translating.It becomes
> **範圍** — …. The build reads either spelling, so the translated line is the Chinese card description. - Append a loose question to the end.It goes under the section that owns the concept. A file with a tail of unfiled questions is a file nobody can navigate.
- Ship the English alone.The tree is at 902/902. The gap would not be reported until the next
statusrun, and the Chinese page would render with an English hole. - Renumber without sweeping the links.The anchors are positional.
e2e-check.js's dangling-fragment rule is what catches it, but only after the fact. - Leave a fence untagged.
textcounts — for ASCII diagrams and program output. A bare fence is the one that renders wrong. - Start a new FAQ file needlessly.If an existing Scope line already claims the area, a new file is the start of two documents about one topic.
One markdown file, no dependencies
Install
SKILL.md is the whole recipe — nothing to build and no network calls,
so the same source runs on any agent that takes a system prompt. Pick yours.
Drop the skill directory into your user-level skills folder and it loads in every repo:
git clone --depth 1 https://github.com/yennanliu/CS_basics.git /tmp/cs_basics
mkdir -p ~/.claude/skills
cp -r /tmp/cs_basics/.claude/skills/lc-faq-add ~/.claude/skills/
Already installed inside this repo at .claude/skills/lc-faq-add/. The
directory name is the command.
Zip the directory, then Customize → Skills → + → + Create skill → Upload a skill:
cd .claude/skills && zip -r lc-faq-add.zip lc-faq-addLeave the YAML frontmatter intact — description is what Claude matches your request against.
Codex reads AGENTS.md at the repo root automatically. Point it at the skill:
## Filing a Q&A into the FAQs
When asked to add an FAQ entry, document an interview question, or start
a new FAQ file, follow `.claude/skills/lc-faq-add/SKILL.md`.A pointer, not a copy — one source of truth means a fix reaches every agent at once.
Same shape in GEMINI.md, or point at it for a single session:
gemini -p "Follow the recipe in .claude/skills/lc-faq-add/SKILL.md. \
Add a question about Kafka rebalancing."
Paste SKILL.md in as the system prompt. For Cursor or Windsurf, put the
Codex pointer above into a rule file
(.cursor/rules/lc-faq-add.mdc or the editor's equivalent).
curl -sL https://raw.githubusercontent.com/yennanliu/CS_basics/master/.claude/skills/lc-faq-add/SKILL.mdAway from this repo, the transferable parts are the Scope-line rule for choosing a file and the answer-first shape. The translation half is specific to a tree that is already fully translated.
Under the hood
What is inside
- SKILL.md The whole recipe — why the translation is part of the job, the five prime directives, the directory-to-category map, the six steps, the do-not list, and a worked run.
Gated in CI by
check_skills.py,
and what it writes is gated by e2e-check.js — dangling fragments,
broken links and missing descriptions, on every built page.
The rest of the loop
Where it fits
/lc-cheatsheet files what a problem taught you;
/lc-faq-add files what a question taught you — the systems,
language and tooling side that no LeetCode number covers.
/lc-zh-translate owns the rules its second half
applies, and the result lands on the FAQ index in both languages.