claudient 0.1.0

package/scripts/cli.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+
+const REPO_ROOT = path.resolve(__dirname, '..')
+const CLAUDE_DIR = path.join(os.homedir(), '.claude')
+const SKILLS_DEST = path.join(CLAUDE_DIR, 'skills')
+
+const VALID_CATEGORIES = [
+  'backend',
+  'devops-infra',
+  'data-ml',
+  'database',
+  'finance-payments',
+  'ai-engineering',
+]
+
+function usage() {
+  console.log(`
+claudient — Claude Code knowledge system installer
+
+Usage:
+  npx claudient add <category>   Add skills from a specific category
+  npx claudient add all          Add all skills
+  npx claudient list             List available categories and skills
+  npx claudient help             Show this help
+
+Categories:
+  ${VALID_CATEGORIES.join('\n  ')}
+
+Examples:
+  npx claudient add backend
+  npx claudient add ai-engineering
+  npx claudient add all
+`)
+}
+
+function checkClaudeInstalled() {
+  if (!fs.existsSync(CLAUDE_DIR)) {
+    console.error(`
+Error: ~/.claude directory not found.
+
+Claude Code must be installed first. Install it from:
+  https://claude.ai/code
+
+Or install the CLI:
+  npm install -g @anthropic-ai/claude-code
+`)
+    process.exit(1)
+  }
+}
+
+function copyDir(src, dest, prefix = '') {
+  if (!fs.existsSync(src)) return 0
+  fs.mkdirSync(dest, { recursive: true })
+
+  let count = 0
+  const entries = fs.readdirSync(src, { withFileTypes: true })
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name)
+    const destPath = path.join(dest, entry.name)
+    if (entry.isDirectory()) {
+      count += copyDir(srcPath, destPath, prefix + entry.name + '/')
+    } else if (entry.name.endsWith('.md')) {
+      fs.copyFileSync(srcPath, destPath)
+      console.log(`  + ${prefix}${entry.name}`)
+      count++
+    }
+  }
+  return count
+}
+
+function addCategory(category) {
+  checkClaudeInstalled()
+
+  if (category === 'all') {
+    let total = 0
+    console.log(`Installing all Claudient skills to ${SKILLS_DEST}...\n`)
+    for (const cat of VALID_CATEGORIES) {
+      const src = path.join(REPO_ROOT, 'skills', cat)
+      const dest = path.join(SKILLS_DEST, cat)
+      const count = copyDir(src, dest, cat + '/')
+      if (count > 0) console.log(`  ✓ ${cat} (${count} files)`)
+    }
+    console.log(`\nDone. Skills installed to: ${SKILLS_DEST}`)
+    console.log('Restart Claude Code to activate the new skills.')
+    return
+  }
+
+  if (!VALID_CATEGORIES.includes(category)) {
+    console.error(`Unknown category: "${category}"`)
+    console.error(`Valid categories: ${VALID_CATEGORIES.join(', ')}`)
+    process.exit(1)
+  }
+
+  const src = path.join(REPO_ROOT, 'skills', category)
+  if (!fs.existsSync(src)) {
+    console.error(`Category directory not found: ${src}`)
+    process.exit(1)
+  }
+
+  const dest = path.join(SKILLS_DEST, category)
+  console.log(`Installing ${category} skills to ${dest}...\n`)
+  const count = copyDir(src, dest, category + '/')
+  console.log(`\nInstalled ${count} skill file(s).`)
+  console.log('Restart Claude Code to activate the new skills.')
+}
+
+function listSkills() {
+  console.log('Available Claudient skill categories:\n')
+  for (const cat of VALID_CATEGORIES) {
+    const catDir = path.join(REPO_ROOT, 'skills', cat)
+    if (!fs.existsSync(catDir)) continue
+    const files = getSkillFiles(catDir, '')
+    console.log(`${cat}/ (${files.length} skills)`)
+    for (const f of files) {
+      console.log(`  ${f}`)
+    }
+  }
+}
+
+function getSkillFiles(dir, prefix) {
+  const results = []
+  if (!fs.existsSync(dir)) return results
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      results.push(...getSkillFiles(p, prefix + entry.name + '/'))
+    } else if (entry.name.endsWith('.md')) {
+      results.push(prefix + entry.name)
+    }
+  }
+  return results
+}
+
+const [, , command, ...args] = process.argv
+
+switch (command) {
+  case 'add':
+    if (!args[0]) {
+      console.error('Usage: claudient add <category|all>')
+      process.exit(1)
+    }
+    addCategory(args[0])
+    break
+  case 'list':
+    listSkills()
+    break
+  case 'help':
+  case '--help':
+  case '-h':
+  case undefined:
+    usage()
+    break
+  default:
+    console.error(`Unknown command: ${command}`)
+    usage()
+    process.exit(1)
+}

