feat(skills): Implement assignable skills library and api support

- Added a new API for managing assignable skills, including endpoints to list categories and skills, and retrieve skill content.
- Implemented functionality to copy selected skills from the global library to topic workspaces for moderator assignment.
- Created a guide for managing skills as submodules, including import scripts and documentation for updating skill libraries.
- Updated the main application to include the new skills router and integrate skills into the discussion flow.
- Enhanced README and documentation to reflect the new skills features and usage instructions.

Author: FZR95

.cursor/skills/skills-submodule-guide/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: skills-submodule-guide
+description: Guides how to update skills via submodule, add new skills submodules, and find skills in complex directory structures. Use when the user asks about updating imported skills, adding a new skill library, importing skill repos, or locating skills in assignable_skills.
+---
+
+# Skills Submodule Guide
+
+When working with assignable skills submodules in Agent Topic Lab, follow these procedures.
+
+## 1. Update Existing Skill Library
+
+When upstream (e.g. AI-Research-SKILLs, anthropics/skills) has new commits:
+
+```bash
+# From backend root — script pulls submodule and updates meta
+./scripts/import_skill_repo.sh git@github.com:Orchestra-Research/AI-Research-SKILLs.git ai-research
+./scripts/import_skill_repo.sh git@github.com:anthropics/skills.git anthropics
+```
+
+Restart backend after update.
+
+## 2. Add New Skills Submodule
+
+1. Ensure the repo contains `SKILL.md` files (various structures supported).
+2. Run:
+   ```bash
+   ./scripts/import_skill_repo.sh <repo_url> [source_name]
+   ```
+3. `source_name` is optional; derived from URL if omitted (e.g. `AI-Research-SKILLs` → `ai-research`).
+4. Commit: `_submodules/<source>/`, `assignable_skills/<source>/`, `meta.json`, `.gitmodules`.
+
+**Examples**:
+- `./scripts/import_skill_repo.sh git@github.com:Orchestra-Research/AI-Research-SKILLs.git`
+- `./scripts/import_skill_repo.sh git@github.com:anthropics/skills.git anthropics`
+
+## 3. Find Skills in Complex Directories
+
+### Discovery Rule
+
+The import script recursively finds all `SKILL.md`:
+
+- **Skill dir** = directory containing `SKILL.md`
+- **slug** = skill dir name
+- **category** = parent dir name (or `general` if at repo root)
+
+### Common Structures
+
+| Pattern | Example | category | slug |
+|---------|---------|----------|------|
+| `{category}/{skill}/SKILL.md` | `01-model-architecture/litgpt/SKILL.md` | `01-model-architecture` | `litgpt` |
+| `skills/{skill}/SKILL.md` | `skills/theme-factory/SKILL.md` | `skills` | `theme-factory` |
+| `{skill}/SKILL.md` at root | `20-ml-paper-writing/SKILL.md` | `general` | `20-ml-paper-writing` |
+
+### Search Commands
+
+```bash
+# All SKILL.md (skills stay in _submodules; no symlinks)
+find skills/assignable_skills/_submodules -name "SKILL.md"
+
+# By keyword in meta
+cat skills/assignable_skills/ai-research/meta.json | python3 -c "
+import json,sys
+d=json.load(sys.stdin)
+q='rag'
+for sid,s in d['skills'].items():
+    if q in (s.get('name','')+s.get('description','')).lower():
+        print(sid, s.get('name'))
+"
+```
+
+### Path Mapping
+
+- **Default**: `assignable_skills/{source}/{category}/{slug}.md`
+- **Imported** (submodule): `assignable_skills/_submodules/{source}/{skills_dir}/{category}/{slug}/SKILL.md` — no symlinks; `skills_dir` in meta (e.g. `"."` for ai-research, `"skills"` for anthropics)
+- Skill ID: `{source}:{slug}` (e.g. `ai-research:litgpt`). Default source has no prefix.
+
+## Quick Reference
+
+| Action | Command |
+|--------|---------|
+| Update/add skill library | `./scripts/import_skill_repo.sh <url> [source]` |
+| List sources | `cat skills/assignable_skills/meta.json` |
+| List skills by source | `cat skills/assignable_skills/<source>/meta.json` |
+| Find SKILL.md | `find skills/assignable_skills/_submodules -name "SKILL.md"` |
+
+## Related Docs
+
+- [docs/skills-submodule-guide.md](../../../docs/skills-submodule-guide.md) — Brief overview, points to this skill
+- [docs/import-skill-repo.md](../../../docs/import-skill-repo.md) — Import script quick reference

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "skills/assignable_skills/_submodules/ai-research"]
+	path = skills/assignable_skills/_submodules/ai-research
+	url = https://github.com/Orchestra-Research/AI-Research-SKILLs.git
+[submodule "skills/assignable_skills/_submodules/anthropics"]
+	path = skills/assignable_skills/_submodules/anthropics
+	url = https://github.com/anthropics/skills.git

README.en.md

@@ -200,6 +200,9 @@ Or use `docker compose up --build`.
 | [docs/config.md](docs/config.md) | Env config |
 | [docs/testing.md](docs/testing.md) | Testing guide |
 | [docs/api-reference.md](docs/api-reference.md) | API reference |
+| [docs/assignable-skills-flow.md](docs/assignable-skills-flow.md) | Assignable skills API and copy logic |
+| [docs/skills-submodule-guide.md](docs/skills-submodule-guide.md) | Add/update skill libraries via submodule |
+| [docs/import-skill-repo.md](docs/import-skill-repo.md) | One-click import script for external skill repos |
 | [docs/troubleshooting.md](docs/troubleshooting.md) | Troubleshooting (dependency install, etc.) |
 
 ## Pragmatic Roadmap
@@ -213,7 +216,8 @@ Or use `docker compose up --build`.
 - `GET /health` — Health check
 - **Topics**: `GET/POST /topics`, `GET/PATCH /topics/{topic_id}`, `POST /topics/{topic_id}/close`
 - **Posts**: `GET/POST /topics/{topic_id}/posts`, `POST .../posts/mention`, `GET .../mention/{reply_post_id}`
-- **Discussion**: `POST /topics/{topic_id}/discussion`, `GET .../discussion/status`
+- **Discussion**: `POST /topics/{topic_id}/discussion` (supports `skill_list`), `GET .../discussion/status`
+- **Assignable Skills**: `GET /skills/assignable/categories`, `GET /skills/assignable`, `GET /skills/assignable/{skill_id}/content`
 - **Topic Experts**: `GET/POST /topics/{topic_id}/experts`, `PUT/DELETE .../experts/{expert_name}`, `POST .../experts/generate`
 - **Moderator Modes**: `GET /moderator-modes`, `GET/PUT /topics/{topic_id}/moderator-mode`, `POST .../moderator-mode/generate`
 - **Experts**: `GET /experts`, `GET/PUT /experts/{name}`

README.md

@@ -202,6 +202,9 @@ docker run --rm -p 8000:8000 --env-file .env \
 | [docs/config.md](docs/config.md) | 环境变量配置 |
 | [docs/testing.md](docs/testing.md) | 测试指南 |
 | [docs/api-reference.md](docs/api-reference.md) | API 参考 |
+| [docs/assignable-skills-flow.md](docs/assignable-skills-flow.md) | 可分配技能 API 与复制逻辑 |
+| [docs/skills-submodule-guide.md](docs/skills-submodule-guide.md) | 技能库 submodule 增改指南（含 Cursor skill 入口） |
+| [docs/import-skill-repo.md](docs/import-skill-repo.md) | 一键导入外部技能库脚本 |
 | [docs/troubleshooting.md](docs/troubleshooting.md) | Troubleshooting (dependency install, etc.) |
 
 ## 务实发展方向
@@ -215,7 +218,8 @@ docker run --rm -p 8000:8000 --env-file .env \
 - `GET /health` — 健康检查
 - **Topics**：`GET/POST /topics`，`GET/PATCH /topics/{topic_id}`，`POST /topics/{topic_id}/close`
 - **Posts**：`GET/POST /topics/{topic_id}/posts`，`POST .../posts/mention`，`GET .../mention/{reply_post_id}`
-- **Discussion**：`POST /topics/{topic_id}/discussion`，`GET .../discussion/status`
+- **Discussion**：`POST /topics/{topic_id}/discussion`（支持 `skill_list`），`GET .../discussion/status`
+- **Assignable Skills**：`GET /skills/assignable/categories`，`GET /skills/assignable`，`GET /skills/assignable/{skill_id}/content`
 - **Topic Experts**：`GET/POST /topics/{topic_id}/experts`，`PUT/DELETE .../experts/{expert_name}`，`POST .../experts/generate`
 - **Moderator Modes**：`GET /moderator-modes`，`GET/PUT /topics/{topic_id}/moderator-mode`，`POST .../moderator-mode/generate`
 - **Experts**：`GET /experts`，`GET/PUT /experts/{name}`

app/agent/discussion.py

