Coding Skill

Coding Skill (Primary Playbook)

This SKILL.md is the default guide for common coding tasks. Focus on reliable tool usage and verifiable code changes. Load references/* only when needed.

1) Scope and Boundary

• This skill covers generic coding work: discover, read, edit, refactor, and validate code.
• This skill is tool-centric. Keep guidance about product/domain-specific implementation out of the main flow.
• All coding-tool paths are resolved under project_dir. Paths outside project_dir are invalid.
• Use minimal edits first; escalate to broad rewrites only when partial edits are unstable.
• Do not introduce hardcoded secrets, machine-specific absolute paths, or environment-specific install commands in generated code.

2) Zero-Context Execution Flow (Default)

When repository context is limited, use this fixed sequence:

1. search_code to locate files/snippets.
2. Run quick environment preflight for path/tool consistency:
   • confirm project_dir-relative target paths
   • avoid bare pip; prefer interpreter-scoped install commands when needed
3. read_code to load exact edit context.
4. Apply smallest safe edit (replace_in_file or update_code).
5. For Python edits:
   • If you used write_code: syntax is already validated (pre-write check). Do NOT call syntax_check in the same tool call — the file won't exist yet when parallel tools run. Only use syntax_check separately for replace_in_file / update_code edits.
   • python -m py_compile <changed_file>.py (optional, for import-level validation; on Windows you may also use py -3 -m py_compile)
6. If syntax fails, patch the failing region with local edits first (replace_in_file / update_code), then re-run checks.
7. Re-read changed region (read_code) when ambiguity/count errors occurred.
8. Report changed files, validations, and unresolved risks.

Prefer not to skip to later steps when an earlier step fails.

3) Tool Contract (Default)

3.1 search_code

Purpose: text/regex discovery in project files. Returns file:line:col: matched_text for each match.

Important: This tool only returns the matching line text, NOT full function/class definitions or surrounding code. To read the full implementation of a matched symbol, use read_code with the file path and line range from search results.

Required:

• query (string)

Common optional:

• path (default ".")
• file_glob (default "**/*")
• use_regex (default false)
• max_results (default 200, range 1-1000)

Example:

{
  "query": "class Workflow",
  "path": "agentclaw",
  "file_glob": "**/*.py"
}

3.2 read_code

Purpose: read file content by line range or Python symbol.

Required:

• path

Optional:

• start_line, end_line
• symbol (Python only)
• symbol_type (auto|function|class)

Examples:

{
  "path": "agentclaw/graph/workflow.py",
  "start_line": 60,
  "end_line": 180
}

{
  "path": "agentclaw/node/llm.py",
  "symbol": "_build_messages",
  "symbol_type": "function"
}

3.3 syntax_check

Purpose: language-aware syntax diagnostics.

Required:

• path

Optional:

• language override (py|js|ts|json|yaml|toml)
• context_lines (default 3, range 0-8)
• include_source_context (default true)

Example:

{"path":"agentclaw/node/llm.py"}

When to use:

• immediately after editing Python/JS/TS/JSON/YAML/TOML files
• before py_compile/register/runtime checks

When NOT to use:

• for semantic/runtime logic debugging (it is syntax-focused)
• as a replacement for import/runtime validation

Common failure shapes -> next action:

• path_not_found / Not a file
  • align path with project_dir, then retry same check
• PY_SYNTAX_ERROR / syntax diagnostics with line+col
  • patch failing region via replace_in_file or update_code, then re-run syntax_check
• checker unavailable (node, tsc, PyYAML, tomli)
  • report dependency gap and continue with partial validation

Output format:

