clikit-plugin 0.2.44 → 0.2.46

package/skill/writing-skills/references/skill-anatomy.md

@@ -0,0 +1,210 @@
+# Skill Anatomy Reference
+
+## SKILL.md — Full Specification
+
+### Frontmatter Fields
+
+| Field | Required | Rules |
+|-------|----------|-------|
+| `name` | ✅ | Lowercase letters, numbers, hyphens. No leading/trailing hyphens. Max 64 chars. Must match directory name. |
+| `description` | ✅ | Max 200 chars. Starts with "Use when…" or trigger condition. Ends with what the skill does. |
+
+**Good description:**
+```yaml
+description: Use when creating a new skill. Produces SKILL.md, references/, and mcp.json following Agent Skills standard.
+```
+
+**Bad description:**
+```yaml
+description: Helps with skills.       # too vague — agent won't trigger
+description: A skill for writing skills for AI agents in OpenCode environments that...  # too long
+```
+
+### Body Structure
+
+```markdown
+# Title (no "Skill" suffix needed)
+
+## Workflow         ← what to do, in order
+## Rules            ← decision tables, hard constraints
+## Red Flags        ← patterns to avoid
+## References       ← links to references/ and mcp.json (if any)
+```
+
+### What NOT to Include in Body
+
+- `"You are running the X skill."` — always omitted
+- Long tool parameter tables → move to `references/`
+- Code examples > 15 lines → move to `references/`
+- Content that is only sometimes relevant → move to `references/`
+
+---
+
+## references/ — Specification
+
+### When to Split
+
+| Candidate | Split if... |
+|-----------|-------------|
+| Tool signatures | > 3 tools with params |
+| Code examples | Block > 15 lines |
+| Decision tables | > 10 rows |
+| Step-by-step details | Only needed for specific sub-tasks |
+
+### File Naming
+
+```
+references/
+  api-reference.md      # tool params and examples
+  tool-reference.md     # MCP tool signatures
+  patterns.md           # extended code patterns
+  quick-ref.md          # command cheatsheet
+  decision-matrix.md    # expanded decision tables
+  lsp-ops.md            # LSP tool reference
+```
+
+### Linking from SKILL.md
+
+Every reference file MUST be linked in SKILL.md:
+
+```markdown
+## References
+
+- [API reference](references/api-reference.md) — full tool params and example session
+- [Patterns](references/patterns.md) — extended code examples
+```
+
+The description after `—` tells the agent *what's in the file* so it knows whether to load it.
+
+---
+
+## mcp.json — Specification
+
+### Structure
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "type": "local" | "remote",
+      "command": ["npx", "-y", "package-name"],    // local only
+      "url": "https://...",                          // remote only
+      "description": "one-line purpose",
+      "tools": ["tool_name_1", "tool_name_2"]
+    }
+  }
+}
+```
+
+### Local Server (stdio)
+
+```json
+{
+  "mcpServers": {
+    "my-tool": {
+      "type": "local",
+      "command": ["npx", "-y", "@scope/mcp-server"],
+      "description": "What this server does",
+      "tools": ["tool_a", "tool_b"]
+    }
+  }
+}
+```
+
+### Remote Server (HTTP/SSE)
+
+```json
+{
+  "mcpServers": {
+    "my-remote": {
+      "type": "remote",
+      "url": "https://mcp.example.com/mcp",
+      "description": "What this server does",
+      "tools": ["query", "search"]
+    }
+  }
+}
+```
+
+### With Auth / Env Vars
+
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "type": "remote",
+      "url": "https://api.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer {env:MY_API_KEY}"
+      },
+      "tools": ["fetch_data"]
+    }
+  }
+}
+```
+
+### Rules
+
+- Only list tools the skill **actually uses** — not all tools the server exposes
+- `tools` array is documentation + scope boundary, not a runtime filter
+- Prefer `npx -y` for local servers (no pre-install needed)
+- Use `{env:VAR_NAME}` for secrets — never hardcode API keys
+
+---
+
+## Complete Example: a minimal skill
+
+```
+my-skill/
+├── SKILL.md
+├── mcp.json
+└── references/
+    └── patterns.md
+```
+
+**SKILL.md**
+```markdown
+---
+name: my-skill
+description: Use when doing X. Automates Y and Z via MCP tool.
+---
+
+# My Skill
+
+## Workflow
+
+1. Step one
+2. Call `tool_name(param)` via MCP
+3. Verify result
+
+## Rules
+
+| Situation | Action |
+|-----------|--------|
+| Tool returns error | Log and retry once |
+| Result is empty | Ask user for clarification |
+
+## Red Flags
+
+- Skipping verification step
+- Calling tool without valid input
+
+## References
+
+- [Patterns](references/patterns.md) — extended examples
+- MCP: `my-tool` — see [mcp.json](mcp.json)
+```
+
+**mcp.json**
+```json
+{
+  "mcpServers": {
+    "my-tool": {
+      "type": "local",
+      "command": ["npx", "-y", "my-mcp-package"],
+      "description": "Does Y and Z",
+      "tools": ["tool_name"]
+    }
+  }
+}
+```

