Subagents → Skills

s04 (151 LOC) → s05 (187 LOC)

LOC Delta

+36lines

New Tools

1

load_skill

New Classes

1

SkillLoader

New Functions

0 Subagents

Clean Context Per Subtask

151 LOC

5 tools: bash, read_file, write_file, edit_file, task

planning

Skills

Load on Demand

187 LOC

5 tools: bash, read_file, write_file, edit_file, load_skill

planning

Source Code Diff

s04 (s04_subagent.py) -> s05 (s05_skill_loading.py)

1	1		#!/usr/bin/env python3
2		-	# Harness: context isolation -- protecting the model's clarity of thought.
	2	+	# Harness: on-demand knowledge -- domain expertise, loaded when the model asks.
3	3		"""
4		-	s04_subagent.py - Subagents
	4	+	s05_skill_loading.py - Skills
5	5
6		-	Spawn a child agent with fresh messages=[]. The child works in its own
7		-	context, sharing the filesystem, then returns only a summary to the parent.
	6	+	Two-layer skill injection that avoids bloating the system prompt:
8	7
9		-	Parent agent Subagent
10		-	+------------------+ +------------------+
11		-	\| messages=[...] \| \| messages=[] \| <-- fresh
12		-	\| \| dispatch \| \|
13		-	\| tool: task \| ---------->\| while tool_use: \|
14		-	\| prompt="..." \| \| call tools \|
15		-	\| description="" \| \| append results \|
16		-	\| \| summary \| \|
17		-	\| result = "..." \| <--------- \| return last text \|
18		-	+------------------+ +------------------+
19		-	\|
20		-	Parent context stays clean.
21		-	Subagent context is discarded.
	8	+	Layer 1 (cheap): skill names in system prompt (~100 tokens/skill)
	9	+	Layer 2 (on demand): full skill body in tool_result
22	10
23		-	Key insight: "Process isolation gives context isolation for free."
	11	+	skills/
	12	+	pdf/
	13	+	SKILL.md <-- frontmatter (name, description) + body
	14	+	code-review/
	15	+	SKILL.md
	16	+
	17	+	System prompt:
	18	+	+--------------------------------------+
	19	+	\| You are a coding agent. \|
	20	+	\| Skills available: \|
	21	+	\| - pdf: Process PDF files... \| <-- Layer 1: metadata only
	22	+	\| - code-review: Review code... \|
	23	+	+--------------------------------------+
	24	+
	25	+	When model calls load_skill("pdf"):
	26	+	+--------------------------------------+
	27	+	\| tool_result: \|
	28	+	\| <skill> \|
	29	+	\| Full PDF processing instructions \| <-- Layer 2: full body
	30	+	\| Step 1: ... \|
	31	+	\| Step 2: ... \|
	32	+	\| </skill> \|
	33	+	+--------------------------------------+
	34	+
	35	+	Key insight: "Don't put everything in the system prompt. Load on demand."
24	36		"""
25	37
26	38		import os
	39	+	import re
27	40		import subprocess
28	41		from pathlib import Path
29	42
30	43		from anthropic import Anthropic
31	44		from dotenv import load_dotenv
32	45
33	46		load_dotenv(override=True)
34	47
35	48		if os.getenv("ANTHROPIC_BASE_URL"):
36	49		os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)
37	50
38	51		WORKDIR = Path.cwd()
39	52		client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
40	53		MODEL = os.environ["MODEL_ID"]
	54	+	SKILLS_DIR = WORKDIR / "skills"
41	55
42		-	SYSTEM = f"You are a coding agent at {WORKDIR}. Use the task tool to delegate exploration or subtasks."
43		-	SUBAGENT_SYSTEM = f"You are a coding subagent at {WORKDIR}. Complete the given task, then summarize your findings."
44	56
	57	+	# -- SkillLoader: scan skills/<name>/SKILL.md with YAML frontmatter --
	58	+	class SkillLoader:
	59	+	def __init__(self, skills_dir: Path):
	60	+	self.skills_dir = skills_dir
	61	+	self.skills = {}
	62	+	self._load_all()