• Human-readable block first (error message, source context with > marker, smart HINT), followed by structured JSON.
• HINT line detects common root causes:
  • HTML entities (" > ') → use write_code instead of write_file to auto-sanitize.
  • double-escaped sequences (\\\\n) → use literal multi-line content or single \\n.
• ok=true + status=success: syntax pass with no flagged risk pattern.
• ok=true + status=warning: syntax pass but risk_diagnostics is non-empty.
  • treat as unresolved risk and patch before claiming completion.
• ok=false + diagnostics: syntax failure; repair same region first.

3.4 update_code

Purpose: regex-based code update with automatic syntax validation.

Required:

• path
• pattern (Python regex)
• replacement

Optional:

• dry_run (default false)

Features:

• Uses Python regex with re.MULTILINE flag
• Automatically validates syntax after update (Python/JSON files)
• Returns syntax warnings without blocking write (allows incremental fixes)

Example:

{
  "path": "agentclaw/node/llm.py",
  "pattern": "def\\s+old_name\\(",
  "replacement": "def new_name(",
  "dry_run": true
}

When to use:

• Pattern-based refactoring across code
• Renaming functions/variables with regex
• Updating repeated code patterns

When NOT to use:

• Exact text replacement (use replace_in_file)
• Large block rewrites (use write_code)

Result includes:

• syntax_warning: line number and error if syntax check fails (does not block write)
• preview: affected code lines
• replacements: number of matches replaced

3.5 replace_in_file

Purpose: deterministic single-file snippet replacement.

Required:

• path, old_text, new_text

Optional:

• replace_all (default false)
• expected_replacements
• occurrence_index (1-based)

Notes:

• old_text and new_text are matched/written LITERALLY — no escape sequence processing (\\n means literal backslash-n). Use real multi-line strings for actual newlines.

Rules:

• Use this for small exact replacements, not broad transformations.
• If multiple matches and replace_all=false, set occurrence_index to disambiguate.
• expected_replacements should only be set when match count is deterministic.
• If expected_replacements mismatches, re-read file and recalculate before retrying.

Example:

{
  "path": "workflows/nl2sql.py",
  "old_text": "Workflow(\"nl2sql\")",
  "new_text": "Workflow(id=\"nl2sql\", name=\"NL2SQL\")"
}

3.6 write_file

Purpose: create/overwrite a full file when partial edit is inefficient.

Note: For source code files (.py, .js, .ts, .json, etc.), prefer write_code (section 3.8) — it auto-sanitizes HTML entities and runs pre-write syntax checks.

Required:

• path (relative project path)
• content (raw source text)

Rules:

• Content is written LITERALLY as-is — no escape sequence processing (\\n becomes literal backslash-n, not a newline). Use real multi-line content for actual newlines.
• Use write_file for new files or full rewrites only.
• For existing files, prefer replace_in_file / update_code; only use write_file overwrite when intentional.
• If an existing file was already written once in this task, do not keep rewriting it with write_file; switch to local patch tools for follow-up fixes.
• Do not pass source text into path.
• Keep content as raw code; do not pre-escape triple quotes into the final file.
• Always re-read the file after write_file before registration/runtime checks.
• If writing Python code, run syntax_check + python -m py_compile immediately after write_file.
• If syntax fails after write_file, do not rewrite whole file first; repair failing region with targeted edits.

Example:

{
  "path": "workflows/new_agent.py",
  "content": "from agentclaw import Workflow\n..."
}

When to use:

• creating a new file
• full overwrite only when partial edits are clearly unstable

When NOT to use:

• one-line or small region fixes (prefer replace_in_file / update_code)
• first attempt for syntax error repair on an existing file

Common failure shapes -> next action:

• content_too_large
  • split into smaller deterministic edits
• post-write syntax error
  • run local patch loop on failing lines; do not jump to another full rewrite
• path confusion after write
  • re-list and re-read file with project_dir-relative path, then validate again

3.7 Safe Coding Patterns (Avoid Syntax Errors)

When generating code with complex strings or nested structures, use segmented writing to prevent syntax errors.

Rule 1: Segmented Writing Strategy

For new files with complex content:

1. Write basic structure (imports, class/function signatures)
2. Run syntax_check to validate
3. Add simple logic and core functionality
4. Run syntax_check to validate
5. Add complex content (long strings, nested structures)
6. Run syntax_check + py_compile to validate

Rule 2: Complex String Handling

For code containing long prompts or multi-line strings:

1. Use separate constant definitions for complex strings
2. Keep string nesting simple (avoid mixing f-strings with triple quotes)
3. Use textwrap.dedent for indentation handling when needed
4. Validate after each addition

Rule 3: Incremental Validation

After each write_file or significant edit:

1. If write_code was used: syntax is already validated — skip syntax_check (do NOT call it in the same tool batch as write_code; the file won't exist yet).
2. If replace_in_file / update_code was used: run syntax_check in a separate tool call.
3. If syntax passes, run py_compile for Python files.
4. Fix any issues with local edits before adding more content.
5. Only proceed to next content addition after validation passes.

This approach reduces syntax error rates and makes fixes more targeted.

3.8 write_code (Preferred for source code)

Purpose: write source code files with automatic sanitization and pre-write validation. Use this instead of write_file for any source code (.py, .js, .ts, .json, etc.).

Required:

• path (relative project path)
• content (source code)

Optional:

• overwrite_existing (default false)

Auto-sanitization:

• HTML entities (" → ", ' → ', > → >, & → &) are auto-decoded
• Double-escaped newlines (\\n literal) trigger a warning in the response

Pre-write checks:

• Python files: compile() check before writing; rejects invalid syntax without touching file
• JSON files: json.loads() check before writing

Result contract:

• [OK] with file stats on success; includes note=html_entities_auto_fixed if sanitization was applied
• [SYNTAX_ERROR] with line context and smart HINT if pre-write check fails — file NOT written
• [Error] on parameter/path validation failure

Example:

{
  "path": "workflows/nl2sql.py",
  "content": "from agentclaw import Workflow\n\nworkflow = Workflow(id=\"nl2sql\")\n",
  "overwrite_existing": true
}

When to use:

• any new code file creation
• full overwrite of source code when partial edits are unstable
• when model output may contain HTML entity encoding

When NOT to use:

• non-code files (configs, logs, binary) — use write_file
• small edits to existing files — use replace_in_file / update_code

3.9 lookup_api

Purpose: introspect installed Python packages to discover correct import paths, constructor signatures, and methods. Use this when you are unsure of the correct import or API for any installed library.

Required:

• module (e.g. "agentclaw", "agentclaw.node")

Optional:

• symbol (e.g. "LLMNode", "Workflow") — omit to list all exported names
• include_methods (default false) — list public methods of a class

Examples:

{"module": "agentclaw"}

→ Lists all classes, functions, and other exports of the module.

{"module": "agentclaw", "symbol": "LLMNode", "include_methods": true}

→ Returns: import paths (shortest + source), constructor signature, description, and public methods.

When to use:

• before writing import statements for unfamiliar packages
• when search_code cannot find the symbol (because it is in an installed package, not project code)
• to verify constructor arguments before generating code

When NOT to use:

• for project-local code (use search_code + read_code instead)
• for non-Python packages

4) Tool Selection Strategy

• replace_in_file: first choice for small deterministic edits.
• update_code(anchor): bounded block insertion/replacement with explicit anchors.
• update_code(regex): repetitive pattern refactors.
• replace_in_files: broad mechanical rename/namespace updates.
• write_code: preferred for creating new code files or full rewrites (auto-sanitizes, pre-validates).
• write_file: non-code files or when write_code is not appropriate.
• lookup_api: verify imports and constructor signatures before generating code for installed packages.
• For precise single-target edits, prefer:
  1. replace_in_file + occurrence_index / expected_replacements
  2. update_code(exact) + expected_count=1
  3. avoid unbounded replace_all=true unless scope guards are set.

5) Failure Recovery Loop (Default)