package/src/agents/AGENTS.md

@@ -8,22 +8,52 @@ Each `.md` file in this directory defines an agent. The frontmatter sets model,
 |---|---|---|---|
 | **@build** | Primary orchestrator and code executor. Delegates, implements, verifies. | primary | ✅ Yes |
 | **@plan** | Primary strategic planner. Produces specs and plans. Architecture-aware. | primary | ❌ Plans only |
-| **@oracle** | Architecture advisor and complex analysis. Deep local inspection. | subagent | ❌ Read-only |
-| **@explore** | Fast codebase navigator. File search, definitions, git history. | subagent | ❌ Read-only |
-| **@research** | External research. Docs, APIs, GitHub evidence, web sources. | subagent | ❌ Read-only |
+| **@oracle** | High-depth read-only advisor for hard architecture trade-offs, complex debugging, and second-opinion analysis. Expensive specialist — invoke only when `@explore` or `@research` cannot resolve the question. | subagent | ❌ Read-only |
+| **@explore** | Fast local codebase navigator. Symbol definitions, usages, file structure, git history. Read-only. | subagent | ❌ Read-only |
+| **@research** | External evidence specialist. Docs, APIs, GitHub patterns, web sources. Read-only. | subagent | ❌ Read-only |
 | **@review** | Code reviewer and security auditor. Quality gate before merge. | subagent | ❌ Read-only |
 | **@vision** | Design architect and visual implementer. Frontend UI only. | subagent | ✅ Frontend only |
 
+## Specialist Boundaries
+
+The three read-only specialists have distinct scopes — choose the right one:
+
+| Need | Use | Why |
+|------|-----|-----|
+| Find a symbol, file, usage, or recent git change | `@explore` | Fast, local, cheap |
+| Find external docs, library API, GitHub pattern, version info | `@research` | External evidence only |
+| Decide between approaches, assess blast radius, unblock hard debugging | `@oracle` | Deep reasoning, expensive — last resort |
+
+**Never call `@oracle` for something `@explore` or `@research` can answer.**
+
+## Active Roles in Compressed Workflow
+
+Default active roles:
+- `@build`
+- `@plan`
+- `@review`
+- coordinator logic in command/runtime flow
+
+On-demand specialists (invoke only when needed):
+- `@explore` — codebase navigation
+- `@research` — external evidence
+- `@oracle` — hard decisions, expensive
+- `@vision` — frontend/UI work
+
 ## Beads Task Management
 
-All agents use **Beads** (`beads-village_*` MCP tools) as the persistent task source of truth.
+Agents use **Beads** (`beads-village_*` MCP tools) for persistent task tracking.
+
+**Policy:** Beads is used for non-trivial work. Trivial fixes (typo, single-line) skip Beads and execute immediately.
 
 **Core cycle:**
 ```
 beads-village_init → beads-village_add → beads-village_claim → work → beads-village_done
 ```
 
-- **@build**: Creates issues on task start, claims and closes on completion
+Execution happens one **Task Packet** at a time.
+
+- **@build**: Creates issues for non-trivial tasks, claims and closes on completion
 - **@plan**: Creates issues for every plan task after plan approval
 - **Subagents**: Read-only — do not create/modify Beads issues
 
@@ -31,25 +61,25 @@ beads-village_init → beads-village_add → beads-village_claim → work → be
 
 ## Delegation Rules
 
-- Primary agents (@build, @plan) can delegate to subagents
-- Subagents should NOT delegate to other subagents (exception: Oracle → Research for external evidence)
-- Build delegates architecture decisions to Oracle or Plan — does not decide itself
-- Plan consults Oracle for hard trade-offs — Oracle provides analysis, Plan makes the plan
+- Primary agents (`@build`, `@plan`) can delegate to subagents
+- Subagents must NOT delegate to other subagents — **exception:** `@oracle` may consult `@research` for external evidence when local analysis is insufficient
+- `@build` delegates architecture decisions to `@oracle` — does not decide itself
+- `@plan` consults `@oracle` for hard trade-offs — Oracle provides analysis, Plan makes the plan
 - Read the specific agent's `.md` file before modifying its behavior
 
 ## Delegation Flow
 
 ```
 User → @build (orchestrator)
-         ├── @explore (find code)
-         ├── @research (find docs)
-         ├── @oracle (hard decisions)
-         ├── @plan (multi-step planning)
-         ├── @vision (UI work)
-         └── @review (quality gate)
+         ├── @explore   (find code, symbols, usages, git history)
+         ├── @research  (find external docs, APIs, GitHub patterns)
+         ├── @oracle    (hard decisions, blast radius, blocked debugging)
+         ├── @plan      (multi-step planning)
+         ├── @vision    (UI work)
+         └── @review    (quality gate before merge)
 
 User → @plan (planning)
-         ├── @explore (codebase context)
-         ├── @research (external info)
-         └── @oracle (architecture trade-offs)
+         ├── @explore   (codebase context, integration points)
+         ├── @research  (external info, version compatibility)
+         └── @oracle    (architecture trade-offs, risky design decisions)
 ```