sn-spec-writing
Skill8 starsChanged 7 months agoMITArchived repositoryView on GitHub
Write technical specifications for SignNow MCP Server features. Use when designing a new feature, writing a spec, performing architecture review, or converting a feature idea into requirements. Covers the analysis protocol (philosophy check, layer check, tool design, auth, errors, testability), spec output format, and Pydantic model design. Do NOT use for implementation, testing, or planning — those have dedicated skills.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- git-commitSkill
- sn-architectureSkill
- sn-implementationSkill
- sn-planningSkill
- sn-testingSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
Before designing any feature, run every check in order.
- Distinctive: line 35
If new: does it overlap with existing tools?
- Very specific: line 77
Write to .specs/Spec-{TASK_NAME}.md with these sections:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Technical Specification Writing
Analysis Protocol
Before designing any feature, run every check in order. If any check fails, reject or redesign before proceeding.
1. Philosophy Check
| Principle | Question |
| Thin Translator | Does this maintain the stateless translation identity? If it adds state, caching, or agent-side logic — redesign. |
| Simplicity | Is this the simplest possible solution? Can it have fewer moving parts? |
| YAGNI | Is the feature actually needed now, or is it speculative? |
2. Architecture & Layer Check
- Which layers are affected? Consult the layer access matrix (skill:
sn-architecture). - Upward imports (
signnow_client/→sn_mcp_server/)? → Reject. - Tool functions importing Starlette or referencing HTTP headers? → Redesign to use
TokenProvider. - Module-level mutable state, global caches, singletons? → Reject.
3. Tool Design Check
- Does this need a new MCP tool? Can the functionality join an existing tool instead?
- If new: does it overlap with existing tools? Could one tool handle both with an internal branch?
- Are parameters minimal and clear? Can an agent use this from the docstring alone?
- Does the response model include only decision-relevant fields? No raw API passthrough.
4. Auth & Transport Check
- Works across all 3 auth strategies (password grant, bearer header, OAuth2 JWT)?
- Works across all 3 transports (STDIO, Streamable HTTP, SSE)?
- No deployment-environment assumptions?
5. Error Handling Check
- List every failure mode explicitly.
- Each failure mode: specific error message with operation name, entity ID, cause.
- SignNow API errors translated via
signnow_client/exceptions.py. - Pydantic validation errors surfaced as clear parameter-level messages before any API call.
6. Testability Check
- Business logic testable by injecting a mocked
SignNowAPIClient? - List test cases: happy path + each failure mode.
- Any tests require network calls? → Redesign.
- New tests mirror
tests/unit/source structure.
7. Documentation Check
README.mdneeds updating? (New tools, auth changes, transport changes.)- Tool docstrings concise, accurate, actionable for an AI agent?
- Tool registered in
tools/__init__.py→register_tools()?
Output Style Rules
| Do | Don't |
| Define Pydantic models as complete runnable Python (models ARE the spec) | Write function bodies or full implementations |
Define function signatures with full type hints + docstrings (body = ...) | Paste raw SignNow API JSON responses |
| Use numbered pseudo-code for business logic flow | Reference Starlette/ASGI/HTTP in tool specs |
| Produce an explicit error catalog table | Skip error scenarios |
| Produce a test matrix table | Write actual test code |
Spec Output Format
Write to .specs/Spec-{TASK_NAME}.md with these sections:
1. Business Goal & Value
One paragraph max. Include a Philosophy Check table (Thin Translator, Stateless, Tool Minimization, Token Efficiency, YAGNI, No Infrastructure Coupling — each with ✅/❌ verdict + rationale).
2. Affected Layers
Table: Layer | File(s) | Change Type | Description.
3. System Diagram (Mermaid)
Sequence diagram: Agent → Tool → Business Logic → API Client → SignNow API → Response Model → Agent.
4. Technical Architecture
- 4.1 Pydantic Models — full Python code for all new/modified models (API-level and response-level).
- 4.2 Function Signatures — full signatures with type hints, docstrings, body =
.... - 4.3 Business Logic Flow — numbered pseudo-code steps per function.
- 4.4 Error Catalog — table: Trigger | Exception Class | Message Template.
5. Implementation Steps
Ordered checkbox list. Each step = one reviewable unit.
6. Test Matrix
Table: Test Name | Input | Mocked API Behavior | Expected Output/Assertion.
7. Risk Assessment
Table: Risk | Impact | Likelihood | Mitigation.
8. File Structure Summary
Tree view of all new and modified files.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

