Customer-readable description
What this skill can do
Establish a verifiable working contract for code implementation, bug fixes, refactoring, and review: what to change, why to change it, how to prove the change is correct, and which risks remain uncovered.
| What the customer wants | What the skill will do | What the customer can see |
|---|---|---|
| Fix defects or implement features | First define the minimal scope and acceptance evidence, then make the minimal reliable change | Change mapping, test evidence, and residual risks |
| Review or refactor | Check behavior preservation, type boundaries, and similar patterns | Findings, review path, and unhandled items |
How the customer uses it
State the goal, the target repository, relevant files, the observable expected behavior, and the available tests or reproduction path. When authentication, deletion, irreversible data changes, public APIs, or remote releases are involved, missing critical constraints must be asked about first.
Dependencies and installation
Installation:
claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-dev@soia
When you only want this one skill, the npx route can be used. Note that the skill will land in the shared source of truth ~/.agents/skills; if a plugin is also installed, the same skill will have two indexes that drift separately, so it is recommended to choose one of the two:
npx skills add soia-team/soia-open-dev-skills -g -a '*' -s soia-dev-coding-protocol -y
Hard dependencies: the target repository and verification means commensurate with the task. Prefer the project's existing tests, lint, type checking, and fixtures; when absent, use the narrowest reliable reproduction and state the limitations. This skill requires no private configuration.
WorkBuddy 's loading unit is role-based experts rather than plugins,npx skills add -a '*' does not cover it, and it needs to be installed separately, see docs/install/workbuddy.md。
Private information and intermediate data
- Only read the source code, configuration, tests, and log fragments needed for the current task; when encountering credentials, customer data, or production logs, minimize references and do not copy them into patches, test fixtures, or receipts.
- Code changes and user-requested deliverables remain in the target repository or the user-specified path. This skill does not create its own persistent state, cache, or invocation records.
- Temporary files produced by tests, builds, and tools follow the target repository's conventions; when there are no conventions, use the operating system's temporary directory, and after the task ends clean up content created by this skill that can be safely deleted.
- Provider credentials use only the official login state or system credential store; ordinary
config.yml, command lines, logs, and commits must not store secrets. - The completion receipt records only file paths, check commands, and result summaries, and does not echo secret values, full prompts, or irrelevant source code text.
Logs and completion receipts
完成：<实现、修复、重构或评审结果>。
契约：<假设、范围边界、验收目标>
文件变化：<每项变更如何映射到请求>
验证：<命令、结果和独立复核>
残余风险：<未覆盖场景或“无”>
Execution contract
Before writing code, make clear:
- Assumptions: which come from observation and which are inferences;
- Scope: what is included and what is not;
- Verification plan: the falsifiable check corresponding to each step.
After writing code, make clear: what was changed, how it satisfies the request, which verifications were actually run, and which real risks still remain. Without evidence, it cannot be called complete.
Core rules
1. Expose uncertainty
Ambiguities that affect correctness, security, external behavior, data integrity, or API contracts must be asked about first. Low-risk ambiguities should be resolved with the narrowest, reversible interpretation and explained. Authentication, destructive operations, and irreversible changes must not proceed on guesswork.
2. Minimal Scope
Write only the code needed to fully solve the current problem. Do not add abstractions, toggles, renames, formatting, or "might be needed in the future" branches just because it is convenient. Report unrelated issues separately; do not mix them into the patch.
3. Isolate and Trace Changes
Every line of change should map to the request or to validation necessary for that change. Follow the surrounding style; remove only what is made obsolete by this change. After fixing one pattern, search for similar call sites, then decide whether to include them in scope.
4. Verify Results, Not Intentions
- bug fix: reproduce first when feasible; otherwise establish the narrowest failing check;
- validation logic: cover invalid input and the expected passing path;
- refactor: prove semantics are preserved with before/after or behavior tests;
- multi-step task: first write
[步骤] -> [验证]； - When tests fail, cannot run, or cover only the happy path, report it truthfully; "the code looks right" cannot substitute for evidence.
Anti-Fake-Fix Gate
Before claiming completion, check item by item:
| Symptoms | Requirements |
|---|---|
| Claiming completion without running validation | Run the real command or clearly explain why validation cannot be performed |
| Using TODO, comments, or swallowed errors instead of a fix | Make the behavior itself meet the requirement, or clearly mark the task as incomplete |
| Verifying only your own conclusion | Use an independent path: tests, fixtures, type checking, logs, or manual review |
| Stopping after fixing one spot | Search for the same pattern; explain the reason for including or excluding it |
| Mixing unrelated adjustments into one commit | Split out or remove unrelated changes |
Additional contracts for interfaces, traits, and adapters
Before starting implementation, the task must clearly specify:
- Context serialization: whether and in what format system, message order, tools, and tool call/result are each passed;
- Usage/billing semantics: how the caller distinguishes metering, subscription, or other models; if the interface lacks expressive capability, add it to the interface first;
- Type ownership: types on the public surface come from this module or an explicit dependency; avoid copying high-level types to form shadow enums;
- Downstream impact: list known consumers, how they use the new method, and their validation paths.
At minimum verify: a context turn containing system, more than two rounds of messages, and tools; usage semantics; type ownership search; and one complete path to a downstream consumer. If any item is missing, stop and request a complete specification.
Pre-submit self-review
- Resources: no unnecessary per-call client/process leaks; child processes and stderr are handled correctly;
- Testable and configurable: no endpoint, binary path, or user input is hardcoded in a non-replaceable location;
- Security: defaults do not expand permissions, and untrusted input is not concatenated into the shell;
- Cross-platform: support or fallback behavior for platform branches is clear;
- Observability: errors are not silently discarded, and failures include sufficient context;
- Consistency: Public interfaces have the necessary documentation, and metadata is kept in sync with related change records;
- Dependency direction: No upper-layer types are redundantly defined or reverse dependencies created.
Matched items must be fixed, or the delivery must clearly state why they are deferred and the associated risks.
Security boundary
Commits, pushes, releases, deletions, overwrites, and remote state changes require explicit authorization from this request. Recheck the target and scope of impact before execution; when committing, stage only the files for this task.
Verification
- Run the project checks closest to the risk surface;
- Recheck key conclusions via an independent path;
- Inspect the working tree and staging area to confirm no unrelated files enter the delivery;
- The receipt states only the checks actually performed and their results.