skill-flow 1.0.0 → 1.0.1

package/docs/refrences/README.md

@@ -0,0 +1,7 @@
+# References
+
+This directory stores external path and compatibility references that guide
+future `skill-flow` target support.
+
+- [agent-skill-paths.md](/Users/Vint/仓库/03%20Project/skill-flow/docs/refrences/agent-skill-paths.md)
+  Current implementation paths and broader ecosystem path references.

package/docs/refrences/agent-skill-paths.md

@@ -0,0 +1,252 @@
+# Agent Skill Paths Reference
+
+Last updated: 2026-03-22
+
+This file separates two things:
+
+1. Current `skill-flow` implementation behavior
+2. Broader ecosystem path references for future support work
+
+The goal is to keep implementation truth and compatibility research in one
+place without mixing them up.
+
+## Current Skill Flow Support
+
+These are the target roots that the current code can detect and project into.
+Targets with missing directories are hidden from the `config` TUI.
+
+| Target | Default detection roots | Env override | Strategy |
+| --- | --- | --- | --- |
+| Claude Code | `~/.claude/skills` | `SKILL_MANAGER_TARGET_CLAUDE_CODE` | `symlink` |
+| OpenAI Codex | `~/.codex/.agents/skills`, `~/.agents/skills` | `SKILL_MANAGER_TARGET_CODEX` | `symlink` |
+| Cursor | `~/.cursor/skills` | `SKILL_MANAGER_TARGET_CURSOR` | `symlink` |
+| GitHub Copilot | `~/.copilot/skills` | `SKILL_MANAGER_TARGET_GITHUB_COPILOT` | `symlink` |
+| Gemini CLI | `~/.gemini/skills` | `SKILL_MANAGER_TARGET_GEMINI_CLI` | `symlink` |
+| OpenCode | `~/.config/opencode/skills`, `~/.opencode/skills` | `SKILL_MANAGER_TARGET_OPENCODE` | `symlink` |
+| OpenClaw | `~/.openclaw/skills` | `SKILL_MANAGER_TARGET_OPENCLAW` | `copy` |
+| Pi | `~/.pi/agent/skills` | `SKILL_MANAGER_TARGET_PI` | `symlink` |
+| Windsurf | `~/.codeium/windsurf/skills` | `SKILL_MANAGER_TARGET_WINDSURF` | `symlink` |
+| Roo Code | `~/.roo/skills` | `SKILL_MANAGER_TARGET_ROO_CODE` | `symlink` |
+| Cline | `~/.cline/skills` | `SKILL_MANAGER_TARGET_CLINE` | `symlink` |
+| Amp | `~/.config/agents/skills`, `~/.config/amp/skills` | `SKILL_MANAGER_TARGET_AMP` | `symlink` |
+| Kiro | `~/.kiro/skills` | `SKILL_MANAGER_TARGET_KIRO` | `symlink` |
+
+Notes:
+
+- Current v1 implementation projects into target roots only. It does not yet
+  model per-agent project skill roots, compatibility reads, or instruction
+  files such as `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md`.
+- Hidden target behavior is intentional: if no detected root exists, the target
+  should not appear in `config`.
+- Shared compatibility roots such as `~/.agents/skills` and `~/.claude/skills`
+  are not reused across multiple new targets yet. This avoids multi-target
+  projection collisions onto the same physical directory.
+
+## Ecosystem Path References
+
+These references are for future compatibility and target-expansion work. They
+should not be read as "already implemented".
+
+### 1. Claude Code
+
+Skills:
+
+- Personal skills: `~/.claude/skills/<skill-name>/SKILL.md`
+- Project skills: `<repo>/.claude/skills/<skill-name>/SKILL.md`
+
+Instructions and rules:
+
+- User instructions: `~/.claude/CLAUDE.md`
+- Project instructions: `<repo>/CLAUDE.md`
+- Project hidden instructions: `<repo>/.claude/CLAUDE.md`
+- Rules: `<repo>/.claude/rules/*.md`
+
+### 2. OpenAI Codex
+
+Skills:
+
+- Current official user skills: `$HOME/.agents/skills`
+- Project skills: upward scan from current directory for `.agents/skills`
+- System skills: `/etc/codex/skills`
+
+Notes:
+
+- `~/.codex/` is primarily a config directory now, for example
+  `~/.codex/config.toml`.
+- `~/.codex/` should not be treated as the official primary skills root going
+  forward.
+
+### 3. Cursor
+
+Skills:
+
+- Global skills: `~/.cursor/skills/`
+- Project skills: `<repo>/.cursor/skills/`
+
+Compatibility reads:
+
+- `.agents/skills/`
+- `.claude/skills/`
+- `.codex/skills/`
+- Their corresponding home-directory versions
+
+Rules and notes:
+
+- Rules: `<repo>/.cursor/rules/`
+- Cursor skills entered editor and CLI support on `2026-01-22`
+
+### 4. OpenCode
+
+Skills:
+
+- Global skills: `~/.config/opencode/skills/<name>/SKILL.md`
+- Project skills: `<repo>/.opencode/skills/<name>/SKILL.md`
+
+Compatibility reads:
+
+- `.claude/skills`
+- `~/.claude/skills`
+- `.agents/skills`
+- `~/.agents/skills`
+
+Instructions and rules:
+
+- Long-term instructions: `AGENTS.md`
+- Global instructions: `~/.config/opencode/AGENTS.md`
+- Also reads `.cursor/rules/*.md` as one instruction source
+
+### 5. Pi
+
+Skills:
+
+- Global skills: `~/.pi/agent/skills/`
+- Also supports: `~/.agents/skills/`
+- Project skills: `<repo>/.pi/skills/`
+- Also scans current directory and ancestors for `.agents/skills/`
+
+Compatibility reads:
+
+- `~/.claude/skills`
+- `~/.codex/skills`
+
+### 6. GitHub Copilot
+
+Skills:
+
+- Project skills: `.github/skills/`
+- Project compatibility skills: `.claude/skills/`
+- User skills: `~/.copilot/skills/`
+- User compatibility skills: `~/.claude/skills/`
+
+Notes:
+
+- Another official description also lists `.agents/skills/` in the wider
+  priority order.
+- This covers VS Code agent mode and Copilot coding agent usage.
+
+### 7. Gemini CLI
+
+Skills:
+
+- Workspace skills: `<repo>/.gemini/skills/`
+- Workspace alias: `<repo>/.agents/skills/`
+- User skills: `~/.gemini/skills/`
+- User alias: `~/.agents/skills/`
+
+Instructions and extensions:
+
+- User instructions: `~/.gemini/GEMINI.md`
+- Workspace instructions: upward scan for `GEMINI.md`
+- Extensions: `~/.gemini/extensions/`
+
+### 8. Windsurf
+
+Skills:
+
+- Workspace skills: `<repo>/.windsurf/skills/<skill-name>/SKILL.md`
+- User skills: `~/.codeium/windsurf/skills/<skill-name>/SKILL.md`
+- System skills on macOS:
+  `/Library/Application Support/Windsurf/skills/`
+
+Instructions, rules, workflows, memories:
+
+- Long-term instructions: `AGENTS.md`
+- Global rules: `global_rules.md`
+- Project rules: `<repo>/.windsurf/rules/`
+- Project workflows: `<repo>/.windsurf/workflows/`
+- Generated memories: `~/.codeium/windsurf/memories/`
+
+### 9. Roo Code
+
+Skills:
+
+- Project skills: `<repo>/.roo/skills/`
+- Global skills: `~/.roo/skills/`
+
+Rules and commands:
+
+- Project rules: `<repo>/.roo/rules/`
+- Global rules: `~/.roo/rules/`
+- Mode-specific rules: `rules-{modeSlug}`
+- Project commands: `<repo>/.roo/commands/`
+- Global commands: `~/.roo/commands/`
+
+### 10. Cline
+
+Skills:
+
+- Project skills: `<repo>/.cline/skills/`
+- Global skills: `~/.cline/skills/`
+
+Compatibility reads:
+
+- Project compatibility skills: `.clinerules/skills/`
+- Project compatibility skills: `.claude/skills/`
+
+Rules, workflows, local data:
+
+- Project rules: `.clinerules/`
+- Global rules on macOS: `~/Documents/Cline/Rules`
+- Project workflows: `<repo>/.clinerules/workflows/`
+- Global workflows on macOS: `~/Documents/Cline/Workflows`
+- Local data and config: `~/.cline/data/`
+
+### 11. Amp
+
+Skills:
+
+- Project skills: `<repo>/.agents/skills/`
+- User skills: `~/.config/agents/skills/`
+
+Compatibility reads:
+
+- `~/.config/amp/skills/`
+- `.claude/skills/`
+- `~/.claude/skills/`
+
+Instructions:
+
+- Long-term instructions: `AGENTS.md`
+- User `AGENTS` locations:
+  - `~/.config/amp/AGENTS.md`
+  - `~/.config/AGENTS.md`
+
+### 12. Kiro
+
+Skills:
+
+- Global skills: `~/.kiro/skills/`
+- Project skills: `<repo>/.kiro/skills/`
+
+## Suggested Follow-up Optimization Areas
+
+These references imply a few near-term architecture changes:
+
+- Split target support into:
+  - projection targets
+  - project-level compatibility readers
+  - instruction/rules readers
+- Distinguish official roots from compatibility aliases
+- Model user-level, project-level, and system-level roots explicitly
+- Add reference-backed tests for detection precedence and hidden-target behavior
+- Document which roots are used for read, write, or compatibility-only behavior