docs: update skill download

Author: gusye1234

docs/docs.json

@@ -87,11 +87,10 @@
             "group": "Long-term Skill",
             "icon": "brain",
             "pages": [
-              "learn/skill-memory",
+              "learn/quick",
               {
                 "group": "Features",
                 "pages": [
-                  "learn/quick",
                   "learn/custom-memory",
                   "learn/learning-spaces"
                 ]

docs/index.mdx

@@ -18,7 +18,7 @@ Session-scoped storage for messages, files, artifacts, and sandboxes — with co
 Task status, progress tracking, and automatic summaries.
 </Card>
 
-<Card title="Long-term Skill" icon="brain" href="/learn/skill-memory">
+<Card title="Long-term Skill" icon="brain" href="/learn/quick">
 Persistent skills learned across sessions — filesystem-compatible, configurable, and human-readable.
 </Card>
 

docs/integrations/claude-agent.mdx

@@ -244,6 +244,49 @@ const storage = new ClaudeAgentStorage({
 | **ResultMessage** | No | Fallback session-id source. |
 | **StreamEvent** | No | Fallback session-id source. |
 
+## Learn and Download Skills
+
+Acontext can automatically learn [long-term skills](/learn/quick) from the stored messages — extracting patterns, user preferences, and domain knowledge into structured markdown files. You can then download these skills to your local filesystem:
+
+<Tabs>
+<Tab title="Python">
+```python
+# Create a learning space and learn from the session
+space = await acontext_client.learning_spaces.create()
+await acontext_client.learning_spaces.learn(space.id, session_id=storage.session_id)
+# your agent runs as usual...
+# ...
+
+
+# Download learned skills to local
+skills = await acontext_client.learning_spaces.list_skills(space.id)
+for skill in skills:
+    result = await acontext_client.skills.download(skill_id=skill.id, path=f"./skills/{skill.name}")
+    print(f"Downloaded {result.name} to {result.dir_path}")
+    print(f"Files: {result.files}")
+```
+</Tab>
+
+<Tab title="TypeScript">
+```typescript
+// Create a learning space and learn from the session
+const space = await client.learningSpaces.create();
+await client.learningSpaces.learn({ spaceId: space.id, sessionId: storage.sessionId });
+
+// your agent runs as usual...
+// ...
+
+// Download learned skills to local
+const skills = await client.learningSpaces.listSkills(space.id);
+for (const skill of skills) {
+    const result = await client.skills.download(skill.id, { path: `./skills/${skill.name}` });
+    console.log(`Downloaded ${result.name} to ${result.dirPath}`);
+    console.log(`Files: ${result.files}`);
+}
+```
+</Tab>
+</Tabs>
+
 ## Next Steps
 
 <CardGroup cols={2}>
@@ -253,8 +296,8 @@ Anthropic message storage details
 <Card title="Message meta" icon="tag" href="/store/messages/special/message-meta">
 Working with message metadata
 </Card>
-<Card title="Mid-term State" icon="eye" href="/observe/agent_tasks">
-Monitor agent tasks and mid-term state
+<Card title="Long-term Skill" icon="brain" href="/learn/quick">
+Learn skills from agent sessions automatically
 </Card>
 <Card title="Dashboard" icon="chart-simple" href="/observe/dashboard">
 View all interactions

docs/learn/custom-memory.mdx

@@ -1,5 +1,5 @@
 ---
-title: Custom Memory Algorithms
+title: Custom Skills for Long-term Memory
 description: "Define how your agent remembers by writing SKILL.md files"
 ---
 

docs/learn/learning-spaces.mdx

@@ -98,7 +98,7 @@ await client.learningSpaces.delete(space.id);
 ## Next Steps
 
 <CardGroup cols={2}>
-<Card title="What is Long-term Skill?" icon="brain" href="/learn/skill-memory">
+<Card title="Long-term Skill" icon="brain" href="/learn/quick">
   Understand how long-term skill compares to other approaches
 </Card>
 <Card title="Agent Skills" icon="sparkles" href="/store/skill">

docs/learn/quick.mdx

@@ -1,9 +1,22 @@
 ---
-title: Quickstart
-description: "Set up long-term skill for your agent in 3 steps"
+title: "What is Long-term Skill"
+description: "Persistent agent memory stored as structured skill files — filesystem-compatible, configurable, and human-readable"
 ---
 
-Create a learning space, run your agent, and Acontext automatically builds long-term skills from completed tasks.
+Long-term skill is Acontext's approach to persistent agent memory: your agents store memory as **skill files** — plain markdown organized by configurable schemas you control.
+
+```
+Session messages ──► Task extraction 
+                        └► Learner ──► Skill files
+                ┌─────────────────────┘
+                ▼
+                social-contacts/
+                ├── SKILL.md          (your schema)
+                ├── alice-chen.md     (learner-created)
+                └── bob-martinez.md   (learner-created)
+```
+
+## Quickstart
 
 <Steps>
 <Step title="Create a learning space and run a session">
@@ -48,7 +61,7 @@ await client.sessions.storeMessage(session.id, { role: "user", content: "My name
 </CodeGroup>
 
 <Note>
-Call `.learn()` before the agent runs. When tasks complete during the session, Acontext automatically picks them up for learning.
+Call `.learn()` before the agent runs. When [tasks](/observe/agent_tasks) complete during the session, Acontext automatically picks them up for learning. A **task** is a unit of work the agent completes — Acontext extracts them from session messages automatically.
 </Note>
 </Step>
 
@@ -115,16 +128,117 @@ for (const skill of skills) {
 }
 ```
 </CodeGroup>
+</Step>
+
+<Step title="Use learned skills in your agent">
+
+Give your agent access to the learned skills via [Skill Content Tools](/tool/skill_tools). The agent can then look up what it learned in previous sessions:
+
+<CodeGroup>
+```python Python
+from acontext.agent.skill import SKILL_TOOLS
+from openai import OpenAI
+import json
+
+openai_client = OpenAI()
+
+# Get skill IDs from the learning space
+skills = client.learning_spaces.list_skills(space.id)
+skill_ids = [s.id for s in skills]
+
+# Give the agent access to those skills
+ctx = SKILL_TOOLS.format_context(client, skill_ids)
+tools = SKILL_TOOLS.to_openai_tool_schema()
+
+messages = [
+    {"role": "system", "content": f"You have access to skills from past sessions.\n\n{ctx.get_context_prompt()}"},
+    {"role": "user", "content": "Do you know my name?"}
+]
+
+while True:
+    response = openai_client.chat.completions.create(
+        model="gpt-4.1", messages=messages, tools=tools
+    )
+    message = response.choices[0].message
+    messages.append(message)
+
+    if not message.tool_calls:
+        print(f"Assistant: {message.content}")
+        break
+
+    for tc in message.tool_calls:
+        result = SKILL_TOOLS.execute_tool(ctx, tc.function.name, json.loads(tc.function.arguments))
+        messages.append({"role": "tool", "tool_call_id": tc.id, "content": result})
+```
+
+```typescript TypeScript
+import { SKILL_TOOLS } from '@acontext/acontext';
+import OpenAI from 'openai';
+
+const openai = new OpenAI();
+
+// Get skill IDs from the learning space
+const skills = await client.learningSpaces.listSkills(space.id);
+const skillIds = skills.map(s => s.id);
+
+// Give the agent access to those skills
+const ctx = await SKILL_TOOLS.formatContext(client, skillIds);
+const tools = SKILL_TOOLS.toOpenAIToolSchema();
+
+const messages: OpenAI.ChatCompletionMessageParam[] = [
+    { role: "system", content: `You have access to skills from past sessions.\n\n${ctx.getContextPrompt()}` },
+    { role: "user", content: "Do you know my name?" },
+];
+
+while (true) {
+    const response = await openai.chat.completions.create({
+        model: "gpt-4.1",
+        messages,
+        tools,
+    });
+    const message = response.choices[0].message;
+    messages.push(message);
+
+    if (!message.tool_calls) {
+        console.log(`Assistant: ${message.content}`);
+        break;
+    }
+
+    for (const tc of message.tool_calls) {
+        const result = await SKILL_TOOLS.executeTool(ctx, tc.function.name, JSON.parse(tc.function.arguments));
+        messages.push({ role: "tool", tool_call_id: tc.id, content: result });
+    }
+}
+```
+</CodeGroup>
+
 </Step>
 </Steps>
 
+## Why Skill Files?
+
+<Accordion title="Comparison with other memory approaches">
+
+| | Long-term Skill (Acontext) | Vector Store | Knowledge Graph | Plain-text Files |
+|--|--|--|--|--|
+| Storage format | Markdown files | Embeddings | Nodes & edges | Text files |
+| Human-readable | Yes | No | Partially | Partially |
+| Configurable schema | Yes (SKILL.md) | No | Complex upfront | No |
+| Filesystem-native | Yes | No | No | Yes |
+| Version controllable | Yes | No | No | No |
+
+</Accordion>
+
 ## Next Steps
 
-<CardGroup cols={2}>
-<Card title="What is Long-term Skill?" icon="brain" href="/learn/skill-memory">
-  Understand how long-term skill compares to other approaches
+<CardGroup cols={3}>
+<Card title="Custom Skills" icon="sparkles" href="/learn/custom-memory">
+  Define your own memory schemas with SKILL.md
 </Card>
-<Card title="Learning Spaces" icon="sparkles" href="/learn/learning-spaces">
+<Card title="Learning Spaces" icon="brain" href="/learn/learning-spaces">
   Default skills, custom skills, and managing learning spaces
 </Card>
+<Card title="Skill Content Tools" icon="wand-magic-sparkles" href="/tool/skill_tools">
+  Full reference for the skill reading tools
+</Card>
 </CardGroup>

docs/learn/skill-memory.mdx

@@ -211,7 +211,7 @@ Build a compact context for agents in one API call
 Store and manage files and artifacts in Acontext
 </Card>
 
-<Card title="Long-term Skill" icon="brain" href="/learn/skill-memory">
+<Card title="Long-term Skill" icon="brain" href="/learn/quick">
 Understand how long-term skills work
 </Card>
 

docs/quick.mdx

@@ -4,11 +4,15 @@
 
 import json
 from collections.abc import Mapping
+from pathlib import Path
 from typing import Any, BinaryIO, cast
 
+import httpx
+
 from .._utils import build_params
 from ..client_types import AsyncRequesterProtocol
 from ..types.skill import (
+    DownloadSkillResp,
     DownloadSkillToSandboxResp,
     GetSkillFileResp,
     ListSkillsOutput,
@@ -135,6 +139,52 @@ async def get_file(
         data = await self._requester.request("GET", endpoint, params=params)
         return GetSkillFileResp.model_validate(data)
 
+    async def download(
+        self,
+        *,
+        skill_id: str,
+        path: str,
+    ) -> DownloadSkillResp:
+        """Download all files from a skill to a local directory.
+
+        Recursively downloads every file in the skill's file_index,
+        preserving the directory structure.
+
+        Args:
+            skill_id: The UUID of the skill.
+            path: Local directory path to download files into.
+
+        Returns:
+            DownloadSkillResp with skill name, description, resolved dir_path,
+            and list of downloaded file paths.
+        """
+        skill = await self.get(skill_id)
+        dest = Path(path).resolve()
+        dest.mkdir(parents=True, exist_ok=True)
+
+        downloaded: list[str] = []
+        for fi in skill.file_index:
+            resp = await self.get_file(skill_id=skill_id, file_path=fi.path)
+            file_dest = dest / fi.path
+            file_dest.parent.mkdir(parents=True, exist_ok=True)
+
+            if resp.content is not None:
+                file_dest.write_text(resp.content.raw, encoding="utf-8")
+            elif resp.url is not None:
+                async with httpx.AsyncClient() as http:
+                    r = await http.get(resp.url)
+                    r.raise_for_status()
+                    file_dest.write_bytes(r.content)
+
+            downloaded.append(fi.path)
+
+        return DownloadSkillResp(
+            name=skill.name,
+            description=skill.description,
+            dir_path=str(dest),
+            files=downloaded,
+        )
+
     async def download_to_sandbox(
         self,
         *,