samples: add pua skill — anti-pattern recovery procedure#305
Open
FMXExpress wants to merge 1 commit into
Open
Conversation
Port of tanweai/pua (MIT) -- a Claude Code skill that gives the
agent a concrete checklist for getting out of the five most common
"stuck loop" failure patterns:
1. Brute-force retry (same command, no new info, give up)
2. Blame-shifting (ask the user without reading the relevant
files / logs first)
3. Idle tools (have the capability, don't use it)
4. Busywork (rewrite the same function without reading callers
or tests)
5. Passive waiting (fix went green, never ran verification)
Port adaptations from the upstream:
* Tool-name mapping. PasClaw uses fs_grep / fs_read / shell_exec
/ execute_code / kb_search / memory_search / session_search /
web_search / tool_output_get; upstream targeted Claude Code's
bash + glob + grep. The skill's tool-skip table now lists the
PasClaw tools so the model doesn't have to translate.
* Drop the SessionStart / PostToolUse / UserPromptSubmit hooks.
Claude Code-specific machinery; PasClaw skills load on-demand
via fs_read when the model decides the trigger conditions
apply, which fits the agent-skills standard the rest of
PasClaw's catalogue uses (samples/skills/hello, picoclaw,
nanobot all share this shape).
* Drop the 14 "corporate flavour" personalities and the
/pua:p7..p10 role variants. The substance is the five-pattern
taxonomy + recovery checklists; the cosmetic skinning isn't
needed and adds tokens.
* Knowledge-only -- no `kind:` in the frontmatter, no callable
skill_pua tool. The model reads the body via fs_read when one
of the five trigger conditions self-applies. Matches the
upstream's "on-demand reference" intent; the upstream's
always-on hook injection is a different mechanism PasClaw
skills can't directly express anyway.
The trigger conditions are concrete enough that the model can
self-diagnose: same command twice with no new info between calls,
asking the operator before fs_grep'ing, a tool unused this turn
that would clearly apply, three rewrites of the same function
without reading callers, fix-without-verification.
Skill loads cleanly under `pasclaw skills list` -- the existing
loader recognises the knowledge-only shape (kind absent).
Credit + license attribution in the trailing "Credit" section
points at the upstream repo. MIT-licensed both sides.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 94d0e274d7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+62
to
+63
| - [ ] `kb_search` and `memory_search` for the same term — past | ||
| sessions may have hit and resolved this. |
There was a problem hiding this comment.
In a fresh or otherwise unindexed PasClaw install, RegisterKBTools intentionally does not register kb_search/kb_get when the knowledgebase has no sources, but this checklist still requires kb_search before asking any clarification. When this skill is installed in that common context, the model cannot complete the recovery procedure and may loop around an unavailable tool instead of escalating; please make the KB step conditional on the tool being present.
Useful? React with 👍 / 👎.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ports
tanweai/pua(MIT) as a PasClaw sample skill atsamples/skills/pua/SKILL.md. The upstream's framing is humorous; the substance is real — a five-pattern taxonomy of agent failure modes, each with a concrete recovery checklist.The five anti-patterns the skill addresses:
For each, the SKILL.md body has a short, concrete recovery procedure using PasClaw's tools.
Port choices
fs_grep/fs_read/shell_exec/execute_code/kb_search/memory_search/session_search/web_search/tool_output_get. Upstream targeted Claude Code'sbash/glob/grep. The skill's tool-skip table now lists the PasClaw tools.SessionStart/PostToolUse/UserPromptSubmit/PreCompacthooks for always-on injection. PasClaw skills load on-demand viafs_readwhen the model self-diagnoses the trigger conditions — same shape assamples/skills/hello, picoclaw, nanobot, and the rest of the agent-skills ecosystem./pua:p7..p10role variants. The substance is the five-pattern taxonomy; the cosmetic skinning adds tokens without changing behaviour.kind:in the frontmatter, noskill_puatool. The model reads the body when one of the five trigger conditions applies.Smoke test
shows
pua knowledge ~/workspace/skills/pua/SKILL.mdwith the full description rendered, so the existing skill loader picks it up with no changes.Files
Test plan
name+description, nokind)pasclaw skills listrecognises it as a knowledge-only skill~/.pasclaw/workspace/skills/, run a session that hits one of the five trigger conditions, verify the modelfs_reads the skill and applies the checklistCredit
Concept and the five-pattern taxonomy are from https://github.com/tanweai/pua, MIT-licensed. License is preserved via the trailing "Credit" section in the SKILL.md body.
Generated by Claude Code