mirror of
https://github.com/shareAI-lab/analysis_claude_code.git
synced 2026-03-22 02:15:42 +08:00
a9c71002d2
Comprehensive rewrite establishing the harness engineering narrative across the entire repository. README (EN/ZH/JA): added "The Model IS the Agent" manifesto with historical proof (DQN, OpenAI Five, AlphaStar, Tencent Jueyu), "What an Agent Is NOT" critique, harness engineer role definition, "Why Claude Code" as masterclass in harness design, and universe vision. Consistent framing: model = driver, harness = vehicle. docs (36 files, 3 languages): injected one-line "Harness layer" callout after the motto in every session document (s01-s12). agents (13 Python files): added harness framing comment before each module docstring. skills/agent-philosophy.md: full rewrite aligned with harness narrative.
109 lines
3.6 KiB
Markdown
109 lines
3.6 KiB
Markdown
# s05: Skills
|
|
|
|
`s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`
|
|
|
|
> *"Load knowledge when you need it, not upfront"* -- inject via tool_result, not the system prompt.
|
|
>
|
|
> **Harness layer**: On-demand knowledge -- domain expertise, loaded when the model asks.
|
|
|
|
## Problem
|
|
|
|
You want the agent to follow domain-specific workflows: git conventions, testing patterns, code review checklists. Putting everything in the system prompt wastes tokens on unused skills. 10 skills at 2000 tokens each = 20,000 tokens, most of which are irrelevant to any given task.
|
|
|
|
## Solution
|
|
|
|
```
|
|
System prompt (Layer 1 -- always present):
|
|
+--------------------------------------+
|
|
| You are a coding agent. |
|
|
| Skills available: |
|
|
| - git: Git workflow helpers | ~100 tokens/skill
|
|
| - test: Testing best practices |
|
|
+--------------------------------------+
|
|
|
|
When model calls load_skill("git"):
|
|
+--------------------------------------+
|
|
| tool_result (Layer 2 -- on demand): |
|
|
| <skill name="git"> |
|
|
| Full git workflow instructions... | ~2000 tokens
|
|
| Step 1: ... |
|
|
| </skill> |
|
|
+--------------------------------------+
|
|
```
|
|
|
|
Layer 1: skill *names* in system prompt (cheap). Layer 2: full *body* via tool_result (on demand).
|
|
|
|
## How It Works
|
|
|
|
1. Each skill is a directory containing a `SKILL.md` with YAML frontmatter.
|
|
|
|
```
|
|
skills/
|
|
pdf/
|
|
SKILL.md # ---\n name: pdf\n description: Process PDF files\n ---\n ...
|
|
code-review/
|
|
SKILL.md # ---\n name: code-review\n description: Review code\n ---\n ...
|
|
```
|
|
|
|
2. SkillLoader scans for `SKILL.md` files, uses the directory name as the skill identifier.
|
|
|
|
```python
|
|
class SkillLoader:
|
|
def __init__(self, skills_dir: Path):
|
|
self.skills = {}
|
|
for f in sorted(skills_dir.rglob("SKILL.md")):
|
|
text = f.read_text()
|
|
meta, body = self._parse_frontmatter(text)
|
|
name = meta.get("name", f.parent.name)
|
|
self.skills[name] = {"meta": meta, "body": body}
|
|
|
|
def get_descriptions(self) -> str:
|
|
lines = []
|
|
for name, skill in self.skills.items():
|
|
desc = skill["meta"].get("description", "")
|
|
lines.append(f" - {name}: {desc}")
|
|
return "\n".join(lines)
|
|
|
|
def get_content(self, name: str) -> str:
|
|
skill = self.skills.get(name)
|
|
if not skill:
|
|
return f"Error: Unknown skill '{name}'."
|
|
return f"<skill name=\"{name}\">\n{skill['body']}\n</skill>"
|
|
```
|
|
|
|
3. Layer 1 goes into the system prompt. Layer 2 is just another tool handler.
|
|
|
|
```python
|
|
SYSTEM = f"""You are a coding agent at {WORKDIR}.
|
|
Skills available:
|
|
{SKILL_LOADER.get_descriptions()}"""
|
|
|
|
TOOL_HANDLERS = {
|
|
# ...base tools...
|
|
"load_skill": lambda **kw: SKILL_LOADER.get_content(kw["name"]),
|
|
}
|
|
```
|
|
|
|
The model learns what skills exist (cheap) and loads them when relevant (expensive).
|
|
|
|
## What Changed From s04
|
|
|
|
| Component | Before (s04) | After (s05) |
|
|
|----------------|------------------|----------------------------|
|
|
| Tools | 5 (base + task) | 5 (base + load_skill) |
|
|
| System prompt | Static string | + skill descriptions |
|
|
| Knowledge | None | skills/\*/SKILL.md files |
|
|
| Injection | None | Two-layer (system + result)|
|
|
|
|
## Try It
|
|
|
|
```sh
|
|
cd learn-claude-code
|
|
python agents/s05_skill_loading.py
|
|
```
|
|
|
|
1. `What skills are available?`
|
|
2. `Load the agent-builder skill and follow its instructions`
|
|
3. `I need to do a code review -- load the relevant skill first`
|
|
4. `Build an MCP server using the mcp-builder skill`
|