1. Classify failure first: path, parameter, count, ambiguity, or checker environment.
2. Fix the same failing tool call before switching to unrelated tools.
3. Re-read local context before retry when mismatch/ambiguity appears.
4. Retry with corrected args.
5. After two same-shape failures, switch strategy and explain the switch.
6. For syntax failures after code edits, prefer local patch loops before full-file rewrite.

5.1 Error-Code Repair Playbook (Default)

Map structured failures to deterministic next actions:

• error_class=path_not_found
  • Action: verify project_dir-relative path with search_code/read_code, then retry same tool.
• error_class=parameter_validation
  • Action: correct required args for current mode/tool, retry immediately.
• error_class=ambiguous_match
  • Action: set occurrence_index or narrow match anchors/text.
• error_class=replacement_scope_too_large
  • Action: narrow scope first; only then set explicit replacement caps.
• error_class=syntax_error or SYNTAX_ERROR diagnostics
  • Action: patch failing region with local edit tools, then re-run syntax_check + py_compile.
• checker unavailable errors
  • Action: report missing dependency and keep status partial if this blocks required validation.

Common patterns:

• path_not_found / Not a file
  • Re-discover path with search_code; confirm relative path under project_dir.
• parameter_validation / missing fields
  • Correct required mode fields and retry same tool immediately.
