From 0c69a2068e214cb2f5adfeaab0c9eccd9921f156 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Tue, 16 Jun 2026 18:51:26 +0800 Subject: [PATCH 1/2] docs(agent): align skill structure with DexSim --- .../skills}/add-atomic-action/SKILL.md | 2 +- .../add-atomic-action/agents/openai.yaml | 4 ++ .../skills}/add-functor/SKILL.md | 0 .agents/skills/add-functor/agents/openai.yaml | 4 ++ .../skills}/add-task-env/SKILL.md | 0 .../skills/add-task-env/agents/openai.yaml | 4 ++ {skills => .agents/skills}/add-test/SKILL.md | 0 .agents/skills/add-test/agents/openai.yaml | 4 ++ {skills => .agents/skills}/benchmark/SKILL.md | 0 .agents/skills/benchmark/agents/openai.yaml | 4 ++ {skills => .agents/skills}/pr/SKILL.md | 7 +--- .agents/skills/pr/agents/openai.yaml | 4 ++ .../skills}/pre-commit-check/SKILL.md | 0 .../pre-commit-check/agents/openai.yaml | 4 ++ .../skills}/project-dev-context/SKILL.md | 5 +++ .../project-dev-context/agents/openai.yaml | 3 ++ .../references/context-system.md | 27 +++++++++++++ .claude/skills/add-atomic-action.md | 20 ++++++++++ .claude/skills/add-functor.md | 20 ++++++++++ .claude/skills/add-task-env.md | 20 ++++++++++ .claude/skills/add-test.md | 20 ++++++++++ .claude/skills/benchmark.md | 20 ++++++++++ .claude/skills/pr.md | 20 ++++++++++ .claude/skills/pre-commit-check.md | 20 ++++++++++ .claude/skills/project-dev-context.md | 35 +++++++++++++++++ .github/copilot/add-atomic-action.md | 8 ++++ .github/copilot/add-functor.md | 7 ++++ .github/copilot/add-task-env.md | 7 ++++ .github/copilot/add-test.md | 7 ++++ .github/copilot/benchmark.md | 7 ++++ .github/copilot/instructions.md | 19 ++++++++++ .github/copilot/pr.md | 8 ++++ .github/copilot/pre-commit-check.md | 7 ++++ .github/copilot/project-dev-context.md | 30 +++++++++++++++ AGENTS.md | 13 ++++++- agent_context/conventions/topic-lifecycle.md | 4 +- docs/source/guides/agent_skills.md | 38 +++++++++++++++++++ docs/source/guides/index.rst | 2 +- 38 files changed, 393 insertions(+), 11 deletions(-) rename {skills => .agents/skills}/add-atomic-action/SKILL.md (98%) create mode 100644 .agents/skills/add-atomic-action/agents/openai.yaml rename {skills => .agents/skills}/add-functor/SKILL.md (100%) create mode 100644 .agents/skills/add-functor/agents/openai.yaml rename {skills => .agents/skills}/add-task-env/SKILL.md (100%) create mode 100644 .agents/skills/add-task-env/agents/openai.yaml rename {skills => .agents/skills}/add-test/SKILL.md (100%) create mode 100644 .agents/skills/add-test/agents/openai.yaml rename {skills => .agents/skills}/benchmark/SKILL.md (100%) create mode 100644 .agents/skills/benchmark/agents/openai.yaml rename {skills => .agents/skills}/pr/SKILL.md (95%) create mode 100644 .agents/skills/pr/agents/openai.yaml rename {skills => .agents/skills}/pre-commit-check/SKILL.md (100%) create mode 100644 .agents/skills/pre-commit-check/agents/openai.yaml rename {skills => .agents/skills}/project-dev-context/SKILL.md (89%) create mode 100644 .agents/skills/project-dev-context/agents/openai.yaml create mode 100644 .agents/skills/project-dev-context/references/context-system.md create mode 100644 .claude/skills/add-atomic-action.md create mode 100644 .claude/skills/add-functor.md create mode 100644 .claude/skills/add-task-env.md create mode 100644 .claude/skills/add-test.md create mode 100644 .claude/skills/benchmark.md create mode 100644 .claude/skills/pr.md create mode 100644 .claude/skills/pre-commit-check.md create mode 100644 .claude/skills/project-dev-context.md create mode 100644 .github/copilot/add-atomic-action.md create mode 100644 .github/copilot/add-functor.md create mode 100644 .github/copilot/add-task-env.md create mode 100644 .github/copilot/add-test.md create mode 100644 .github/copilot/benchmark.md create mode 100644 .github/copilot/instructions.md create mode 100644 .github/copilot/pr.md create mode 100644 .github/copilot/pre-commit-check.md create mode 100644 .github/copilot/project-dev-context.md create mode 100644 docs/source/guides/agent_skills.md diff --git a/skills/add-atomic-action/SKILL.md b/.agents/skills/add-atomic-action/SKILL.md similarity index 98% rename from skills/add-atomic-action/SKILL.md rename to .agents/skills/add-atomic-action/SKILL.md index 9ae574a5..21dee651 100644 --- a/skills/add-atomic-action/SKILL.md +++ b/.agents/skills/add-atomic-action/SKILL.md @@ -1,6 +1,6 @@ --- name: add-atomic-action -description: Use when adding a new observation, event, reward, action, dataset, or randomization functor to an EmbodiChain environment +description: Use when adding a new simulation atomic action or motion primitive to EmbodiChain's AtomicActionEngine. --- # Add Atomic Action diff --git a/.agents/skills/add-atomic-action/agents/openai.yaml b/.agents/skills/add-atomic-action/agents/openai.yaml new file mode 100644 index 00000000..63a1e76d --- /dev/null +++ b/.agents/skills/add-atomic-action/agents/openai.yaml @@ -0,0 +1,4 @@ +name: add-atomic-action +canonical_skill: .agents/skills/add-atomic-action/SKILL.md +project: EmbodiChain + diff --git a/skills/add-functor/SKILL.md b/.agents/skills/add-functor/SKILL.md similarity index 100% rename from skills/add-functor/SKILL.md rename to .agents/skills/add-functor/SKILL.md diff --git a/.agents/skills/add-functor/agents/openai.yaml b/.agents/skills/add-functor/agents/openai.yaml new file mode 100644 index 00000000..0945b413 --- /dev/null +++ b/.agents/skills/add-functor/agents/openai.yaml @@ -0,0 +1,4 @@ +name: add-functor +canonical_skill: .agents/skills/add-functor/SKILL.md +project: EmbodiChain + diff --git a/skills/add-task-env/SKILL.md b/.agents/skills/add-task-env/SKILL.md similarity index 100% rename from skills/add-task-env/SKILL.md rename to .agents/skills/add-task-env/SKILL.md diff --git a/.agents/skills/add-task-env/agents/openai.yaml b/.agents/skills/add-task-env/agents/openai.yaml new file mode 100644 index 00000000..a2b960d5 --- /dev/null +++ b/.agents/skills/add-task-env/agents/openai.yaml @@ -0,0 +1,4 @@ +name: add-task-env +canonical_skill: .agents/skills/add-task-env/SKILL.md +project: EmbodiChain + diff --git a/skills/add-test/SKILL.md b/.agents/skills/add-test/SKILL.md similarity index 100% rename from skills/add-test/SKILL.md rename to .agents/skills/add-test/SKILL.md diff --git a/.agents/skills/add-test/agents/openai.yaml b/.agents/skills/add-test/agents/openai.yaml new file mode 100644 index 00000000..bb75fb19 --- /dev/null +++ b/.agents/skills/add-test/agents/openai.yaml @@ -0,0 +1,4 @@ +name: add-test +canonical_skill: .agents/skills/add-test/SKILL.md +project: EmbodiChain + diff --git a/skills/benchmark/SKILL.md b/.agents/skills/benchmark/SKILL.md similarity index 100% rename from skills/benchmark/SKILL.md rename to .agents/skills/benchmark/SKILL.md diff --git a/.agents/skills/benchmark/agents/openai.yaml b/.agents/skills/benchmark/agents/openai.yaml new file mode 100644 index 00000000..bae4aecc --- /dev/null +++ b/.agents/skills/benchmark/agents/openai.yaml @@ -0,0 +1,4 @@ +name: benchmark +canonical_skill: .agents/skills/benchmark/SKILL.md +project: EmbodiChain + diff --git a/skills/pr/SKILL.md b/.agents/skills/pr/SKILL.md similarity index 95% rename from skills/pr/SKILL.md rename to .agents/skills/pr/SKILL.md index e31b1628..e997f0c9 100644 --- a/skills/pr/SKILL.md +++ b/.agents/skills/pr/SKILL.md @@ -80,9 +80,7 @@ Commit with a clear message following conventional commits format: ```bash git commit -m "type(scope): brief description -Detailed description of the change. - -Co-Authored-By: Claude Opus 4.6 " +Detailed description of the change." ``` ### 7. Push to Remote @@ -168,8 +166,6 @@ Fixes # - [ ] I have made corresponding changes to the documentation - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] Dependencies have been updated, if applicable. - -๐Ÿค– Generated with [Claude Code](https://claude.com/claude-code) ``` ## PR Title Guidelines @@ -199,4 +195,3 @@ Fixes # - Keep PRs small and focused. Large PRs are harder to review and merge. - It's recommended to open an issue and discuss the design before opening a large PR. - The checklist in the PR template should be completed honestly. -- Remember to include the Claude Code attribution at the bottom of the PR body. diff --git a/.agents/skills/pr/agents/openai.yaml b/.agents/skills/pr/agents/openai.yaml new file mode 100644 index 00000000..a870565d --- /dev/null +++ b/.agents/skills/pr/agents/openai.yaml @@ -0,0 +1,4 @@ +name: pr +canonical_skill: .agents/skills/pr/SKILL.md +project: EmbodiChain + diff --git a/skills/pre-commit-check/SKILL.md b/.agents/skills/pre-commit-check/SKILL.md similarity index 100% rename from skills/pre-commit-check/SKILL.md rename to .agents/skills/pre-commit-check/SKILL.md diff --git a/.agents/skills/pre-commit-check/agents/openai.yaml b/.agents/skills/pre-commit-check/agents/openai.yaml new file mode 100644 index 00000000..374d3282 --- /dev/null +++ b/.agents/skills/pre-commit-check/agents/openai.yaml @@ -0,0 +1,4 @@ +name: pre-commit-check +canonical_skill: .agents/skills/pre-commit-check/SKILL.md +project: EmbodiChain + diff --git a/skills/project-dev-context/SKILL.md b/.agents/skills/project-dev-context/SKILL.md similarity index 89% rename from skills/project-dev-context/SKILL.md rename to .agents/skills/project-dev-context/SKILL.md index 59a25e19..9a035029 100644 --- a/skills/project-dev-context/SKILL.md +++ b/.agents/skills/project-dev-context/SKILL.md @@ -21,6 +21,8 @@ Use this skill when: ## Start here - Read `agent_context/MAP.yaml` first +- Read `references/context-system.md` for routing rules +- Read `agents/openai.yaml` for the canonical agent metadata - Read `agent_context/conventions/*.md` when creating or updating context files ## Workflow @@ -58,6 +60,9 @@ If code behavior changes a routed topic, update all relevant pieces in the same - the matching file under `agent_context/topics/...` - `agent_context/MAP.yaml` if topic metadata changed - `AGENTS.md` if routing guidance changed +- `.agents/skills/project-dev-context/references/context-system.md` if routing behavior changed +- `.claude/skills/project-dev-context.md` if Claude adapter wording changed +- `.github/copilot/project-dev-context.md` if Copilot adapter wording changed ## Source-of-truth diff --git a/.agents/skills/project-dev-context/agents/openai.yaml b/.agents/skills/project-dev-context/agents/openai.yaml new file mode 100644 index 00000000..04e0975b --- /dev/null +++ b/.agents/skills/project-dev-context/agents/openai.yaml @@ -0,0 +1,3 @@ +name: project-dev-context +canonical_skill: .agents/skills/project-dev-context/SKILL.md +project: EmbodiChain diff --git a/.agents/skills/project-dev-context/references/context-system.md b/.agents/skills/project-dev-context/references/context-system.md new file mode 100644 index 00000000..5565eacf --- /dev/null +++ b/.agents/skills/project-dev-context/references/context-system.md @@ -0,0 +1,27 @@ +# EmbodiChain Agent Context System + +EmbodiChain keeps agent-facing context in `agent_context/`, indexed by +`agent_context/MAP.yaml`. Agent skills are stored under `.agents/skills/`, and +tool-specific adapters under `.claude/skills/` and `.github/copilot/` should +stay thin. + +## Routing Rules + +1. Read `agent_context/MAP.yaml` first. +2. Resolve the requested topic by exact `id`, then `aliases`, then `keywords`. +3. Load only the matched Markdown files listed in the topic `paths`. +4. Do not read `docs/source/` unless the user explicitly asks for Sphinx + documentation. + +## Update Rules + +When behavior covered by a context topic changes, update the topic Markdown and +`agent_context/MAP.yaml` metadata in the same change. If routing behavior itself +changes, update: + +- `.agents/skills/project-dev-context/SKILL.md` +- `.agents/skills/project-dev-context/references/context-system.md` +- `AGENTS.md` +- `.claude/skills/project-dev-context.md` +- `.github/copilot/project-dev-context.md` + diff --git a/.claude/skills/add-atomic-action.md b/.claude/skills/add-atomic-action.md new file mode 100644 index 00000000..b1812546 --- /dev/null +++ b/.claude/skills/add-atomic-action.md @@ -0,0 +1,20 @@ +--- +name: add-atomic-action +description: Claude adapter for the canonical EmbodiChain add-atomic-action skill. +--- + +# Add Atomic Action - Claude Adapter + +Canonical source: `.agents/skills/add-atomic-action/` + +## When to use + +- adding a new atomic action +- creating a custom motion primitive +- extending `AtomicActionEngine` + +## Start here + +1. Use this adapter when the task asks for a new atomic action. +2. Then follow `.agents/skills/add-atomic-action/SKILL.md`. + diff --git a/.claude/skills/add-functor.md b/.claude/skills/add-functor.md new file mode 100644 index 00000000..3e76ca33 --- /dev/null +++ b/.claude/skills/add-functor.md @@ -0,0 +1,20 @@ +--- +name: add-functor +description: Claude adapter for the canonical EmbodiChain add-functor skill. +--- + +# Add Functor - Claude Adapter + +Canonical source: `.agents/skills/add-functor/` + +## When to use + +- adding observation, reward, event, action, dataset, or randomization functors +- scaffolding manager terms +- extending manager configuration with `FunctorCfg` + +## Start here + +1. Use this adapter when the task asks for a new functor. +2. Then follow `.agents/skills/add-functor/SKILL.md`. + diff --git a/.claude/skills/add-task-env.md b/.claude/skills/add-task-env.md new file mode 100644 index 00000000..358283a3 --- /dev/null +++ b/.claude/skills/add-task-env.md @@ -0,0 +1,20 @@ +--- +name: add-task-env +description: Claude adapter for the canonical EmbodiChain add-task-env skill. +--- + +# Add Task Env - Claude Adapter + +Canonical source: `.agents/skills/add-task-env/` + +## When to use + +- creating a new EmbodiChain task environment +- adding an `EmbodiedEnv` subclass +- scaffolding a new registered Gym task + +## Start here + +1. Use this adapter when the task asks for a new task environment. +2. Then follow `.agents/skills/add-task-env/SKILL.md`. + diff --git a/.claude/skills/add-test.md b/.claude/skills/add-test.md new file mode 100644 index 00000000..ae90ebd9 --- /dev/null +++ b/.claude/skills/add-test.md @@ -0,0 +1,20 @@ +--- +name: add-test +description: Claude adapter for the canonical EmbodiChain add-test skill. +--- + +# Add Test - Claude Adapter + +Canonical source: `.agents/skills/add-test/` + +## When to use + +- writing tests for EmbodiChain modules +- adding coverage for new public APIs +- preparing PR validation + +## Start here + +1. Use this adapter when the task asks for tests. +2. Then follow `.agents/skills/add-test/SKILL.md`. + diff --git a/.claude/skills/benchmark.md b/.claude/skills/benchmark.md new file mode 100644 index 00000000..e190a0be --- /dev/null +++ b/.claude/skills/benchmark.md @@ -0,0 +1,20 @@ +--- +name: benchmark +description: Claude adapter for the canonical EmbodiChain benchmark skill. +--- + +# Benchmark - Claude Adapter + +Canonical source: `.agents/skills/benchmark/` + +## When to use + +- writing benchmark scripts +- modifying benchmark workflow +- comparing solver, simulator, or toolkit performance + +## Start here + +1. Use this adapter when the task is benchmark-specific. +2. Then follow `.agents/skills/benchmark/SKILL.md`. + diff --git a/.claude/skills/pr.md b/.claude/skills/pr.md new file mode 100644 index 00000000..738479ef --- /dev/null +++ b/.claude/skills/pr.md @@ -0,0 +1,20 @@ +--- +name: pr +description: Claude adapter for the canonical EmbodiChain PR skill. +--- + +# PR - Claude Adapter + +Canonical source: `.agents/skills/pr/` + +## When to use + +- drafting or creating an EmbodiChain pull request +- filling the GitHub PR template +- selecting repository labels + +## Start here + +1. Use this adapter when the task asks for PR preparation or creation. +2. Then follow `.agents/skills/pr/SKILL.md`. + diff --git a/.claude/skills/pre-commit-check.md b/.claude/skills/pre-commit-check.md new file mode 100644 index 00000000..53dea4b9 --- /dev/null +++ b/.claude/skills/pre-commit-check.md @@ -0,0 +1,20 @@ +--- +name: pre-commit-check +description: Claude adapter for the canonical EmbodiChain pre-commit-check skill. +--- + +# Pre-Commit Check - Claude Adapter + +Canonical source: `.agents/skills/pre-commit-check/` + +## When to use + +- checking changes before commit or PR +- running local CI-style validation +- verifying headers, formatting, annotations, exports, tests, and docs + +## Start here + +1. Use this adapter when the task asks for pre-commit validation. +2. Then follow `.agents/skills/pre-commit-check/SKILL.md`. + diff --git a/.claude/skills/project-dev-context.md b/.claude/skills/project-dev-context.md new file mode 100644 index 00000000..cbb1487b --- /dev/null +++ b/.claude/skills/project-dev-context.md @@ -0,0 +1,35 @@ +--- +name: project-dev-context +description: Claude adapter for the canonical EmbodiChain project-dev-context skill. +--- + +# Project Dev Context - Claude Adapter + +Canonical source: `.agents/skills/project-dev-context/` + +## When to use + +- reference project development docs +- reference project context +- refresh project context +- update project context +- write project context +- register a new project context topic +- ๅ‚่€ƒ้กน็›ฎๅผ€ๅ‘ๆ–‡ๆกฃ +- ๅ‚่€ƒ้กน็›ฎไธŠไธ‹ๆ–‡ +- ๅˆทๆ–ฐ้กน็›ฎไธŠไธ‹ๆ–‡ +- ๆ›ดๆ–ฐ้กน็›ฎไธŠไธ‹ๆ–‡ +- ๅ†™้กน็›ฎไธŠไธ‹ๆ–‡ + +## Start here + +1. Use this adapter when the request asks to reference, refresh, write, or register project development context. +2. Then follow `.agents/skills/project-dev-context/SKILL.md`. +3. Resolve topics through `agent_context/MAP.yaml`. + +## Update contract + +Keep this file thin. If canonical routing behavior changes, update the +canonical skill first, then only adjust this adapter if Claude needs a +different local entry hint. + diff --git a/.github/copilot/add-atomic-action.md b/.github/copilot/add-atomic-action.md new file mode 100644 index 00000000..a9a9127b --- /dev/null +++ b/.github/copilot/add-atomic-action.md @@ -0,0 +1,8 @@ +# Add Atomic Action for GitHub Copilot + +Canonical source: `.agents/skills/add-atomic-action/` + +Use this adapter when adding a new EmbodiChain atomic action, custom motion +primitive, or `AtomicActionEngine` extension. Then follow +`.agents/skills/add-atomic-action/SKILL.md`. + diff --git a/.github/copilot/add-functor.md b/.github/copilot/add-functor.md new file mode 100644 index 00000000..9021578c --- /dev/null +++ b/.github/copilot/add-functor.md @@ -0,0 +1,7 @@ +# Add Functor for GitHub Copilot + +Canonical source: `.agents/skills/add-functor/` + +Use this adapter when adding observation, reward, event, action, dataset, or +randomization functors. Then follow `.agents/skills/add-functor/SKILL.md`. + diff --git a/.github/copilot/add-task-env.md b/.github/copilot/add-task-env.md new file mode 100644 index 00000000..3cffe98e --- /dev/null +++ b/.github/copilot/add-task-env.md @@ -0,0 +1,7 @@ +# Add Task Env for GitHub Copilot + +Canonical source: `.agents/skills/add-task-env/` + +Use this adapter when creating a new EmbodiChain task environment or registered +`EmbodiedEnv` subclass. Then follow `.agents/skills/add-task-env/SKILL.md`. + diff --git a/.github/copilot/add-test.md b/.github/copilot/add-test.md new file mode 100644 index 00000000..494f0ed8 --- /dev/null +++ b/.github/copilot/add-test.md @@ -0,0 +1,7 @@ +# Add Test for GitHub Copilot + +Canonical source: `.agents/skills/add-test/` + +Use this adapter when writing tests for EmbodiChain modules or adding coverage +for new public APIs. Then follow `.agents/skills/add-test/SKILL.md`. + diff --git a/.github/copilot/benchmark.md b/.github/copilot/benchmark.md new file mode 100644 index 00000000..5bbfa151 --- /dev/null +++ b/.github/copilot/benchmark.md @@ -0,0 +1,7 @@ +# Benchmark for GitHub Copilot + +Canonical source: `.agents/skills/benchmark/` + +Use this adapter when writing or modifying EmbodiChain benchmark scripts. Then +follow `.agents/skills/benchmark/SKILL.md`. + diff --git a/.github/copilot/instructions.md b/.github/copilot/instructions.md new file mode 100644 index 00000000..b76ecd7c --- /dev/null +++ b/.github/copilot/instructions.md @@ -0,0 +1,19 @@ +# EmbodiChain Agent Instructions for GitHub Copilot + +EmbodiChain keeps canonical agent skills under `.agents/skills/`. + +## Project Context Routing + +Use `.github/copilot/project-dev-context.md` as the local entry adapter, then +follow the canonical routing rules in `.agents/skills/project-dev-context/`. + +## Common Skills + +- Add task environments: `.github/copilot/add-task-env.md` +- Add functors: `.github/copilot/add-functor.md` +- Add atomic actions: `.github/copilot/add-atomic-action.md` +- Add tests: `.github/copilot/add-test.md` +- Run pre-commit checks: `.github/copilot/pre-commit-check.md` +- Draft or create pull requests: `.github/copilot/pr.md` +- Write benchmarks: `.github/copilot/benchmark.md` + diff --git a/.github/copilot/pr.md b/.github/copilot/pr.md new file mode 100644 index 00000000..d9e55ac2 --- /dev/null +++ b/.github/copilot/pr.md @@ -0,0 +1,8 @@ +# EmbodiChain PR Creation for GitHub Copilot + +Canonical source: `.agents/skills/pr/` + +Use this adapter when drafting or creating an EmbodiChain pull request, filling +the GitHub PR template, or selecting repository labels. Then follow +`.agents/skills/pr/SKILL.md`. + diff --git a/.github/copilot/pre-commit-check.md b/.github/copilot/pre-commit-check.md new file mode 100644 index 00000000..c5ac9716 --- /dev/null +++ b/.github/copilot/pre-commit-check.md @@ -0,0 +1,7 @@ +# Pre-Commit Check for GitHub Copilot + +Canonical source: `.agents/skills/pre-commit-check/` + +Use this adapter before committing or opening a PR. Then follow +`.agents/skills/pre-commit-check/SKILL.md`. + diff --git a/.github/copilot/project-dev-context.md b/.github/copilot/project-dev-context.md new file mode 100644 index 00000000..ebfa7ef2 --- /dev/null +++ b/.github/copilot/project-dev-context.md @@ -0,0 +1,30 @@ +# Project Dev Context for GitHub Copilot + +Canonical source: `.agents/skills/project-dev-context/` + +## When to use + +- reference project development docs +- reference project context +- refresh project context +- update project context +- write project context +- register a new project context topic +- ๅ‚่€ƒ้กน็›ฎๅผ€ๅ‘ๆ–‡ๆกฃ +- ๅ‚่€ƒ้กน็›ฎไธŠไธ‹ๆ–‡ +- ๅˆทๆ–ฐ้กน็›ฎไธŠไธ‹ๆ–‡ +- ๆ›ดๆ–ฐ้กน็›ฎไธŠไธ‹ๆ–‡ +- ๅ†™้กน็›ฎไธŠไธ‹ๆ–‡ + +## Start here + +1. Use this adapter when the request asks to reference, refresh, write, or register project development context. +2. Then follow `.agents/skills/project-dev-context/SKILL.md`. +3. Resolve topics through `agent_context/MAP.yaml`. + +## Update contract + +Keep this file thin. If canonical routing behavior changes, update the +canonical skill first, then only adjust this adapter if Copilot needs a +different local entry hint. + diff --git a/AGENTS.md b/AGENTS.md index a7c5fac3..0a8115e0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,8 @@ EmbodiChain keeps agent-facing context in a structured topic registry: - `agent_context/` โ€” agent-readable Markdown context, indexed by `agent_context/MAP.yaml` - `docs/source/` โ€” human-facing Sphinx documentation -- `skills/project-dev-context/` โ€” the skill that routes "reference project context" requests +- `.agents/skills/project-dev-context/` โ€” the skill that routes "reference project context" requests +- `.claude/skills/` and `.github/copilot/` โ€” thin tool-specific adapters that point back to `.agents/skills/` When a request says things like: @@ -34,6 +35,10 @@ Available topics: `env-framework`, `manager-functor`, `ik-solvers`, `robot-syste ``` EmbodiChain/ +โ”œโ”€โ”€ .agents/ # Canonical in-repo agent skills +โ”‚ โ””โ”€โ”€ skills/ +โ”œโ”€โ”€ .claude/ # Claude adapters for canonical skills +โ”‚ โ””โ”€โ”€ skills/ โ”œโ”€โ”€ embodichain/ # Main Python package โ”‚ โ”œโ”€โ”€ agents/ # AI agents โ”‚ โ”‚ โ”œโ”€โ”€ datasets/ # Datasets and data loaders for model training @@ -71,7 +76,7 @@ EmbodiChain/ โ”œโ”€โ”€ docs/ # Sphinx documentation source + build โ”‚ โ””โ”€โ”€ source/ # .md doc pages (overview, quick_start, features, resources) โ”œโ”€โ”€ tests/ # Test suite -โ”œโ”€โ”€ .github/ # CI workflows and issue/PR templates +โ”œโ”€โ”€ .github/ # CI workflows, issue/PR templates, Copilot adapters โ”œโ”€โ”€ setup.py # Package setup โ””โ”€โ”€ VERSION # Package version file ``` @@ -252,8 +257,12 @@ Use the `/add-test` skill to scaffold tests with the correct file placement, sty ## Skills Quick Reference +Canonical skill instructions live under `.agents/skills//SKILL.md`. +Tool-specific adapter files should stay thin and point back to the canonical skill. + | Skill | Command | Purpose | |-------|---------|---------| +| Add Atomic Action | `/add-atomic-action` | Scaffold a new simulation atomic action | | Add Task Env | `/add-task-env` | Scaffold a new `EmbodiedEnv` task | | Add Functor | `/add-functor` | Scaffold observation/reward/event/action/dataset/randomization functors | | Add Test | `/add-test` | Scaffold tests following project conventions | diff --git a/agent_context/conventions/topic-lifecycle.md b/agent_context/conventions/topic-lifecycle.md index 16c8dfb9..fa49642f 100644 --- a/agent_context/conventions/topic-lifecycle.md +++ b/agent_context/conventions/topic-lifecycle.md @@ -43,7 +43,9 @@ Explicit refresh requests such as `refresh context` or - `status` 5. If the routing rule or recommended usage changed, update: - `AGENTS.md` - - `skills/project-dev-context/` + - `.agents/skills/project-dev-context/` + - `.claude/skills/project-dev-context.md` + - `.github/copilot/project-dev-context.md` ## Rule diff --git a/docs/source/guides/agent_skills.md b/docs/source/guides/agent_skills.md new file mode 100644 index 00000000..2d4b7cf9 --- /dev/null +++ b/docs/source/guides/agent_skills.md @@ -0,0 +1,38 @@ +# Agent Skills + +EmbodiChain stores canonical in-repo agent skills under `.agents/skills/`. +Each skill directory contains a `SKILL.md` file with the source-of-truth +workflow for that task. + +Tool-specific files are adapters only: + +- `.claude/skills/*.md` points Claude-style skill entry points to the canonical skill. +- `.github/copilot/*.md` points GitHub Copilot guidance to the canonical skill. + +Keep adapters thin. When a workflow changes, update the matching +`.agents/skills//SKILL.md` first, then adjust adapters only when a tool +needs a different local entry hint. + +## Available Skills + +| Skill | Canonical path | Purpose | +| --- | --- | --- | +| `/add-atomic-action` | `.agents/skills/add-atomic-action/SKILL.md` | Scaffold simulation atomic actions. | +| `/add-task-env` | `.agents/skills/add-task-env/SKILL.md` | Scaffold `EmbodiedEnv` task environments. | +| `/add-functor` | `.agents/skills/add-functor/SKILL.md` | Add observation, reward, event, action, dataset, or randomization functors. | +| `/add-test` | `.agents/skills/add-test/SKILL.md` | Write tests following project conventions. | +| `/pre-commit-check` | `.agents/skills/pre-commit-check/SKILL.md` | Run local CI-style checks before committing. | +| `/pr` | `.agents/skills/pr/SKILL.md` | Draft or create pull requests. | +| `/benchmark` | `.agents/skills/benchmark/SKILL.md` | Write benchmark scripts for EmbodiChain modules. | +| Project context routing | `.agents/skills/project-dev-context/SKILL.md` | Resolve project context through `agent_context/MAP.yaml`. | + +## Project Context Routing + +Requests such as `reference project development docs` or `reference project +context` should use the `project-dev-context` skill. The routing flow is: + +1. Read `agent_context/MAP.yaml`. +2. Resolve the topic by exact `id`, then `aliases`, then `keywords`. +3. Load only the matched Markdown files under `agent_context/`. +4. Do not read `docs/source/` unless the user explicitly asks for the Sphinx + documentation. diff --git a/docs/source/guides/index.rst b/docs/source/guides/index.rst index f44ad5a0..12943e4a 100644 --- a/docs/source/guides/index.rst +++ b/docs/source/guides/index.rst @@ -9,6 +9,6 @@ Practical guides for common tasks in EmbodiChain. custom_functors configuration + agent_skills add_robot cli - From d1ed3166fbb9fb30fa294522664e85ed06038b40 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Tue, 16 Jun 2026 18:55:50 +0800 Subject: [PATCH 2/2] fix(agent): use Claude Code skill directories --- .agents/skills/project-dev-context/SKILL.md | 2 +- .../project-dev-context/references/context-system.md | 9 ++++----- .claude/skills/add-atomic-action | 1 - .../{add-atomic-action.md => add-atomic-action/SKILL.md} | 0 .claude/skills/add-functor | 1 - .claude/skills/{add-functor.md => add-functor/SKILL.md} | 0 .claude/skills/add-task-env | 1 - .../skills/{add-task-env.md => add-task-env/SKILL.md} | 0 .claude/skills/add-test | 1 - .claude/skills/{add-test.md => add-test/SKILL.md} | 0 .claude/skills/benchmark | 1 - .claude/skills/{benchmark.md => benchmark/SKILL.md} | 0 .claude/skills/pr | 1 - .claude/skills/{pr.md => pr/SKILL.md} | 0 .claude/skills/pre-commit-check | 1 - .../{pre-commit-check.md => pre-commit-check/SKILL.md} | 0 .../SKILL.md} | 0 agent_context/conventions/topic-lifecycle.md | 2 +- docs/source/guides/agent_skills.md | 2 +- 19 files changed, 7 insertions(+), 15 deletions(-) delete mode 120000 .claude/skills/add-atomic-action rename .claude/skills/{add-atomic-action.md => add-atomic-action/SKILL.md} (100%) delete mode 120000 .claude/skills/add-functor rename .claude/skills/{add-functor.md => add-functor/SKILL.md} (100%) delete mode 120000 .claude/skills/add-task-env rename .claude/skills/{add-task-env.md => add-task-env/SKILL.md} (100%) delete mode 120000 .claude/skills/add-test rename .claude/skills/{add-test.md => add-test/SKILL.md} (100%) delete mode 120000 .claude/skills/benchmark rename .claude/skills/{benchmark.md => benchmark/SKILL.md} (100%) delete mode 120000 .claude/skills/pr rename .claude/skills/{pr.md => pr/SKILL.md} (100%) delete mode 120000 .claude/skills/pre-commit-check rename .claude/skills/{pre-commit-check.md => pre-commit-check/SKILL.md} (100%) rename .claude/skills/{project-dev-context.md => project-dev-context/SKILL.md} (100%) diff --git a/.agents/skills/project-dev-context/SKILL.md b/.agents/skills/project-dev-context/SKILL.md index 9a035029..85423ab0 100644 --- a/.agents/skills/project-dev-context/SKILL.md +++ b/.agents/skills/project-dev-context/SKILL.md @@ -61,7 +61,7 @@ If code behavior changes a routed topic, update all relevant pieces in the same - `agent_context/MAP.yaml` if topic metadata changed - `AGENTS.md` if routing guidance changed - `.agents/skills/project-dev-context/references/context-system.md` if routing behavior changed -- `.claude/skills/project-dev-context.md` if Claude adapter wording changed +- `.claude/skills/project-dev-context/SKILL.md` if Claude adapter wording changed - `.github/copilot/project-dev-context.md` if Copilot adapter wording changed ## Source-of-truth diff --git a/.agents/skills/project-dev-context/references/context-system.md b/.agents/skills/project-dev-context/references/context-system.md index 5565eacf..51113170 100644 --- a/.agents/skills/project-dev-context/references/context-system.md +++ b/.agents/skills/project-dev-context/references/context-system.md @@ -1,9 +1,9 @@ # EmbodiChain Agent Context System EmbodiChain keeps agent-facing context in `agent_context/`, indexed by -`agent_context/MAP.yaml`. Agent skills are stored under `.agents/skills/`, and -tool-specific adapters under `.claude/skills/` and `.github/copilot/` should -stay thin. +`agent_context/MAP.yaml`. Agent skills are stored under `.agents/skills/`. +Claude Code project adapters use `.claude/skills//SKILL.md`, and +GitHub Copilot adapters under `.github/copilot/` should stay thin. ## Routing Rules @@ -22,6 +22,5 @@ changes, update: - `.agents/skills/project-dev-context/SKILL.md` - `.agents/skills/project-dev-context/references/context-system.md` - `AGENTS.md` -- `.claude/skills/project-dev-context.md` +- `.claude/skills/project-dev-context/SKILL.md` - `.github/copilot/project-dev-context.md` - diff --git a/.claude/skills/add-atomic-action b/.claude/skills/add-atomic-action deleted file mode 120000 index ee63a4bc..00000000 --- a/.claude/skills/add-atomic-action +++ /dev/null @@ -1 +0,0 @@ -../../skills/add-atomic-action \ No newline at end of file diff --git a/.claude/skills/add-atomic-action.md b/.claude/skills/add-atomic-action/SKILL.md similarity index 100% rename from .claude/skills/add-atomic-action.md rename to .claude/skills/add-atomic-action/SKILL.md diff --git a/.claude/skills/add-functor b/.claude/skills/add-functor deleted file mode 120000 index 59a2505a..00000000 --- a/.claude/skills/add-functor +++ /dev/null @@ -1 +0,0 @@ -../../skills/add-functor \ No newline at end of file diff --git a/.claude/skills/add-functor.md b/.claude/skills/add-functor/SKILL.md similarity index 100% rename from .claude/skills/add-functor.md rename to .claude/skills/add-functor/SKILL.md diff --git a/.claude/skills/add-task-env b/.claude/skills/add-task-env deleted file mode 120000 index c06093df..00000000 --- a/.claude/skills/add-task-env +++ /dev/null @@ -1 +0,0 @@ -../../skills/add-task-env \ No newline at end of file diff --git a/.claude/skills/add-task-env.md b/.claude/skills/add-task-env/SKILL.md similarity index 100% rename from .claude/skills/add-task-env.md rename to .claude/skills/add-task-env/SKILL.md diff --git a/.claude/skills/add-test b/.claude/skills/add-test deleted file mode 120000 index bc175531..00000000 --- a/.claude/skills/add-test +++ /dev/null @@ -1 +0,0 @@ -../../skills/add-test \ No newline at end of file diff --git a/.claude/skills/add-test.md b/.claude/skills/add-test/SKILL.md similarity index 100% rename from .claude/skills/add-test.md rename to .claude/skills/add-test/SKILL.md diff --git a/.claude/skills/benchmark b/.claude/skills/benchmark deleted file mode 120000 index 2735c494..00000000 --- a/.claude/skills/benchmark +++ /dev/null @@ -1 +0,0 @@ -../../skills/benchmark \ No newline at end of file diff --git a/.claude/skills/benchmark.md b/.claude/skills/benchmark/SKILL.md similarity index 100% rename from .claude/skills/benchmark.md rename to .claude/skills/benchmark/SKILL.md diff --git a/.claude/skills/pr b/.claude/skills/pr deleted file mode 120000 index 5167ba85..00000000 --- a/.claude/skills/pr +++ /dev/null @@ -1 +0,0 @@ -../../skills/pr \ No newline at end of file diff --git a/.claude/skills/pr.md b/.claude/skills/pr/SKILL.md similarity index 100% rename from .claude/skills/pr.md rename to .claude/skills/pr/SKILL.md diff --git a/.claude/skills/pre-commit-check b/.claude/skills/pre-commit-check deleted file mode 120000 index b0cc815c..00000000 --- a/.claude/skills/pre-commit-check +++ /dev/null @@ -1 +0,0 @@ -../../skills/pre-commit-check \ No newline at end of file diff --git a/.claude/skills/pre-commit-check.md b/.claude/skills/pre-commit-check/SKILL.md similarity index 100% rename from .claude/skills/pre-commit-check.md rename to .claude/skills/pre-commit-check/SKILL.md diff --git a/.claude/skills/project-dev-context.md b/.claude/skills/project-dev-context/SKILL.md similarity index 100% rename from .claude/skills/project-dev-context.md rename to .claude/skills/project-dev-context/SKILL.md diff --git a/agent_context/conventions/topic-lifecycle.md b/agent_context/conventions/topic-lifecycle.md index fa49642f..095f8068 100644 --- a/agent_context/conventions/topic-lifecycle.md +++ b/agent_context/conventions/topic-lifecycle.md @@ -44,7 +44,7 @@ Explicit refresh requests such as `refresh context` or 5. If the routing rule or recommended usage changed, update: - `AGENTS.md` - `.agents/skills/project-dev-context/` - - `.claude/skills/project-dev-context.md` + - `.claude/skills/project-dev-context/SKILL.md` - `.github/copilot/project-dev-context.md` ## Rule diff --git a/docs/source/guides/agent_skills.md b/docs/source/guides/agent_skills.md index 2d4b7cf9..8eee3113 100644 --- a/docs/source/guides/agent_skills.md +++ b/docs/source/guides/agent_skills.md @@ -6,7 +6,7 @@ workflow for that task. Tool-specific files are adapters only: -- `.claude/skills/*.md` points Claude-style skill entry points to the canonical skill. +- `.claude/skills//SKILL.md` points Claude Code project skills to the canonical skill. - `.github/copilot/*.md` points GitHub Copilot guidance to the canonical skill. Keep adapters thin. When a workflow changes, update the matching