package/scripts/link-skills.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# link-skills.sh — symlink all Claudient skills to ~/.claude/skills for local development
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CLAUDE_DIR="${HOME}/.claude"
+SKILLS_DEST="${CLAUDE_DIR}/skills"
+
+if [ ! -d "${CLAUDE_DIR}" ]; then
+  echo "Error: ~/.claude not found. Install Claude Code first."
+  exit 1
+fi
+
+mkdir -p "${SKILLS_DEST}"
+
+linked=0
+for category_dir in "${REPO_ROOT}/skills"/*/; do
+  category="$(basename "${category_dir}")"
+  dest="${SKILLS_DEST}/${category}"
+
+  if [ -L "${dest}" ]; then
+    echo "  ~ ${category}/ (already linked)"
+  elif [ -d "${dest}" ]; then
+    echo "  ! ${category}/ (exists as real dir — remove it first to symlink)"
+  else
+    ln -s "${category_dir}" "${dest}"
+    echo "  + ${category}/ → ${category_dir}"
+    ((linked++))
+  fi
+done
+
+echo ""
+echo "Done. Linked ${linked} new category symlink(s) to ${SKILLS_DEST}"
+echo "Restart Claude Code to pick up the skills."

package/scripts/list-skills.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# list-skills.sh — enumerate all skill .md files in the Claudient repo
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SKILLS_DIR="${REPO_ROOT}/skills"
+
+total=0
+
+for category_dir in "${SKILLS_DIR}"/*/; do
+  category="$(basename "${category_dir}")"
+  files=()
+
+  while IFS= read -r -d '' file; do
+    # Skip translation directories (fr/, de/, nl/, es/)
+    rel="${file#${category_dir}}"
+    if [[ "${rel}" =~ ^(fr|de|nl|es)/ ]]; then
+      continue
+    fi
+    files+=("${rel}")
+    ((total++))
+  done < <(find "${category_dir}" -name "*.md" -not -path "*/fr/*" -not -path "*/de/*" -not -path "*/nl/*" -not -path "*/es/*" -print0 | sort -z)
+
+  if [ ${#files[@]} -gt 0 ]; then
+    echo "${category}/ (${#files[@]})"
+    for f in "${files[@]}"; do
+      echo "  ${category}/${f}"
+    done
+  fi
+done
+
+echo ""
+echo "Total: ${total} skill(s)"

package/skills/ai-engineering/agent-construction.md

@@ -0,0 +1,285 @@
+# Agent Construction Skill
+
+## When to activate
+- Designing a multi-agent system with Claude (orchestrator + subagents)
+- Building a Claude-powered agent that uses tools across multiple turns
+- Designing memory for a long-running agent (in-context vs. external)
+- Handling agent errors, retries, and stopping conditions
+- Implementing agent handoffs between specialized subagents
+
+## When NOT to use
+- Single-turn Claude API calls — the Claude API skill is sufficient
+- Simple chatbots without tool use or autonomous decision-making
+- LangChain/LlamaIndex abstractions — address the abstraction layer directly
+
+## Instructions
+
+### Agent architecture patterns
+
+**Single agent with tools** — one Claude instance, multiple tools, loops until task is done:
+```
+User → Agent → [Tool A] → [Tool B] → Agent → User
+```
+
+**Orchestrator + subagents** — one parent spawns specialized children:
+```
+User → Orchestrator → [ResearchAgent] → [WriterAgent] → Orchestrator → User
+```
+
+**Pipeline** — agents hand off results in sequence:
+```
+User → Agent1(classify) → Agent2(extract) → Agent3(generate) → User
+```
+
+Choose the simplest architecture that solves the problem. Single agent with tools handles most cases.
+
+### Tool design
+```python
+# Tool definitions for multi-turn agent loop
+tools = [
+    {
+        "name": "search_web",
+        "description": "Search the web for current information. Use when you need facts not in your training data.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "Search query"}
+            },
+            "required": ["query"]
+        }
+    },
+    {
+        "name": "read_file",
+        "description": "Read contents of a file by path.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Absolute file path"}
+            },
+            "required": ["path"]
+        }
+    },
+    {
+        "name": "write_file",
+        "description": "Write content to a file. Creates the file if it doesn't exist.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "content": {"type": "string"}
+            },
+            "required": ["path", "content"]
+        }
+    }
+]
+```
+
+Tool design rules:
+- Description must tell Claude WHEN to use it, not just what it does
+- Keep `input_schema` minimal — only required fields, no optional noise
+- Return structured data (JSON), not prose, so Claude can use it reliably
+- One tool per action — don't bundle read+write into one tool
+
+### Agent loop
+```python
+import anthropic
+import json
+
+client = anthropic.Anthropic()
+
+def run_agent(task: str, max_iterations: int = 20) -> str:
+    messages = [{"role": "user", "content": task}]
+    
+    for iteration in range(max_iterations):
+        response = client.messages.create(
+            model="claude-sonnet-4-6",
+            max_tokens=4096,
+            system=AGENT_SYSTEM_PROMPT,
+            tools=tools,
+            messages=messages,
+        )
+        
+        # Append assistant's response
+        messages.append({"role": "assistant", "content": response.content})
+        
+        if response.stop_reason == "end_turn":
+            # Extract final text response
+            return next(b.text for b in response.content if hasattr(b, "text"))
+        
+        if response.stop_reason == "tool_use":
+            # Execute all tool calls in this response
+            tool_results = []
+            for block in response.content:
+                if block.type == "tool_use":
+                    result = execute_tool(block.name, block.input)
+                    tool_results.append({
+                        "type": "tool_result",
+                        "tool_use_id": block.id,
+                        "content": json.dumps(result) if not isinstance(result, str) else result
+                    })
+            
+            messages.append({"role": "user", "content": tool_results})
+        else:
+            # Unexpected stop reason
+            break
+    
+    raise RuntimeError(f"Agent exceeded {max_iterations} iterations without completing")
+
+
+def execute_tool(name: str, inputs: dict) -> any:
+    match name:
+        case "search_web":
+            return search(inputs["query"])
+        case "read_file":
+            return Path(inputs["path"]).read_text()
+        case "write_file":
+            Path(inputs["path"]).write_text(inputs["content"])
+            return {"success": True, "path": inputs["path"]}
+        case _:
+            return {"error": f"Unknown tool: {name}"}
+```
+
+### System prompt for agents
+```
+AGENT_SYSTEM_PROMPT = """You are an autonomous agent completing tasks step by step.
+
+Approach:
+1. Analyze the task before acting
+2. Use the minimum tools necessary
+3. Check your work before declaring done
+4. If a tool returns an error, diagnose and retry once — if it fails again, report the error
+
+Stopping conditions — declare "DONE: <result>" when:
+- The task is fully complete
+- You've hit an unrecoverable error after retrying
+- You've been asked to do something harmful or impossible
+
+Never loop more than 3 times on the same tool call with the same inputs.
+"""
+```
+
+### Memory patterns
+
+**In-context memory** (messages array) — for single session, small state:
+```python
+# Summarize when context grows large
+if count_tokens(messages) > 150_000:
+    summary = summarize_messages(messages[:-5])  # keep last 5 turns
+    messages = [
+        {"role": "user", "content": f"[Previous context summary]\n{summary}"},
+        {"role": "assistant", "content": "Understood. Continuing from where we left off."},
+        *messages[-5:]
+    ]
+```
+
+**External memory** (for multi-session agents):
+```python
+# Simple file-based memory
+class AgentMemory:
+    def __init__(self, path: str):
+        self.path = Path(path)
+        self.data = json.loads(self.path.read_text()) if self.path.exists() else {}
+
+    def remember(self, key: str, value: any):
+        self.data[key] = {"value": value, "timestamp": datetime.utcnow().isoformat()}
+        self.path.write_text(json.dumps(self.data, indent=2))
+
+    def recall(self, key: str) -> any:
+        entry = self.data.get(key)
+        return entry["value"] if entry else None
+
+    def as_context(self) -> str:
+        if not self.data:
+            return ""
+        lines = [f"- {k}: {v['value']}" for k, v in self.data.items()]
+        return "Known context:\n" + "\n".join(lines)
+```
+
+### Orchestrator pattern
+```python
+def orchestrate(task: str) -> str:
+    # Step 1: Planning agent decomposes the task
+    plan = run_subagent(
+        model="claude-sonnet-4-6",
+        system="You are a planner. Decompose tasks into numbered steps.",
+        task=f"Decompose this task into steps: {task}",
+        tools=[]  # No tools needed for planning
+    )
+
+    # Step 2: Execute each step with specialized agents
+    results = []
+    for step in parse_steps(plan):
+        agent_type = classify_step(step)  # "research" | "code" | "write"
+        result = run_subagent(
+            model=agent_model(agent_type),
+            system=agent_system_prompt(agent_type),
+            task=step,
+            tools=agent_tools(agent_type),
+            context="\n".join(results)  # Give context from previous steps
+        )
+        results.append(f"Step result: {result}")
+
+    # Step 3: Synthesis agent combines results
+    return run_subagent(
+        model="claude-sonnet-4-6",
+        system="You are a synthesizer. Combine step results into a final answer.",
+        task=f"Original task: {task}\n\nStep results:\n" + "\n".join(results),
+        tools=[]
+    )
+```
+
+### Error handling and stopping conditions
+```python
+class AgentError(Exception):
+    pass
+
+class MaxIterationsError(AgentError):
+    pass
+
+class ToolFailureError(AgentError):
+    pass
+
+def execute_tool_safe(name: str, inputs: dict, consecutive_failures: dict) -> dict:
+    try:
+        result = execute_tool(name, inputs)
+        consecutive_failures[name] = 0
+        return {"success": True, "result": result}
+    except Exception as e:
+        consecutive_failures[name] = consecutive_failures.get(name, 0) + 1
+        if consecutive_failures[name] >= 3:
+            raise ToolFailureError(f"Tool {name} failed 3 consecutive times: {e}")
+        return {"success": False, "error": str(e), "retry": True}
+```
+
+### Handoff pattern
+```python
+# Parent agent passes context explicitly — subagents have no session memory
+def handoff_to_specialist(context: dict, task: str, specialist: str) -> str:
+    handoff_prompt = f"""
+Context from orchestrator:
+{json.dumps(context, indent=2)}
+
+Your task:
+{task}
+"""
+    return run_subagent(
+        system=SPECIALIST_PROMPTS[specialist],
+        task=handoff_prompt,
+        tools=SPECIALIST_TOOLS[specialist]
+    )
+```
+
+## Example
+
+**User:** Build a research agent that takes a topic, searches the web for 3 sources, reads each URL, and writes a 500-word summary with citations to a file.
+
+**Expected output:**
+- `tools` list: `search_web`, `fetch_url`, `write_file`
+- System prompt: instructs agent to search → fetch 3 URLs → synthesize → write file before declaring done
+- `run_agent(task)` loop with `max_iterations=15`
+- Error handling: if `fetch_url` fails, try next search result
+- Final output: path to the written summary file
+
+---
+
+> **Work with us:** Claudient is backed by [Uitbreiden](https://uitbreiden.com/) — we build AI products and B2B solutions with developer communities. [uitbreiden.com](https://uitbreiden.com/)