Agent Skills: Assimilate

Assimilate

When to Use

• "improve the framework", "compare to competitor repos", "adopt best ideas"
• EVOLVE phase requiring external pattern benchmarking before creating artifacts
• Reflection output calls for concrete upgrade candidates

Iron Laws

1. NEVER implement borrowed ideas directly — produce feature map, gap list, and TDD backlog first.
2. ALWAYS create workspace under .claude/context/runtime/assimilate/<run-id>/.
3. ALWAYS use shallow clones (--depth=1) unless commit history is the comparison surface.
4. NEVER execute external project scripts — no npm install, make, ./setup.sh; read-only only.
5. ALWAYS score gaps by impact×feasibility before writing the TDD backlog.

Anti-Patterns

• Implementing patterns without gap analysis — always produce feature map first
• Cloning repos outside assimilate workspace — use .claude/context/runtime/assimilate/<run-id>/
• Running project scripts from clones — read-only analysis only
• Writing TDD items without acceptance criteria — every item needs RED test + measurable GREEN
• Gaps without complexity/risk scoring — score all: impact, complexity (S/M/L), risk

Four-Phase Execution (Framework Benchmarking)

Phase 1 — Clone + Stage: Create workspace → clone into externals/<repo-name>/ → capture commit hash, branch, structure.

Phase 2 — Comparable Surface Extraction: Extract normalized tables across: memory model, search stack, agent orchestration, creator system, observability.

Phase 3 — Gap List: Each gap: gap_id, current state, reference pattern (source + path), expected benefit, complexity (S|M|L), risk (low|medium|high), recommended artifact type.

Phase 4 — TDD Upgrade Backlog: RED (failing test + acceptance criteria) → GREEN (minimal implementation) → REFACTOR (hardening) → VERIFY (integration). Each item includes owner agent, target files, validation steps, rollback notes.

CLI Generation Pipeline (CLI-Anything 7-Phase)

When assimilating a CLI tool (inspired by HKUDS/CLI-Anything):

1. Discover — TOOL --help and TOOL SUBCOMMAND --help; build { commands, flags, outputFormats } map
2. Analyze — extract signatures, types, docs, dependencies; identify interaction model (REPL/one-shot/daemon)
3. Design — map capabilities to skill sections; define JSON output contract; identify dedup vs. new skills
4. Implement — write SKILL.md with workflow steps + concrete command examples with expected JSON output
5. Test — RED tests (expected output for known inputs) + boundary tests; create mock fixtures
6. Document — usage examples per workflow; env requirements (tool install, auth setup)
7. Deploy — pnpm skills:index; update agent-registry if assigned to specialist

Coverage target: covered_commands / total_commands * 100% — aim for >80% before marking complete.

JSON-Structured Agent Output

When assimilating code, write an API surface descriptor to .claude/context/runtime/assimilate/<run-id>/api-surface.json:

{
  "repo": "<name>",
  "commit": "<sha>",
  "api_surface": {
    "entryPoints": ["<file>:<export>"],
    "cliCommands": [{ "command": "<cmd>", "flags": [], "outputFormat": "json|text" }],
    "configKeys": [],
    "hookPoints": []
  },
  "gaps": [
    { "gap_id": "<id>", "impact": "H|M|L", "complexity": "S|M|L", "risk": "low|medium|high" }
  ]
}

Multi-Platform CLI Generation

After assimilation, generate installable wrappers. Always emit --output json flag. Use shell: false for subprocess calls. Never hardcode credentials.

• npm (Node.js): package.json bin field → cli.mjs with #!/usr/bin/env node → npx <tool>
• pip (Python): pyproject.toml [project.scripts] → cli.py with __main__ guard → pipx run <tool>
• cargo (Rust): Cargo.toml [[bin]] + clap → src/main.rs → cargo install <tool>
• go build (Go): cmd/<tool>/main.go + cobra → go install <module>@latest

CLI-Anything Wrapper Generation

Generate LLM-callable wrappers for ANY CLI tool using the CLI-Anything methodology (ref: HKUDS/CLI-Anything).

--help Autodiscovery Pattern

# Step 1: Capture help output for all subcommands
TOOL --help > help_root.txt
TOOL SUBCOMMAND --help > help_sub.txt

# Step 2: Parse into structured schema
node -e "
const help = require('fs').readFileSync('help_root.txt', 'utf8');
const commands = help.match(/^\s+(\w[\w-]*)\s+(.+)$/gm) || [];
console.log(JSON.stringify(commands.map(c => {
  const [, name, desc] = c.trim().match(/^(\S+)\s+(.+)$/) || [];
  return { name, description: desc };
}), null, 2));
"

MCP Tool Schema Generation from CLI

Convert discovered CLI capabilities into MCP tool definitions:

// From CLI --help output, generate MCP tool schema
function cliToMcpTool(command: CLICommand): McpToolDefinition {
  return {
    name: command.name.replace(/-/g, '_'),
    description: command.description,
    inputSchema: {
      type: 'object',
      properties: Object.fromEntries(
        command.flags.map(f => [
          f.name,
          {
            type: f.type || 'string',
            description: f.description,
            ...(f.default !== undefined && { default: f.default }),
          },
        ])
      ),
      required: command.flags.filter(f => f.required).map(f => f.name),
    },
  };
}

JSON Output Adapter Pattern

Force structured JSON output from CLI tools that normally produce text:

# Pattern: pipe text output through jq or custom parser
TOOL command --format json 2>/dev/null || \
TOOL command | node -e "
  const lines = require('fs').readFileSync('/dev/stdin','utf8').split('\n');
  console.log(JSON.stringify({ output: lines.filter(Boolean) }));
"

Supported Application Categories

| Category | Examples | Wrapper Pattern | | --------- | -------------------------- | ------------------------------------ | | Graphics | GIMP, Blender, ImageMagick | Batch processing via CLI flags | | Office | LibreOffice, Pandoc | Document conversion pipelines | | Dev Tools | Docker, kubectl, terraform | Direct JSON output (--format json) | | Media | ffmpeg, yt-dlp | Stream processing with progress | | System | systemctl, pm2 | Status queries + action commands |

Session Management

Track multi-session progress in .claude/context/plans/assimilate-{name}-progress.json:

{
  "name": "<repo>",
  "runId": "<uuid>",
  "lastUpdatedAt": "<ISO>",
  "phases": {
    "clone": "done|pending",
    "surface": "done|pending",
    "gaps": "done|pending",
    "backlog": "done|pending",
    "cli_pipeline": "done|pending"
  },
  "artifacts": { "apiSurface": "<path>", "gapList": "<path>", "backlog": "<path>" },
  "nextStep": "<description>"
}

On resume: read progress file → skip completed phases → continue from nextStep.

Memory Protocol (MANDATORY)

Before work: cat .claude/context/memory/learnings.md

After work: record assimilated patterns → learnings.md; adoption risks → decisions.md; blockers → issues.md.