xonecas.io
64875
Mc

mini-coder / commit 1b95dc7

chore: remove skills implementation plan file

xonecas2026-03-13 1b95dc7de28e92ced55a899d0581fff5dcc3680b parent 4004169

1 file changed

SKILLS_IMPLEMENTATION_PLAN.md+0−167
@@ -1,167 +0,0 @@
1-# Skills Auto-Discovery + Progressive Disclosure — Implementation Plan
2-
3-## Goal
4-Implement skills behavior aligned with Claude Code/OpenCode expectations:
5-- Auto-discovered skills from supported directories
6-- Progressive disclosure (metadata first, full content on demand)
7-- Agent-accessible skill loading at runtime
8-- Backward-compatible explicit `@skill` usage
9-
10-## Scope
11-In scope:
12-- Skill discovery/indexing
13-- Runtime skill loading mechanism/tooling
14-- Prompt/context integration changes
15-- Validation rules and conflict handling
16-- Tests and docs updates
17-
18-Out of scope (for this iteration):
19-- Remote skill registries / marketplace install flows
20-- Full plugin packaging workflows
21-- New UI beyond existing `/help` and completion paths
22-
23----
24-
25-## Phase 1 — Data model split (metadata index vs full content)
26-
27-### Changes
28-1. Introduce explicit types:
29- - `SkillMeta` (name, description, source, root path, file path)
30- - `SkillRecord` / loader output that can resolve full content lazily
31-2. Refactor `src/cli/skills.ts`:
32- - `loadSkillsIndex(cwd, homeDir?) => Map<string, SkillMeta>`
33- - `loadSkillContent(name, cwd, homeDir?) => { name, content, source } | null`
34-3. Keep existing `loadSkills` temporarily as compatibility shim, then migrate callsites.
35-
36-### Acceptance criteria
37-- Reading skill metadata does not read all `SKILL.md` bodies into memory.
38-- Existing command/help/completion behavior still works.
39-
40----
41-
42-## Phase 2 — Discovery parity (auto-discovery + walk-up)
43-
44-### Changes
45-1. Extend discovery in `src/cli/load-markdown-configs.ts`:
46- - Walk upward from `cwd` to git worktree root for local dirs.
47- - Collect from each level:
48- - `.agents/skills/*/SKILL.md`
49- - `.claude/skills/*/SKILL.md`
50- - Continue loading global dirs:
51- - `~/.agents/skills/*/SKILL.md`
52- - `~/.claude/skills/*/SKILL.md`
53-2. Define deterministic precedence:
54- - Nearest local path wins over farther ancestor
55- - Local wins over global
56- - At same scope/path level, `.agents` wins over `.claude`
57-3. Retain conflict warnings where appropriate.
58-
59-### Acceptance criteria
60-- Skills in parent directories are discoverable.
61-- Precedence is deterministic and covered by tests.
62-
63----
64-
65-## Phase 3 — Progressive disclosure runtime path
66-
67-### Changes
68-1. Add agent-facing skill loader tool (or equivalent internal tool contract) in `src/tools/`:
69- - `listSkills` (metadata only)
70- - `readSkill` / `loadSkill` (full `SKILL.md` for a single skill)
71-2. Expose available skill metadata to the model with minimal token footprint.
72-3. Ensure full skill content is loaded only when:
73- - the model explicitly requests it via tool, or
74- - the user explicitly references `@skill-name`.
75-4. Route `@skill-name` expansion through same resolver used by runtime loader.
76-
77-### Acceptance criteria
78-- Normal turns do not include all skill bodies.
79-- Skill body appears only after explicit load trigger.
80-- `@skill-name` remains functional.
81-
82----
83-
84-## Phase 4 — Validation + compatibility policy
85-
86-### Changes
87-1. Add validation for skill frontmatter:
88- - `name` required
89- - `description` required
90- - name format constraints (lowercase alnum + hyphen, length bounds)
91-2. Validation policy:
92- - Invalid skills are skipped with clear warnings.
93- - Unknown frontmatter fields are tolerated.
94-3. Optional: introduce strict mode flag if needed for incremental rollout.
95-
96-### Acceptance criteria
97-- Invalid skills do not crash loading.
98-- Validation behavior is deterministic and tested.
99-
100----
101-
102-## Phase 5 — UX and docs alignment
103-
104-### Changes
105-1. Update CLI help output to reflect skill auto-discovery and on-demand loading semantics.
106-2. Update docs (`docs/skills.md`) to describe:
107- - discovery locations + walk-up behavior
108- - precedence rules
109- - progressive disclosure
110- - validation constraints
111-3. Keep examples for explicit `@skill` usage and tab completion.
112-
113-### Acceptance criteria
114-- Docs match real runtime behavior.
115-- `/help` and completion output stay accurate.
116-
117----
118-
119-## Testing Plan
120-
121-Add/extend tests in:
122-- `src/cli/skills.test.ts`
123-- `src/cli/input.test.ts` (completion and visibility)
124-- new/updated tests for loader precedence and walk-up behavior
125-- tool tests for `listSkills`/`readSkill`
126-
127-Required scenarios:
128-1. Walk-up discovery from nested cwd.
129-2. Precedence matrix (nearest local > ancestor local > global; `.agents` > `.claude`).
130-3. Metadata-only listing does not require full body reads.
131-4. On-demand content load returns exact raw `SKILL.md`.
132-5. `@skill` expansion remains correct and unified with loader.
133-6. Invalid skill frontmatter handling.
134-
135-Verification command:
136-- `bun run jscpd && bun run knip && bun run typecheck && bun run format && bun run lint && bun run test`
137-
138----
139-
140-## Rollout Strategy
141-
142-1. Land Phases 1–2 behind compatibility-preserving interfaces.
143-2. Land Phase 3 with both explicit (`@skill`) and runtime tool path enabled.
144-3. Enable strict validation policy (Phase 4) once tests and docs are complete.
145-4. Final docs/help cleanup and full QA pass.
146-
147----
148-
149-## Risks and Mitigations
150-
151-- **Risk:** Behavior drift for users relying on permissive frontmatter.
152- - **Mitigation:** Start with warning-based skipping and clear error messages.
153-- **Risk:** Token/context regression from accidental eager loading.
154- - **Mitigation:** Add tests asserting no eager full-body skill injection.
155-- **Risk:** Discovery order confusion in monorepos.
156- - **Mitigation:** Document precedence and cover with explicit tests.
157-
158----
159-
160-## Done Definition
161-
162-Complete when:
163-- Skills are auto-discovered with walk-up + global support.
164-- Model receives metadata catalog, not full bodies by default.
165-- Full skill content is loaded only on demand.
166-- `@skill` works through unified loader path.
167-- Validation, tests, and docs are all aligned and passing.