cs-note
cs-learn / cs-trick / cs-decide generate independent markdown files, which are accessed via retrieval; AGENTS.md / CLAUDE.md are persistent contexts that are automatically loaded in every session. These two types of information have different destinations — this skill is dedicated to managing the latter: appending short, stable, and "must-know-every-time" fragments to the resident files.
It does not replace knowledge-precipitation skills, but fills a previously missing entry point.
What Goes into cs-note, What Doesn't
Criteria: Length + Frequency + Stability — all three must be met to go into cs-note.
| Item | Goes to cs-note | Goes elsewhere |
|---|
| Length | Can be explained in 1-2 lines | Exceeds half screen / requires background context → cs-learn |
| Frequency | Needed in almost every session | Only relevant to specific task types → cs-trick |
| Stability | Long-term hard constraints of the project | Temporary bypass / short-term workaround → write to issue spec or feature spec |
| Decision Status | Already a fact (no decision records needed) | Need to record selection reasons / rejected solutions → cs-decide |
✅ Typical entries that should be added:
- "Must run to generate schema before compilation"
- "Must start before launching local services"
- "The project uses yarn berry, do not use "
- "Test command is , not "
- "src/legacy/ is historical code, consult before modifying"
- " is stored in 1Password, do not copy from .env.example"
❌ Typical entries that should NOT be added (will bloat AGENTS.md):
- Fix for a specific bug (→ cs-learn pitfall)
- Usage of a certain library (→ cs-trick library)
- Architecture description (→ codestable/architecture/)
- Short-term status like "Working on X this week" (→ do not record, will become outdated)
- Content requiring more than 3 lines to explain (→ cs-learn knowledge)
If unsure, ask the user: "Should the AI know this in every future session?" If the answer is "Not necessarily" → it doesn't belong to cs-note.
Target Files
Follow the actual files in the project, do not create new files proactively:
- If exists in the project root → write here
- If doesn't exist but does → write here
- If both exist → default to (more universal), unless specified by the user
- If neither exists → prompt the user: "The project doesn't have AGENTS.md / CLAUDE.md yet. Would you like me to create an AGENTS.md first?" Only create if the user agrees
Do not write under codestable/ — the entire value of this skill lies in leveraging "automatic loading"; writing under codestable/ would lose its purpose.
Fixed Section Structure
To prevent the file from becoming bloated, the sections are fixed (do not create new sections outside the list):
markdown
## Project Fragment Knowledge
<!-- cs-note managed: maintained by cs-note, append new entries to the sections below -->
### Compilation & Building
- ...
### Running & Local Service Setup
- ...
### Testing
- ...
### Command & Script Pitfalls
- ...
### Path & Directory Conventions
- ...
### Environment Variables & Credentials
- ...
### Others
- ...
Rules:
- Append new entries to the end of the corresponding section, one entry per line (max two lines)
- If no suitable section exists → put in "Others". If "Others" has more than 5 entries, stop and discuss with the user whether to add a new fixed section (do not add sections silently)
- Keep empty sections intact, do not delete them (so the AI recognizes the section is meaningful)
- The comment line is the identification anchor for this skill — if not found, insert the entire structure at the end of the file
- Soft upper limit for total length ~150 lines — if exceeded, prompt the user: "There are too many fragment knowledge entries. Would you like to move some to cs-learn / cs-decide?"
Process
1. Determine Eligibility
Check against the "Criteria" table above. If any criterion is not met → guide to the corresponding other skill and end this round.
2. Select Target File
Follow the rules in the "Target Files" section, handle cases with multiple files or no files accordingly.
3. Locate Position: Section Classification + Duplication Check
- Read the target file and locate the anchor
- If the anchor is not found → append the entire "Project Fragment Knowledge" skeleton at the end of the file
- Search for keywords within the "Project Fragment Knowledge" section to check for duplicates — if a similar entry already exists, do not add a new one, ask the user: "Would you like to update the existing entry or add this as a separate one?"
- Select the appropriate section, or use "Others" if no suitable section exists
4. Add an Entry
Format for each entry:
- {one-sentence fact + one-sentence reason if necessary}
Examples:
- Must run `pnpm run gen` before compilation, otherwise schema types will not match
- Do not use `npm install`, the project's lock file is for yarn berry
- src/legacy/ is old code from before 2023, confirm with @ldz before modifying
Exit after the user reviews and confirms. Do not proactively add multiple entries at once — one entry per time, to avoid including unconfirmed content.
5. Trigger Soft Upper Limit Check
After adding, check the total number of lines in the "Project Fragment Knowledge" section:
- ≥150 lines → prompt the user to move some entries to cs-learn / cs-decide
- "Others" section has ≥5 entries → prompt the user to discuss adding a new fixed section
This is only a prompt, do not make decisions for the user.
Proactive Recommendation Timing
Do not ask every time. Only recommend when two clear signals are triggered:
- The user mentions a fact that clearly belongs to fragment knowledge — "Oh right, this project requires X to do Y", "We use Z instead of W here" → recommend: "Would you like to this? The AI will see it every time in future sessions."
- The AI just encountered a project-specific setting that can be explained in one sentence (compilation failure / incorrect command / wrong path) → after fixing, recommend: "Is this a universal pitfall for the project? If yes, it so the AI knows it directly in the next session."
If the user says "No thanks", skip immediately and do not repeat the recommendation.
Common Pitfalls
- Putting detailed background / multi-step guides into AGENTS.md — content longer than two lines should go to cs-learn
- Writing under codestable/ — loses the value of "automatic loading", this skill is designed to write to root directory resident files
- Adding new sections silently — sections are fixed, discuss with the user before adding new ones
- Adding multiple entries together when seeing one — add one entry at a time
- Writing "short-term status" (working on X this week / sprint goals) — will become outdated and misleading over time
- Appending without checking for duplicates — if the same fact is recorded 3 times, the AI will get confused about which is accurate