mirror of
https://github.com/tiennm99/goclaw.git
synced 2026-10-14 02:15:57 +00:00
Viet TranandGoon
ace07509b7
* feat(infra): add runtime package support for skills Install nodejs, npm, pandoc, github-cli + pre-install Python packages (openpyxl, pandas, python-pptx, markitdown) and Node packages (docx, pptxgenjs). Configure runtime dirs for agent pip/npm installs with PIP_TARGET, NPM_CONFIG_PREFIX, NODE_PATH to enable dynamic package installation in read-only container environment. * feat(infra): add bundled skills with runtime package support - Add 5 bundled skills: docx, pdf, pptx, xlsx, skill-creator from container skills-store - Wire GOCLAW_BUILTIN_SKILLS_DIR env var in gateway and CLI - Support optional runtime packages alongside dynamic skill loading - Update Dockerfile to COPY bundled-skills at /app/bundled-skills/ - Add PIP_CACHE_DIR in docker-entrypoint.sh for clean pip installs - Document bundled skills in 14-skills-runtime.md section 6 * feat(infra): remove ai-multimodal skill directory from bundled skills Remove the ai-multimodal skill package as part of consolidating runtime package support for bundled skills. This directory is no longer needed in the bundled skills structure. * feat(ci): add semantic release and Docker Hub publishing Add go-semantic-release workflow to auto-create semver tags on merge to main. Extend docker-publish to push all variants to both GHCR and Docker Hub (digitop/goclaw). * feat(skills): add system skills infrastructure with is_system column, dep scanning, and seeder - Migration 000017: add is_system boolean column with partial index - Store layer: UpsertSystemSkill, delete protection, IsSystemSkill - ListAccessible auto-includes system skills (no grants needed) - ListWithGrantStatus returns is_system field - Dependency scanner: auto-detect deps from scripts/ or skill-manifest.json - Dependency checker: verify system binaries, Python/Node packages - Seeder: seed bundled skills into DB on startup (idempotent via hash) - Gateway wiring: GOCLAW_BUNDLED_SKILLS_DIR env for bundled skills - HTTP: delete guard (403), slug conflict check (409), rescan-deps endpoint - UI: System badge, hide delete for system skills, rescan deps button - Agent skills tab: "Always available" for system skills - i18n: en/vi/zh keys for system skills, deps scanning * feat(skills): conditional system prompt, skill manifests, and Zip Slip fix - System prompt: only show package list when python3/node are available - Add skill-manifest.json for pdf, docx, xlsx, pptx bundled skills - Fix Zip Slip vulnerability in office/unpack.py (all 3 copies) * refactor(skills): extract shared office code to _shared/ and deduplicate Move office scripts (pack, unpack, validate, schemas, validators) from duplicated copies in docx/xlsx/pptx to skills/_shared/office/ with symlinks. Remove soffice.py (non-functional in containers) and update SKILL.md references to use soffice binary directly. Update seeder copyDir to follow symlinks. Removes ~45K lines of duplicate code across 3 skills. * fix(skills): address code review findings for system skills integration - H1: Remove dead symlink branch in copyDir (filepath.Walk follows symlinks) - H3: Fix rescan-deps to query ALL skills (including archived) and re-activate when deps become available; add ListAllSkills() + Status field to SkillInfo - H4: Add Status field to SkillCreateParams, stop overloading Visibility - M1: Batch Python/Node dep checks into single subprocess per runtime - M4: Add rows.Err() check in ListSkills to prevent caching partial results * feat(skills): async dep checking with realtime WS events Split Seed() into sync DB upsert + async CheckDepsAsync() goroutine. Gateway startup no longer blocks on Python/Node subprocess dep checks. - Seed() returns seeded skills list, all initially status="active" - CheckDepsAsync() runs in background, emits skill.deps.checked per-skill - skill.deps.complete event emitted when all checks finish - Each failed dep check: archives skill + BumpVersion() for immediate cache invalidation so next agent turn picks up the change - UI: use-query-invalidation listens to skill.deps.* events → auto-refresh skills list in realtime * feat(skills): system skills integration with toggle, dep checking, and per-item install - Add is_system, deps, enabled columns to skills table (migration 017) - Seed bundled core skills (pdf, docx, pptx, xlsx, skill-creator) on startup - PYTHONPATH-based dep detection — eliminates false positives from local modules - Per-item dep install UI with individual status (installing/success/error) - Enable/disable toggle for core and custom skills (independent of dep status) - Re-run dep check when skill is toggled back on - Inline skill thresholds: 40 skills / 5000 tokens before switching to search mode - Fix UpsertSystemSkill: backfill null file_hash without bumping DB version - Remove redundant skill-manifest.json files (replaced by deps JSONB column) - Show author from frontmatter in custom skills tab - Runtime checker for python3/pip3/node/npm availability - WS events for dep checking/installing progress - docs: add 15-core-skills-system.md, 16-skill-publishing.md --------- Co-authored-by: Goon <duy@wearetopgroup.com>
2.7 KiB
2.7 KiB
Skill Design Patterns
Five proven patterns for structuring skills. Choose based on workflow type.
Choosing Approach: Problem-First vs Tool-First
- Problem-first: "I need to set up a project workspace" → skill orchestrates the right calls in sequence. Users describe outcomes; skill handles tools.
- Tool-first: "I have Notion MCP connected" → skill teaches optimal workflows and best practices. Users have access; skill provides expertise.
Pattern 1: Sequential Workflow Orchestration
Use when: Multi-step processes must happen in specific order.
Key techniques:
- Explicit step ordering with dependencies
- Validation at each stage
- Rollback instructions for failures
## Workflow: Onboard New Customer
### Step 1: Create Account
Call MCP tool: `create_customer` → Parameters: name, email, company
### Step 2: Setup Payment
Call MCP tool: `setup_payment_method` → Wait for verification
### Step 3: Create Subscription
Call MCP tool: `create_subscription` → Uses customer_id from Step 1
Pattern 2: Multi-MCP Coordination
Use when: Workflows span multiple services (Figma → Drive → Linear → Slack).
Key techniques:
- Clear phase separation
- Data passing between MCPs
- Validation before moving to next phase
- Centralized error handling
Pattern 3: Iterative Refinement
Use when: Output quality improves with iteration (reports, documents).
Key techniques:
- Generate initial draft → validate with script → refine → re-validate
- Explicit quality criteria and "stop iterating" conditions
- Bundled validation scripts for deterministic checks
Pattern 4: Context-Aware Tool Selection
Use when: Same outcome, different tools depending on context.
Key techniques:
- Decision tree based on inputs (file type, size, destination)
- Fallback options when primary tool unavailable
- Transparency about why a tool was chosen
Pattern 5: Domain-Specific Intelligence
Use when: Skill adds specialized knowledge beyond tool access (compliance, finance).
Key techniques:
- Domain rules embedded in logic (compliance checks before action)
- Comprehensive audit trails
- Clear governance and documentation of decisions
Use Case Categories
Category 1: Document & Asset Creation
Creates consistent output (documents, presentations, apps, designs). Uses embedded style guides, templates, quality checklists. No external tools required.
Category 2: Workflow Automation
Multi-step processes with consistent methodology. Uses step-by-step workflows with validation gates, templates, iterative refinement loops.
Category 3: MCP Enhancement
Workflow guidance atop MCP tool access. Coordinates multiple MCP calls, embeds domain expertise, handles common MCP errors.