@@ -18,6 +18,7 @@
 from .moderator_modes import get_moderator_prompt, prepare_moderator_skill
 from .topic_sandbox import exclusive_topic_sandbox
 from .workspace import (
+    copy_skills_to_workspace,
     ensure_topic_workspace,
     init_discussion_history,
     read_discussion_history,
@@ -135,6 +136,7 @@ async def run_discussion_for_topic(
     max_budget_usd: float = 5.0,
     model: str | None = None,
     allowed_tools: list[str] | None = None,
+    skill_list: list[str] | None = None,
 ) -> dict[str, Any]:
     """Run discussion for a topic; return discussion_history, summary, cost, etc."""
     from app.core.config import get_workspace_base
@@ -143,6 +145,12 @@ async def run_discussion_for_topic(
     ws_path = ensure_topic_workspace(base, topic_id)
     init_discussion_history(ws_path, topic_title, topic_body)
 
+    # Copy user-selected skills from global assignable_skills to config/skills/
+    if skill_list:
+        copied = copy_skills_to_workspace(ws_path, skill_list)
+        if copied:
+            logger.info(f"Copied {len(copied)} skills to workspace: {copied}")
+
     config = get_agent_config()
     if model:
         config = {**config, "model": model}

app/agent/moderator_modes.py

@@ -167,13 +167,38 @@ def prepare_moderator_skill(ws_path: Path, topic: str, expert_names: list[str],
             mode_id = "standard"
         skill_content = _build_moderator_prompt_from_preset(mode_id, params)
 
+    # Append skill assignment section when config/skills/ has assignable skills
+    skills_dir = ws_path / "config" / "skills"
+    if skills_dir.exists():
+        skill_files = sorted(skills_dir.glob("*.md"))
+        if skill_files:
+            skill_names = [f.stem for f in skill_files]
+            assignment_section = _build_skill_assignment_section(skill_names)
+            skill_content = skill_content.rstrip() + "\n\n" + assignment_section
+            logger.info(f"Added skill assignment section for {skill_names}")
+
     skill_file = ws_path / "config" / "moderator_skill.md"
     skill_file.parent.mkdir(parents=True, exist_ok=True)
     skill_file.write_text(skill_content, encoding="utf-8")
     logger.info(f"Saved moderator skill to {skill_file} (mode={mode_id}, rounds={num_rounds})")
     return skill_file
 
 
+def _build_skill_assignment_section(skill_names: list[str]) -> str:
+    """Build moderator instructions for assigning skills to experts."""
+    paths_str = "\n".join(f"- config/skills/{s}.md" for s in skill_names)
+    return f"""## Skill Assignment (config/skills/)
+
+以下技能已拷贝到工作区，供你按需分配给专家：
+
+{paths_str}
+
+**使用方式**：
+1. 每轮开始前，用 Read 工具阅读上述技能文件，根据当前讨论阶段与话题选择最相关的技能
+2. 调用专家 Task 时，在指令中附加技能内容，例如：「除你的角色外，请额外遵循以下指导：[粘贴技能内容]。然后阅读 shared/topic.md 并参与讨论。」
+3. 同一专家可分配多个技能，或不同专家分配不同技能；根据话题与专家专长灵活选择"""
+
+
 def get_moderator_prompt(ws_path: Path) -> str:
     """Return the short prompt that instructs the moderator to read its skill file.
 

app/agent/workspace.py

@@ -73,6 +73,107 @@ def init_discussion_history(ws_path: Path, topic_title: str, topic_body: str) ->
     return turns_dir
 
 
+def _parse_skill_id(skill_id: str) -> tuple[str, str]:
+    """Parse skill_id into (source, slug). Supports source-prefixed format: source:slug."""
+    raw = skill_id.removesuffix(".md") if skill_id.endswith(".md") else skill_id
+    if ":" in raw:
+        parts = raw.split(":", 1)
+        return parts[0], parts[1]
+    return "", raw
+
+
+def _resolve_skill_path(base_dir: Path, skill_id: str, skill_info: dict) -> Path | None:
+    """Resolve source file path for a skill. Returns None if not found.
+
+    - default: assignable_skills/default/{category}/{slug}.md
+    - imported (submodule): assignable_skills/_submodules/{source}/{skills_dir}/{category}/{slug}/SKILL.md
+      or {skills_dir}/{slug}/SKILL.md when category is 'general'
+    """
+    _, slug = _parse_skill_id(skill_id)
+    source = skill_info.get("source", "default") or "default"
+    category = skill_info.get("category", "")
+
+    submodules = base_dir / "_submodules" / source
+    if source != "default" and submodules.exists():
+        skills_dir = skill_info.get("_skills_dir", ".") or "."
+        if category and category != "general":
+            path = base_dir / "_submodules" / source / skills_dir / category / slug / "SKILL.md"
+        else:
+            path = base_dir / "_submodules" / source / skills_dir / slug / "SKILL.md"
+        return path if path.exists() else None
+
+    if not category:
+        return base_dir / source / f"{slug}.md"
+    return base_dir / source / category / f"{slug}.md"
+
+
+def _skill_dest_filename(skill_id: str) -> str:
+    """Destination filename in config/skills/. Replaces : with _ to avoid collisions."""
+    _, slug = _parse_skill_id(skill_id)
+    if ":" in (skill_id.removesuffix(".md") if skill_id.endswith(".md") else skill_id):
+        return f"{skill_id.replace(':', '_')}.md"
+    return f"{slug}.md"
+
+
+def copy_skills_to_workspace(ws_path: Path, skill_list: list[str]) -> list[str]:
+    """Copy selected skills from global assignable_skills to topic workspace config/skills/.
+
+    Supports source-prefixed IDs (e.g. awesome:critical_thinking) to avoid collisions
+    when importing from multiple skill libraries.
+
+    Path rule: assignable_skills/{source}/{category}/{slug}.md (all sources)
+
+    Args:
+        ws_path: Topic workspace path (workspace/topics/{topic_id})
+        skill_list: List of skill ids (e.g. ["research_methodology", "awesome:critical_thinking"])
+
+    Returns:
+        List of skill ids that were successfully copied.
+    """
+    if not skill_list:
+        return []
+
+    from app.core.config import get_assignable_skills_dir
+    from app.core.skills_meta import load_aggregated_meta
+
+    base_dir = get_assignable_skills_dir()
+    _, skills_meta = load_aggregated_meta(base_dir)
+    if not skills_meta:
+        logger.warning("Assignable skills meta not found")
+        return []
+
+    # Allow alphanumeric, underscore, hyphen, colon (for source:slug)
+    id_pattern = re.compile(r"^[a-zA-Z0-9_.-]+(:[a-zA-Z0-9_.-]+)*$")
+
+    dest_dir = ws_path / "config" / "skills"
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    copied: list[str] = []
+    for skill_id in skill_list:
+        raw = skill_id.removesuffix(".md") if skill_id.endswith(".md") else skill_id
+        if not id_pattern.match(raw):
+            logger.warning(f"Invalid skill id (skipped): {skill_id}")
+            continue
+
+        skill_info = skills_meta.get(raw, {}) if isinstance(skills_meta.get(raw), dict) else {}
+        if not skill_info:
+            logger.warning(f"Skill not found in meta (skipped): {raw}")
+            continue
+
+        src = _resolve_skill_path(base_dir, raw, skill_info)
+        if not src or not src.exists():
+            logger.warning(f"Skill file not found (skipped): {src}")
+            continue
+
+        dest_name = _skill_dest_filename(raw)
+        dest = dest_dir / dest_name
+        dest.write_text(src.read_text(encoding="utf-8"), encoding="utf-8")
+        copied.append(raw)
+        logger.info(f"Copied skill {raw} to {dest}")
+
+    return copied
+
+
 def _get_expert_label(expert_key: str, ws_path: Path) -> str:
     """Map expert key to display label.
 

app/api/discussion.py

@@ -6,7 +6,13 @@
 from fastapi import APIRouter, HTTPException
 
 from app.agent.discussion import run_discussion_for_topic
-from app.agent.workspace import get_topic_experts, read_discussion_history, read_discussion_summary, validate_topic_id
+from app.agent.workspace import (
+    copy_skills_to_workspace,
+    get_topic_experts,
+    read_discussion_history,
+    read_discussion_summary,
+    validate_topic_id,
+)
 from app.core.config import get_workspace_base
 from app.models.schemas import (
     DEFAULT_ALLOWED_TOOLS,
@@ -37,6 +43,7 @@ async def run_discussion_background(
     max_budget_usd: float,
     model: str | None = None,
     allowed_tools: list[str] | None = None,
+    skill_list: list[str] | None = None,
 ):
     """Background task to run discussion."""
     try:
@@ -52,6 +59,7 @@ async def run_discussion_background(
             max_budget_usd=max_budget_usd,
             model=model,
             allowed_tools=allowed_tools,
+            skill_list=skill_list or [],
         )
         logger.info(f"Discussion completed for topic {topic_id}, result: {result}")
         typed_result = DiscussionResult(**result)
@@ -103,6 +111,7 @@ async def start_discussion_endpoint(topic_id: str, req: StartDiscussionRequest):
         max_budget_usd=req.max_budget_usd,
         model=req.model,
         allowed_tools=tools,
+        skill_list=req.skill_list or [],
     ))
 
     return DiscussionStatusResponse(