High-cla/multi-skilled-repository

CLI-First Decision

Core Rule

Before any task starts, decide by priority: trigger first → think → select tool → execute

1. Forced Trigger: Upon receiving ANY request, before starting to think, before calling any tool, before dispatching any sub-agent, you MUST first trigger this skill to make a decision
2. Think First: First understand the essence of the problem—clarify requirements, break down steps, determine scope. Don't rush to grab tools.
3. Built-in Tools Next: Simple read/write/search one step away → directly use Read/Edit/Grep/Glob etc. (zero extra cost)
4. CLI Tools Next: Batch/mechanical operations → use corresponding CLI tools (<1s, refer to matrix below)
5. Skill Assistance: Operations requiring domain expertise → first load the corresponding skill for guidance (refer to available skills list)
6. MCP Tools: Knowledge graph queries, sequential reasoning, web scraping, etc. → use tools provided by MCP server
7. Sub-Agent: Multi-step reasoning, semantic understanding, cross-module analysis → dispatch a sub-agent
8. Self-Reasoning as Fallback: Architecture decisions, design trade-offs, review and validation → reason yourself or consult Oracle

Decision Tree

Receive request (trigger)
  └─ Identify type: fix/implement/research/evaluate/open-ended?
       └─ Reason: first clarify requirements, break down steps, determine scope
       ├─ Simple read/write/modify a file with known content? ───→ Built-in tools (Read/Edit/Write)
       ├─ Mechanical batch operation?
       │   ├─ Batch text replacement? ───────────→ git-sed / sd
       │   ├─ File search? ──────────────────────→ fd-find / glob
       │   ├─ Content search? ───────────────────→ rg-search / grep
       │   ├─ AST structured operation? ─────────→ ast-grep
       │   ├─ JSON/YAML/XML query? ─────────────→ jq-query / yq
       │   └─ Other mechanical operations? ───────→ Check matrix below
       ├─ Corresponding domain skill available? ─→ Load skill for guidance
       ├─ MCP tool available?
       │   ├─ Knowledge graph/code relationship query? ──→ codebase-memory-mcp
       │   ├─ Sequential reasoning/complex analysis? ───→ sequential-thinking
       │   └─ Web content retrieval? ───────────────────→ fetch
       ├─ Need semantic understanding/multi-step reasoning/cross-module? ──→ Sub-agent (task/sub-agent)
       └─ Architecture decision/design trade-off/review? ─────→ Self-reasoning or consult Oracle

Tool Decision Matrix

Level	Scenario	Preferred Tool	Cost
Trigger	Receive request, identify type, clarify intent	Intent Gate Classification	Instant
Reasoning	Task analysis, requirement breakdown, step planning	Think first, then select tool	Instant
Built-in	Simple file read/write/edit	Read / Edit / Write	Instant
Built-in	Basic content search	grep	<1s
Built-in	File pattern matching	glob	<1s
CLI	Batch text replacement (regex)	git-sed	<1s
CLI	File search (by name/type/time)	fd-find	<1s
CLI	Content search + statistics	rg-search (ripgrep)	<1s
CLI	AST code search/replace (25 languages)	ast-grep	<1s
CLI	JSON query/transform	jq-query	<1s
CLI	HTTP API testing	git-curl	<1s
CLI	Fuzzy filtering / narrow down list	fzf-filter	<1s
CLI	Packing/extracting	git-tar	<1s
CLI	Line ending conversion (CRLF/LF)	git-dos2unix	<1s
CLI	Text find-and-replace (simpler syntax)	sd	<1s
CLI	Code statistics (language distribution)	tokei	<1s
CLI	XML/YAML/JSON query	yq / xq	<1s
Skill	Domain-specific operations (quant/frontend/cloud, etc.)	Load corresponding skill for guidance	See skill docs
MCP	Knowledge graph/code relationship query	codebase-memory-mcp	<5s
MCP	Sequential reasoning/multi-step analysis	sequential-thinking	Depends on steps
MCP	Web content retrieval	fetch	<10s
Sub-agent	Multi-step reasoning, semantic understanding, cross-module analysis	task() dispatch sub-agent	Tens of seconds+
Self-reasoning	Architecture decisions, design trade-offs, review and validation	Handle yourself or Oracle	Depends on complexity

