# Skill Refinement Loop

> Use when a Pi skill receives a user correction, fails a test, produces unsafe/low-quality output, or should be improved from runtime feedback. Creates structured per-skill memory plus PATCH.md-style refinement proposals via skill_refinement_plan without mutating production skill behavior.

- **Type:** Skill
- **Install:** `agentstack add skill-firstp1ck-pi-coding-agent-forge-skill-refinement-loop`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Firstp1ck](https://agentstack.voostack.com/s/firstp1ck)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Firstp1ck](https://github.com/Firstp1ck)
- **Source:** https://github.com/Firstp1ck/pi-coding-agent-forge/tree/main/pi-package-skill-lifecycle/vendor/pi-skill-skill-refinement-loop/skills/skill-refinement-loop

## Install

```sh
agentstack add skill-firstp1ck-pi-coding-agent-forge-skill-refinement-loop
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Skill Refinement Loop

## When to use

Use this skill when the issue is with a **Pi skill or skill routing/workflow**, for example:

- The user says a skill should have behaved differently.
- A skill-specific test, routing fixture, or evaluator check fails.
- A skill omits required evidence, safety checks, verification, or citations.
- Runtime feedback reveals a reusable failure pattern worth preserving.

Do **not** use this for ordinary application bugs unless the bug is caused by a skill's instructions, scripts, routing, or validation behavior.

## Lifecycle policy

Before proposing production skill edits, enablement, pruning, publishing, or risky lifecycle changes, read the bundled package policy at `../../../../references/SKILL-LIFECYCLE-POLICY.md` when available.

## Critical implementation notes

The original MUSE task recommends Task 2 (per-skill memory tools) and Task 3 (skill evaluator) as dependencies. Those may not exist yet. This package deliberately handles that inconsistency with safe fallbacks:

- Per-skill memory is appended directly to `~/.pi/agent/memory/skills/.md`.
- `skill_eval_run` is treated as optional; include it in verification when available, otherwise use package tests plus hand-inspected routing checks.
- Production skill files are never edited by the tool. The tool writes a proposal file and memory only.

## Workflow

1. Identify the affected skill and the exact correction/failure.
2. Collect evidence: user quote, failing command/test output, prompt, file path, or observed behavior.
3. Call `skill_refinement_plan` with the skill name, failure, evidence, root-cause hypothesis if known, and a regression test proposal.
4. Review the generated PATCH.md-style proposal.
5. Add/update regression coverage if possible; if not possible, document why.
6. Run the skill evaluator if installed; otherwise run the package's tests and inspect routing/contract behavior by hand.
7. Apply source changes only after validation and user approval for risky edits.

## Tool usage

Prefer the tool for repeatable, structured output:

```text
skill_refinement_plan(
  skill="repo-explorer",
  failure="The skill should have used includeEvidence=true because exact code citations were requested.",
  evidence=["User correction after repo-explorer compact output omitted exact snippets."],
  rootCauseHypothesis="The workflow does not explicitly escalate includeEvidence when exact citations are requested.",
  patchSummary="Update repo-explorer SKILL.md to require includeEvidence=true for exact code citation requests.",
  regressionTest="Add a routing/contract fixture asserting citation-heavy prompts require includeEvidence=true."
)
```

By default the tool:

- Appends memory to `~/.pi/agent/memory/skills/.md`.
- Writes the proposal to a unique `/tmp/skill-refinement--.md` file.
- Refuses to overwrite an explicit `outputPath` unless `overwrite=true`.

Use `dryRun=true` to preview without writing files.

## Required proposal content

Every refinement plan should include:

- Evidence.
- Root cause hypothesis.
- Patch summary.
- Regression test proposal or explicit "not applicable" rationale.
- Verification steps.
- Safety note that production skill behavior is not changed automatically.

## Safety boundaries

- Do not edit `SKILL.md`, scripts, tests, or package metadata as part of refinement planning.
- Do not treat a generated proposal as approval to apply it.
- Ask before risky/destructive edits, publishing, package enablement, or changing global Pi runtime installs.
- Keep per-skill memory short and avoid secrets.

## Verification

After creating a plan, verify:

```bash
# Proposal exists and is reviewable
ls -l /tmp/skill-refinement-*.md

# Per-skill memory was appended
ls ~/.pi/agent/memory/skills

# If available
skill_eval_run /skills//SKILL.md
```

If `skill_eval_run` is unavailable, run the package's own tests (for example `npm test`, `bun test`, or package-specific mock tests) and inspect the skill's routing/workflow language by hand.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Firstp1ck](https://github.com/Firstp1ck)
- **Source:** [Firstp1ck/pi-coding-agent-forge](https://github.com/Firstp1ck/pi-coding-agent-forge)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-firstp1ck-pi-coding-agent-forge-skill-refinement-loop
- Seller: https://agentstack.voostack.com/s/firstp1ck
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.