• expected_count / expected_replacements mismatch
  • File changed or match pattern drifted; re-read and recompute.
• ambiguous match
  • provide occurrence_index or explicit ambiguity override.
• replacement scope too large
  • narrow old_text/anchors, or set explicit max_replacements / max_total_replacements after verifying match count.
• checker unavailable (node, tsc, PyYAML, tomli)
  • report dependency gap and treat validation as partial.
• syntax/compile failure after write
  • run targeted fix on failing lines with replace_in_file/update_code;
  • only do full rewrite when local fixes failed repeatedly.

6) Structured Outcome Contract (Default)

When using MCP coding tools, consume structured fields first, not prose keywords:

• success hints:
  • ok=true
  • changed / replacements present as expected
  • for syntax_check, require status=success (not warning) before claiming clean pass
• failure hints:
  • error_class
  • missing_fields
  • suggested_fix
  • explicit [ERROR] ... prefix

Required behavior:

1. If error_class=parameter_validation, fix arguments and retry the same tool.
2. If result is dry_run=true, do not claim the edit is applied.
3. If replacement/count guard fails, re-read target region before retry.
4. In final report, bind each claimed change to a concrete successful tool call.
5. If syntax_check returns risk_diagnostics, include them in risks or fix them before marking completed.

7) Validation Standard

For code-change tasks:

1. syntax_check for changed files when supported.
2. py_compile for changed Python files.
3. If changed files include workflows/*.py, confirm bootstrap import wiring in server.py (direct import or via workflows/__init__.py).
4. Re-run focused checks when previous step failed.

Do not report full completion without validation evidence.

7.1 Workflow Tooling Pattern (Recommended)

For workflow-local tools in generated workflow files:

1. Prefer @workflow.tool as the default registration path.
2. Use workflow.register_toolkit(...) only when cross-workflow reuse/pluginization is explicitly required.
3. If migrating old examples (ToolKit() + workflow.use(toolkit)), keep behavior equivalent and avoid unrelated rewrites.

8) Anti-Hardcoding Rules (Default)

• Never write credentials/tokens/passwords directly into source files.
• Avoid absolute host-specific paths (for example /home/<user>/...) in code and scripts.
• Prefer config/env-based values and explicit input parameters.
• If dependency installation is required, do not emit bare pip install ... by default.
  • prefer <python_executable> -m pip ... or project-selected package manager strategy.

8.1 Import Validity Check (Recommended for generated code)

• Do not invent module paths or symbol names from memory.
• Before final write_code/write_file for framework code, verify:
  • imported module path exists in the local repository/runtime;
  • imported symbols are actually exported.
• For installed packages: use lookup_api(module="<pkg>", symbol="<name>") to get correct import paths and constructor signatures.
• For project-local code: use search_code/read_code to confirm local definitions before writing.
• If registration/preflight reports import blockers, fix imports first, then continue to syntax/runtime validation.

9) Completion Contract

Final result should include:

1. changed_files
2. operations (tools actually used)
3. validation (syntax_check, py_compile, or explicit limitations)
4. status (completed / partial / blocked)
5. next_step (if not completed)

10) Reference Policy

Read references only when needed. Read only when task requires coordination between coding_skill and agent_creator:

• references/agent_workflow_coding_notes.md