45	63
46		-	# -- Tool implementations shared by parent and child --
	64	+	def _load_all(self):
	65	+	if not self.skills_dir.exists():
	66	+	return
	67	+	for f in sorted(self.skills_dir.rglob("SKILL.md")):
	68	+	text = f.read_text()
	69	+	meta, body = self._parse_frontmatter(text)
	70	+	name = meta.get("name", f.parent.name)
	71	+	self.skills[name] = {"meta": meta, "body": body, "path": str(f)}
	72	+
	73	+	def _parse_frontmatter(self, text: str) -> tuple:
	74	+	"""Parse YAML frontmatter between --- delimiters."""
	75	+	match = re.match(r"^---\n(.?)\n---\n(.)", text, re.DOTALL)
	76	+	if not match:
	77	+	return {}, text
	78	+	meta = {}
	79	+	for line in match.group(1).strip().splitlines():
	80	+	if ":" in line:
	81	+	key, val = line.split(":", 1)
	82	+	meta[key.strip()] = val.strip()
	83	+	return meta, match.group(2).strip()
	84	+
	85	+	def get_descriptions(self) -> str:
	86	+	"""Layer 1: short descriptions for the system prompt."""
	87	+	if not self.skills:
	88	+	return "(no skills available)"
	89	+	lines = []
	90	+	for name, skill in self.skills.items():
	91	+	desc = skill["meta"].get("description", "No description")
	92	+	tags = skill["meta"].get("tags", "")
	93	+	line = f" - {name}: {desc}"
	94	+	if tags:
	95	+	line += f" [{tags}]"
	96	+	lines.append(line)
	97	+	return "\n".join(lines)
	98	+
	99	+	def get_content(self, name: str) -> str:
	100	+	"""Layer 2: full skill body returned in tool_result."""
	101	+	skill = self.skills.get(name)
	102	+	if not skill:
	103	+	return f"Error: Unknown skill '{name}'. Available: {', '.join(self.skills.keys())}"
	104	+	return f"<skill name=\"{name}\">\n{skill['body']}\n</skill>"
	105	+
	106	+
	107	+	SKILL_LOADER = SkillLoader(SKILLS_DIR)
	108	+
	109	+	# Layer 1: skill metadata injected into system prompt
	110	+	SYSTEM = f"""You are a coding agent at {WORKDIR}.
	111	+	Use load_skill to access specialized knowledge before tackling unfamiliar topics.
	112	+
	113	+	Skills available:
	114	+	{SKILL_LOADER.get_descriptions()}"""
	115	+
	116	+
	117	+	# -- Tool implementations --
