PFC5 FISH Skill: Tame Asphalt Simulation Scripts

Where this fits

You're mid-way through a PFC2D asphalt compaction simulation, and the FISH script you wrote in an afternoon just threw a nil pointer at step 10,000. You need to audit callbacks, check history IDs, and verify stop logic—but the model is huge and the syntax unforgiving. This skill turns an agent into a FISH-aware linter, contract writer, and probe runner, so you can debug and extend simulation control without a PhD in PFC internals.

Why agents benefit

• Writes contract-first FISH: The skill forces a function contract (inputs, globals, side effects) before any code, reducing the back-and-forth of malformed def/end blocks.
• Audits existing scripts: It runs scripts/audit_pfc5_fish.py to catch missing end statements, uninitialized locals, and callback leaks—errors agents normally miss when reading code.
• Ties to runtime probes: It builds minimal PFC5 runtime checks (history counters, object traversal guards) so the agent can prove a callback actually fired, not just assume it did.
• Manages state across restarts: The skill explicitly handles callback removal and reset on restore, a common source of silent bugs in long-running asphalt cases.
• Keeps histories documented: It enforces numbered history id outputs with schema comments, making post-processing and debugging tractable.

Practical scenarios

Auditing a legacy FISH script for a cyclic triaxial test

Your agent needs to verify whether a 400-line FISH script correctly stops at 2% axial strain. Using this skill, it maps the stop condition, identifies an unguarded global that changes between cycles, and suggests a history id for strain—then runs the audit script to confirm no syntax errors.

Adding a new servo-control callback to an asphalt rutting model

You need to apply a load only when the average stress in a zone group exceeds a threshold. The skill guides the agent to write a def with an explicit callback activation flag, initialize its counter, and tie a history id to the stress value. It then generates a short runtime probe to verify the callback fires and stops correctly.

Generating a FISH module for asphalt binder aging (time-step dependent)

The agent must output viscoelastic parameters at fixed timesteps. This skill ensures the history IDs are numbered sequentially, the output file schema is documented, and the stop logic triggers at the final step—no orphaned file handles or missing finish commands.

Add it to your agent workflow

npx skills add Echo-aloha/asphalt-codex-skills-5 --skill pfc5-fish

Then in an agent prompt, say: "Use the pfc5-fish skill to audit this FISH file for a PFC2D asphalt case, focusing on callback lifecycle and history ID consistency." The skill will load its workflow and references, guiding your agent through input gathering, audit, and probe generation. For a deeper overview, see the PFC5 FISH skill page.

Compare before adopting

• Quality signals: Check the GitHub repo for recent commits, open issues on PFC5-specific edge cases, and whether the audit script handles your PFC version (2D vs 3D).
• Maintenance freshness: The skill was last updated? Look for responsiveness to API changes in PFC 5.0 (e.g., new object methods).
• Alternatives: Consider generic code-review agents that don't understand FISH semantics—they'll catch syntax but not logical flaws like callback double-activation.
• Workflow fit: If your team already has a formal spec for FISH contracts, this skill aligns; if you write ad-hoc scripts, it may introduce overhead.

Why it is worth tracking

With 31 stars and a focus on asphalt-specific PFC5 cases, this skill fills a real niche: simulation scripting is high-stakes and under-served by general LLM skills. Its pattern-based audit script and explicit callback handling make it a reliable second pair of eyes for anything that touches FISH. Keep an eye on it if you're building agents that assist with geomechanical modeling—when PFC 6.0 grows, this skill's patterns will likely evolve, and early tracking gives you a head start on adapting your workflows. As more developers share FISH-related fixes, the skill's reference patterns will mature, making it a solid baseline for future simulation-adjacent agent skills.