Quick Tool Reference

Tool	Typical Command	Use Case
git-sed	git-sed expression:"s/old/new/g" files:["src/**/*.ts"] inPlace:""	Batch regex replace, cross-file editing
fd-find	fd-find pattern:"*.xml" extension:"xml" path:"./Characters"	Find files by name/type/size/time
rg-search	rg-search pattern:"somePattern" glob:"*.xml" context:2	File content search, PCRE2 regex, context lines
ast-grep	ast_grep_search pattern:"if($$$) { $$$ }" lang:"ts" / ast_grep_replace pattern:"console.log($MSG)" rewrite:"logger.info($MSG)" lang:"ts"	AST structure search/replace, understands code syntax tree
jq-query	jq-query filter:".name" file:"data.json"	JSON data query, filter, transform
git-curl	git-curl url:"https://api.example.com" method:"POST" data:'{"key":"val"}'	HTTP API request, supports various methods and custom headers
fzf-filter	fzf-filter pattern:"keyword" input:$lines	Fuzzy filter text lines, narrow down list
git-tar	git-tar action:"create" archive:"out.tar.gz" files:["src/"] compression:"gzip"	Create/extract tar/zip archives
git-dos2unix	git-dos2unix file:"script.sh" mode:"dos2unix"	Convert CRLF ↔ LF line endings
grep	grep pattern:"somePattern" include:"*.xml" output_mode:"files_with_matches"	Basic content search (built-in)
glob	glob pattern:"**/*.xml"	File pattern matching (built-in)
sd	sd find:"old" replace:"new" files:["file.txt"]	Simpler find-replace, default in-place edit, supports regex and literal patterns
tokei	tokei path:"./"	Count code lines, comments, blanks per language. Results in seconds.
yq	yq expression:".Missions.NestMission[]" file:"Missions.xml" xml:true	YAML/XML/JSON structured data query. XML mode can directly query XML files (e.g., list all mission IDs)

When to Use Sub-Agents (Sub-Agent Trigger Guide)

Sub-agents excel where CLI tools and built-in tools fall short:

Scenario	Description	Recommended Method
Semantic Understanding	Determine if code logic is correct, if functionality is complete	task() dispatch sub-agent
Cross-Module Integration	Coordinated changes across multiple modules, interface alignment	task() dispatch sub-agent
Multi-Step Operations	Chain operations requiring search → analysis → modify	task() dispatch sub-agent
Code Generation/Refactoring	Need to understand existing code structure then generate new code	Sub-agent or self-reasoning
Architecture Decisions	Design choices, trade-off analysis	Self-reasoning or Oracle
Verification & Review	Understand code intent, make quality judgments	Self-reasoning or review-work

Note: Even if you ultimately decide to use a sub-agent, you can reference CLI tools inside the task() prompt—the sub-agent can also call these tools internally to complete the task.

Common Mistakes

1. Skipping CLI check and directly calling task(): Habitually dispatch a sub-agent for batch replacements, wasting tens of thousands of tokens. A 30-second agent job could be completed by a <1s CLI command.

2. Manually modifying files after finding them with ripgrep: First use rg to locate, then use CLI batch edit in two steps. Use git-sed one command to complete search+replace.

3. Calling a sub-agent on a single file: To modify known content in a single file, just edit directly—no need to start a full sub-agent session.

4. Using CLI tools to brute-force when a sub-agent is appropriate: CLI tools don't understand semantics. For scenarios involving cross-module analysis, multi-step reasoning, or understanding code intent, a combination of CLI tools is less efficient than a sub-agent. Example: "Find all files calling function X, analyze their parameter patterns, then uniformly refactor"—this is the domain of a sub-agent, not something sed can handle.

5. sd edits in-place by default—always --preview before executing: sd and sed behave differently—sd modifies files directly by default. In practice, sd '<?xml' '<?XML' filelist.xml rewrote all <?xml tags (63 occurrences), only recoverable via git checkout. Safe procedure: First use sd --preview 'find' 'replace' file to see the scope of changes, then execute only after confirming (without --preview).

6. yq XML mode: yq v3 uses --xml, v4 changed to -p xml: yq v4 removed the --xml short parameter, now uses -p xml. Default output format warnings can be suppressed with -o yaml.