47	118		def safe_path(p: str) -> Path:
48	119		path = (WORKDIR / p).resolve()
49	120		if not path.is_relative_to(WORKDIR):
50	121		raise ValueError(f"Path escapes workspace: {p}")
51	122		return path
52	123
53	124		def run_bash(command: str) -> str:
54	125		dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
55	126		if any(d in command for d in dangerous):
56	127		return "Error: Dangerous command blocked"
57	128		try:
58	129		r = subprocess.run(command, shell=True, cwd=WORKDIR,
59	130		capture_output=True, text=True, timeout=120)
60	131		out = (r.stdout + r.stderr).strip()
61	132		return out[:50000] if out else "(no output)"
62	133		except subprocess.TimeoutExpired:
63	134		return "Error: Timeout (120s)"
64	135
65	136		def run_read(path: str, limit: int = None) -> str:
66	137		try:
67	138		lines = safe_path(path).read_text().splitlines()
68	139		if limit and limit < len(lines):
69	140		lines = lines[:limit] + [f"... ({len(lines) - limit} more)"]
70	141		return "\n".join(lines)[:50000]
71	142		except Exception as e:
72	143		return f"Error: {e}"
73	144
74	145		def run_write(path: str, content: str) -> str:
75	146		try:
76	147		fp = safe_path(path)
77	148		fp.parent.mkdir(parents=True, exist_ok=True)
78	149		fp.write_text(content)
79	150		return f"Wrote {len(content)} bytes"
80	151		except Exception as e:
81	152		return f"Error: {e}"
82	153
83	154		def run_edit(path: str, old_text: str, new_text: str) -> str:
84	155		try:
85	156		fp = safe_path(path)
86	157		content = fp.read_text()
87	158		if old_text not in content:
88	159		return f"Error: Text not found in {path}"
89	160		fp.write_text(content.replace(old_text, new_text, 1))
90	161		return f"Edited {path}"
91	162		except Exception as e:
92	163		return f"Error: {e}"
93	164
94	165
95	166		TOOL_HANDLERS = {
96	167		"bash": lambda **kw: run_bash(kw["command"]),
97	168		"read_file": lambda **kw: run_read(kw["path"], kw.get("limit")),
98	169		"write_file": lambda **kw: run_write(kw["path"], kw["content"]),
99	170		"edit_file": lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
	171	+	"load_skill": lambda **kw: SKILL_LOADER.get_content(kw["name"]),
100	172		}
101	173
102		-	# Child gets all base tools except task (no recursive spawning)
103		-	CHILD_TOOLS = [
	174	+	TOOLS = [
104	175		{"name": "bash", "description": "Run a shell command.",
105	176		"input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
106	177		{"name": "read_file", "description": "Read file contents.",
107	178		"input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["path"]}},
108	179		{"name": "write_file", "description": "Write content to file.",
109	180		"input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
110	181		{"name": "edit_file", "description": "Replace exact text in file.",
111	182		"input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
	183	+	{"name": "load_skill", "description": "Load specialized knowledge by name.",
	184	+	"input_schema": {"type": "object", "properties": {"name": {"type": "string", "description": "Skill name to load"}}, "required": ["name"]}},
112	185		]
113	186
114	187
115		-	# -- Subagent: fresh context, filtered tools, summary-only return --
116		-	def run_subagent(prompt: str) -> str:
117		-	sub_messages = [{"role": "user", "content": prompt}] # fresh context
118		-	for _ in range(30): # safety limit
119		-	response = client.messages.create(
120		-	model=MODEL, system=SUBAGENT_SYSTEM, messages=sub_messages,
121		-	tools=CHILD_TOOLS, max_tokens=8000,
122		-	)
123		-	sub_messages.append({"role": "assistant", "content": response.content})
124		-	if response.stop_reason != "tool_use":
125		-	break
126		-	results = []
127		-	for block in response.content:
128		-	if block.type == "tool_use":
129		-	handler = TOOL_HANDLERS.get(block.name)
130		-	output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
131		-	results.append({"type": "tool_result", "tool_use_id": block.id, "content": str(output)[:50000]})
132		-	sub_messages.append({"role": "user", "content": results})
133		-	# Only the final text returns to the parent -- child context is discarded
134		-	return "".join(b.text for b in response.content if hasattr(b, "text")) or "(no summary)"
135		-
136		-
137		-	# -- Parent tools: base tools + task dispatcher --
138		-	PARENT_TOOLS = CHILD_TOOLS + [
139		-	{"name": "task", "description": "Spawn a subagent with fresh context. It shares the filesystem but not conversation history.",
140		-	"input_schema": {"type": "object", "properties": {"prompt": {"type": "string"}, "description": {"type": "string", "description": "Short description of the task"}}, "required": ["prompt"]}},
141		-	]
142		-
143		-
144	188		def agent_loop(messages: list):
145	189		while True:
146	190		response = client.messages.create(
147	191		model=MODEL, system=SYSTEM, messages=messages,
148		-	tools=PARENT_TOOLS, max_tokens=8000,
	192	+	tools=TOOLS, max_tokens=8000,
149	193		)
150	194		messages.append({"role": "assistant", "content": response.content})
151	195		if response.stop_reason != "tool_use":
152	196		return
153	197		results = []
154	198		for block in response.content:
155	199		if block.type == "tool_use":
156		-	if block.name == "task":
157		-	desc = block.input.get("description", "subtask")
158		-	print(f"> task ({desc}): {block.input['prompt'][:80]}")
159		-	output = run_subagent(block.input["prompt"])
160		-	else:
161		-	handler = TOOL_HANDLERS.get(block.name)
	200	+	handler = TOOL_HANDLERS.get(block.name)
	201	+	try:
162	202		output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
163		-	print(f" {str(output)[:200]}")
	203	+	except Exception as e:
	204	+	output = f"Error: {e}"
	205	+	print(f"> {block.name}: {str(output)[:200]}")
164	206		results.append({"type": "tool_result", "tool_use_id": block.id, "content": str(output)})
165	207		messages.append({"role": "user", "content": results})
166	208
167	209
168	210		if __name__ == "__main__":
169	211		history = []
170	212		while True:
171	213		try:
172		-	query = input("\033[36ms04 >> \033[0m")
	214	+	query = input("\033[36ms05 >> \033[0m")
173	215		except (EOFError, KeyboardInterrupt):
174	216		break
175	217		if query.strip().lower() in ("q", "exit", ""):
176	218		break
177	219		history.append({"role": "user", "content": query})
178	220		agent_loop(history)
179	221		response_content = history[-1]["content"]
180	222		if isinstance(response_content, list):
181	223		for block in response_content:
182	224		if hasattr(block, "text"):
183	225		print(block.text)
184	226		print()