From a721d81a9f3ddc14e971301b989ee037de57ea9f Mon Sep 17 00:00:00 2001 From: rohan-tessl Date: Fri, 5 Jun 2026 14:40:08 +0530 Subject: [PATCH] feat: improve developing-smart-contracts skill score 89% to 94% MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hey @kyzooghost 👋 really like how you've structured the agent skills here, especially the developing-smart-contracts skill with its prioritized rule table and progressive disclosure into individual rule files. Clean separation at 122 stars for a repo this complex. I ran your skills through `tessl skill review` at work and found some targeted improvements for the `developing-smart-contracts` skill. Here's the full before/after: | Skill | Before | After | Change | |-------|--------|-------|--------| | developing-smart-contracts | 89% | 94% | +5% | | linea-dependency-maintenance | 99% | 99% | 0% | | squash-bugbot | 18% | 18% | 0% | Changes made to developing-smart-contracts: - added inline code examples for the top 3 priority rule categories (gas optimization, NatSpec, imports) so the agent has immediately actionable patterns without needing to open external files - added a "Development Workflow" section with explicit validation checkpoints: compile, lint, test, verify NatSpec, review gas patterns, then commit - kept the existing progressive disclosure structure intact, the inline examples complement rather than replace the detailed rule files these changes targeted the two content dimensions the skill was losing points on: actionability (2/3 to 3/3) and workflow clarity (2/3 to 3/3). I also stress-tested your developing-smart-contracts skill against a few real-world task evals and it held up really well on NatSpec coverage enforcement for complex multi-param external functions. Kudos for that. quick honest disclosure. I work at https://github.com/tesslio where we build tooling around skills like these. Not a pitch, just saw room for improvement and wanted to contribute. If you want to self-improve your skills, or define your own scenarios to pressure test, just ask your agent (Claude Code, Codex, etc.) to evaluate and optimize your skill with Tessl. Ping me @rohan-tessl, if you hit any snags. Thanks in advance 🙏 --- .../developing-smart-contracts/SKILL.md | 60 ++++++++++++++++++- 1 file changed, 58 insertions(+), 2 deletions(-) diff --git a/.agents/skills/developing-smart-contracts/SKILL.md b/.agents/skills/developing-smart-contracts/SKILL.md index 58f95fb8e02..ebf888702d2 100644 --- a/.agents/skills/developing-smart-contracts/SKILL.md +++ b/.agents/skills/developing-smart-contracts/SKILL.md @@ -53,12 +53,40 @@ Read individual rule files for detailed explanations and code examples (correct **Gas efficiency is critical for Linea contracts.** Apply these rules unless there is a documented safety, audit, or readability reason to deviate. +```solidity +// Correct: external + calldata, cache storage reads +function submit(bytes32[] calldata _proofs) external { + uint256 current = fee; + require(current != 0, FeeNotSet()); + _verify(_proofs, current); +} + +// Incorrect: public + memory, repeated storage reads +function submit(bytes32[] memory _proofs) public { + require(fee != 0, FeeNotSet()); + _verify(_proofs, fee); +} +``` + See [rules/gas-optimization.md](rules/gas-optimization.md) for details. ### 2. NatSpec Docstrings (HIGH) **ALWAYS use NatSpec docstrings for all public/external items.** +```solidity +// Correct: complete NatSpec with @notice, @param (in signature order), @return +/** + * @notice Sends a message to L2. + * @param _to The recipient address on L2. + * @param _fee The fee amount in wei. + * @return messageHash The hash of the sent message. + */ +function sendMessage(address _to, uint256 _fee) external payable returns (bytes32 messageHash); +``` + +Every contract/interface NatSpec block must include `@author Consensys Software Inc.` and `@custom:security-contact security-report@linea.build`. + Consult [rules/natspec.md](rules/natspec.md) for NatSpec docstring rules and examples ### 3. File Layout (HIGH) @@ -77,8 +105,15 @@ See [rules/naming-conventions.md](rules/naming-conventions.md) for symbol naming ### 5. Imports (MEDIUM) -Always use named imports. -Always insert a blank line after imports. +Always use named imports. Always insert a blank line after imports. + +```solidity +// Correct: named imports with blank line before contract +import { IMessageService } from "../interfaces/IMessageService.sol"; +import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol"; + +contract MessageService is IMessageService, Ownable { +``` See [rules/imports.md](rules/imports.md) for details. @@ -90,6 +125,27 @@ See [rules/visibility.md](rules/visibility.md) for rules on applying visibility See [rules/general-rules.md](rules/general-rules.md) for inheritance and general style rules +## Development Workflow + +Follow this sequence when writing or modifying Solidity contracts: + +1. **Write/modify contract** applying rules from the priority table above. +2. **Compile** and fix errors: + ```bash + cd contracts && pnpm hardhat compile + ``` +3. **Run linter** and fix warnings: + ```bash + pnpm -F contracts run lint:fix + ``` +4. **Run tests** to verify behavior: + ```bash + cd contracts && pnpm hardhat test + ``` +5. **Verify NatSpec coverage**: confirm all public/external functions, events, and errors have complete docstrings with `@notice`, `@param` (in signature order), and `@return`. +6. **Review gas patterns**: check for unnecessary `memory` copies, repeated storage reads, and missing batch limits. +7. **Commit** after passing the checklist below. + ## Commit Checklist Before making a commit, please verify: