Skip to content

agentsope/SkillAlchemy / skills/agentsop-signature-design

agentsop-signature-design

Verified

Decision rubric for promoting a prose prompt into a typed DSPy Signature. This is an ENHANCE overlay on top of the [[dspy]] library skill: it does NOT teach DSPy syntax — it answers the coder-agent decision "when do I stop hand-writing a prompt string and declare it as a `dspy.Signature`, and how do I name/describe its fields so the optimizer and the calling code both get a clean contract." Activate when: a prompt string grows past ~50 lines; the LM output is consumed by code (parsed, branched on, stored) rather than read by a human; the same prompt is reused across >1 call site; or a teammate asks "should this be a Signature?". Do NOT activate for one-shot throwaway prompts, or for HOW-TO questions about DSPy modules /optimizers/compile — defer those to the [[dspy]] skill and the [[agentsop-dspy]] workflow skill. Search keywords: typed prompt, structured prompt, DSPy Signature, prompt as a function, prompt contract, when to formalize a prompt.

FileKindSize
README.mdmarkdown3.0 KB
SKILL.mdskill md21.1 KB
intermediate/operation_candidates.jsonconfig6.3 KB
references/R1-source-evidence.mdmarkdown7.1 KB

intermediate/operation_candidates.json

View on GitHub
{
  "skill": "signature-design",
  "version": "0.1.0",
  "capture_date": "2026-05-20",
  "layer": "enhance-overlay",
  "decision_layer_only": true,
  "defers_implementation_to": ["dspy", "dspy-sop"],
  "primary_source": "/Users/5imp1ex/Desktop/Skill-Workplace/output/dspy-sop-skill/SKILL.md",
  "operations": [
    {
      "id": "OP-1",
      "name": "Gate: decide promote vs keep-prose",
      "trigger": "A prose prompt crosses a load-bearing threshold: > ~50 lines, OR its output is consumed by code, OR it is reused across > 1 call site",
      "action": "Run the promote-trigger checklist (LENGTH / CONSUMED / REUSED, + bonus signals). Zero boxes -> keep prose. One+ box -> promote.",
      "output": "Decision token: `promote` | `keep-prose`",
      "evidence": ["dspy-sop S1: prompts past ~50 lines are a symptom", "dspy-sop S7: do not promote while signature unstable"],
      "tags": ["entry-gate", "decision"]
    },
    {
      "id": "OP-2",
      "name": "Extract inputs and outputs into named slots",
      "trigger": "OP-1 returned `promote`",
      "action": "Read the prose prompt; list every variable the LM is given (inputs) and every distinct value it must return (outputs). Split fused outputs (e.g. 'category and reason' = two fields).",
      "output": "Flat list of typed I/O slots",
      "evidence": ["dspy-sop S2: field names carry intent; one concept per field"],
      "tags": ["shaping", "core"]
    },
    {
      "id": "OP-3",
      "name": "Name fields semantically",
      "trigger": "Slots extracted (OP-2)",
      "action": "Rename each slot to read like a function parameter (`text`->`ticket`, `out`->`category`). Avoid generic input/output. The name is the optimizer's only pre-data intent signal.",
      "output": "Field names that self-describe intent",
      "evidence": ["dspy-sop S2: name like function parameters in well-written code"],
      "tags": ["shaping", "core", "naming"]
    },
    {
      "id": "OP-4",
      "name": "Add descriptions only where the name underspecifies",
      "trigger": "Field names set (OP-3)",
      "action": "Add InputField(desc=) / OutputField(desc=) ONLY for fields whose name is ambiguous or that need a constraint (format/length/units/allowed values). Leave obvious fields bare.",
      "output": "Minimal, justified descriptions",
      "evidence": ["dspy-sop S3: cheatsheet leaves `question` bare, adds desc only on `answer`"],
      "tags": ["shaping", "naming"]
    },
    {
      "id": "OP-5",
      "name": "Type closed-set / boolean / numeric outputs",
      "trigger": "An output field has a fixed value set, a boolean meaning, or a numeric range",
      "action": "Type the OutputField (`Literal[...]`, `bool`, `int`, `float`) instead of `str`, so the type is both documentation and a parse guard, and downstream code stops scraping prose.",
      "output": "Typed OutputField; downstream parsing removed",
      "evidence": ["dspy-sop S3: upgrade to class-based Signature when types matter", "dspy-sop S5: signature shape is your code's job"],
      "tags": ["shaping", "typing"]
    },
    {
      "id": "OP-6",
      "name": "Defer module choice to [[dspy]]",
      "trigger": "Signature shaped; quality may benefit from reasoning",
      "action": "Note any module hint (e.g. 'reasoning helps -> likely ChainOfThought') but DO NOT decide here. Hand the shaped Signature to the [[dspy]] skill for module selection / evaluation / compile.",
      "output": "Hand-off note + context switch to [[dspy]]",
      "evidence": ["dspy-sop S4: module-selection table belongs to the dspy library/workflow"],
      "tags": ["boundary", "hand-off"]
    },
    {
      "id": "OP-7",
      "name": "Re-audit Signature when optimizer plateaus",
      "trigger": "Later, in [[dspy]], compilation gains flatten",
      "action": "Before blaming the optimizer, loop back: are inputs/outputs truly separated? Do field names carry intent? Ambiguous Signature is the common root cause.",
      "output": "Revised Signature (re-run OP-2..OP-5)",
      "evidence": ["dspy-sop S8: plateau usually means program/signature ambiguity, not optimizer"],
      "tags": ["iterate-back", "decision"]
    },
    {
      "id": "OP-8",
      "name": "Pair Signature with a grammar enforcer when machine-validity is mandatory",
      "trigger": "Output is consumed by code AND must be syntactically valid (strict JSON/grammar)",
      "action": "Keep the Signature for intent shaping + optimization, but add a token-level enforcer (Outlines/Guidance) for the hard syntax guarantee. A typed OutputField pushes toward structure but does not guarantee grammar.",
      "output": "Signature + enforcement layer",
      "evidence": ["dspy-sop S9: typed OutputField does not guarantee grammar conformance; use Outlines for that"],
      "tags": ["composition", "boundary"]
    }
  ],
  "field_naming_rules": [
    "Name like a function parameter, not like a prompt sentence.",
    "Inputs are nouns the LM receives; outputs are nouns it produces; do not mix.",
    "One concept per field; split fused outputs.",
    "Use the most specific type the value can hold (Literal/bool/int over str).",
    "Reserve desc= for what the name cannot say: format, length, units, allowed values, edge cases."
  ],
  "dilemma_cases": [
    {
      "id": "Case-A",
      "title": "80-line mega-prompt: promote whole vs split first",
      "decision": "Promote, but keep only the I/O shape in code; let instruction/demo prose become optimizer-owned; split fused outputs; type closed-set/boolean outputs.",
      "extractable_op": "OP-2, OP-5, mental-model #2"
    },
    {
      "id": "Case-B",
      "title": "One-shot disposable prompt someone wants to 'make robust'",
      "decision": "CONSUMED justifies a minimal TYPED Signature (parse safety) but NOT optimization. Separate 'promote to typed contract' from 'compile/optimize'.",
      "extractable_op": "OP-5 yes, refuse compile (S10), boundary S7"
    }
  ],
  "anti_patterns": [
    "Over-signaturizing one-off prompts (no trigger fired).",
    "Under-specifying field semantics (generic input/output names).",
    "One blob output that should be N typed fields.",
    "Copying whole prose prompt into the docstring (that text is the optimizer's).",
    "Promoting before the I/O contract stabilizes.",
    "Reflexively adding desc= to every field.",
    "Confusing 'promote to Signature' with 'guarantee valid JSON'."
  ]
}
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall