Swamp skill should guide AI agents to create extension models instead of inline shell scripts

[bixu]

Problem

When AI agents (like Claude Code) need to process or transform data from a swamp model method run, they default to piping stdout through complex inline shell scripts (python -c, deno eval, etc.) rather than creating a proper extension model or adding a method to an existing one.

This leads to:

• Fragile shell-escaped code that breaks on special characters
• Logic that is untestable and unreusable
• Violations of the "extend, don't be clever" principle from CLAUDE.md

Example

After running listUserRepos, the AI attempted to pipe JSON output through an inline python3 -c script with complex string processing to build a security report. This failed repeatedly due to shell escaping issues. The correct approach was to create a dedicated @bixu/github-security extension model with its own helpers and tests.

Proposed Solution

The swamp-extension-model skill and/or swamp-model skill should include stronger guidance for AI agents:

1. When an agent needs to transform or aggregate data from a model method, it should create a new extension model (or add a method to an existing one) rather than processing stdout inline
2. The skill should explicitly call out anti-patterns: inline python3 -c, deno eval, jq pipelines for anything beyond trivial formatting
3. The decision tree in the skill should include: "Need to process model output? -> Create an extension model method for it"

Scope

Changes would be needed in the swamp skill documentation (swamp-extension-model and swamp-model skills) to add guidance about when to create models vs. when inline processing is acceptable.

[github-actions]

Hi @bixu, thanks for opening this issue!

We appreciate you taking the time to report it. A maintainer will review it as soon as possible.

In the meantime, please make sure you've included all relevant details (steps to reproduce, expected vs actual behaviour, swamp version, etc.) to help us triage it quickly.

[stack72]

Closely related to #667 — same underlying principle ("prefer extension models over ad-hoc alternatives"), different manifestation. #667 covers shelling out to CLI tools; this one covers inline script processing of model output.

Planning to address both in a single PR. See #667 for the full scope — the changes relevant to this issue specifically are an anti-patterns section in the extension model skill (calling out python3 -c, deno eval, complex jq pipelines) and guidance in the model skill about when transforming output warrants a new extension model vs. when simple inline processing is acceptable.

[stack72]

Implementation Plan

Addressing both this issue and #667 together in a single PR. Full plan posted at #667 (comment) — here's a summary of the parts most relevant to this issue:

Changes specific to #662

swamp-extension-model/references/scenarios.md — New Scenario 5, Part B shows:

• Anti-pattern (marked as wrong): piping model output through python3 -c for inline processing
• Correct approach: creating a new @user/github-repo-report model that reads existing model data via dataRepository.getContent() and produces a structured report
• Complete, copy-paste ready TypeScript with Zod schemas, error handling, and writeResource — verified against the actual dataRepository API signature

swamp-extension-model/SKILL.md — The expanded decision tree includes a dedicated path:

Need to transform/aggregate model output? → Create a new model for it

swamp-model/SKILL.md — New "When to Extend vs. Shell Out" section explicitly covers: if you need to transform output beyond trivial formatting, create an extension model rather than processing stdout inline.

CLAUDE.md — New rule 7: "When you need to transform or aggregate model output, create an extension model for it. Don't pipe output through inline scripts."

No separate anti-patterns section in the skill — the scenario itself shows anti-patterns inline with "DON'T DO THIS" markers, which avoids redundancy.

[stack72]

In testing this:

❯ create me a model that I can use to create an aws ec2 instance

⏺ Skill(swamp-model)
  ⎿  Successfully loaded skill

⏺ Following the project rules, I'll search before building. Let me check for existing types and community extensions first.

⏺ Bash(swamp model type search "ec2" --json 2>&1)
  ⎿  {
       "query": "ec2",
       "results": [],
     … +2 lines (ctrl+o to expand)

⏺ Bash(swamp extension search "ec2 instance" --json 2>&1)
  ⎿  Running…

This feels way more correct behaviour now