From cbe2ca5746e256441f37117fbd1951df4119f49d Mon Sep 17 00:00:00 2001 From: AP3X Date: Wed, 10 Jun 2026 18:40:15 -0700 Subject: [PATCH] sharpen readme positioning --- README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 51 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index ae92664..3e249ef 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,58 @@ [![audit](https://github.com/AP3X-Dev/skill-jar/actions/workflows/audit.yml/badge.svg)](https://github.com/AP3X-Dev/skill-jar/actions/workflows/audit.yml) -A growing collection of **Agent Skills** — drop-in capabilities that teach an AI agent how to do a specific job well. Reach into the jar when you need one. +Skill Jar is an **agent skill operating system**: an installable library of +production-grade **Agent Skills** that teach coding agents how to debug, +review, refactor, test, research, and run safe autonomous loops. + +Not just reusable prompts. Not just Claude skills. It is an agent operations +layer: a growing set of executable disciplines for getting useful work out of +coding agents without giving up verification, state, or human control. + +## Start Here + +| If your repo... | Start with | Why | +|---|---|---| +| Is buggy | [**bug-pipeline**](development/bug-pipeline/SKILL.md) | Runs a Hunter -> Fixer -> Validator repair loop over evidence-backed defects. | +| Is messy after feature work | [**optimization-loop**](development/optimization-loop/SKILL.md) | Audits the codebase, builds a measurable backlog, and runs gated improvement cycles. | +| Needs its own recurring agent workflow | [**loop-engineer**](development/loop-engineer/SKILL.md) | Scaffolds the state files, role agents, gates, and driver prompts for a safe loop. | + +## How It Runs + +```mermaid +flowchart TD + A[User goal] --> B[Skill router] + B --> C[SKILL.md] + C --> D[Role agents] + D --> E[State files] + E --> F[Verification gate] + F --> G[Human review] +``` + +Skills turn fuzzy agent work into explicit operating contracts: what to do, what +not to do, which artifacts to update, which gates must pass, and where the human +still owns the decision. + +## Self-Hardening by Design + +Skill Jar contains the skill that improves Skill Jar. + +[**skill-forge**](development/skill-forge/SKILL.md) pressure-tests skills by +watching fresh agents fail, patching the loopholes they found, and re-running +until the behavior holds. This repo also dogfoods its own loop machinery: +`jar-audit` runs the deterministic gate, records state under `agent-state/`, +and requires a separate checker before work is marked complete. + +That makes the jar a self-hardening skill library: the operating procedures, the +role agents, the state files, and the audit gate all reinforce each other. ## What's an Agent Skill? -Each skill is a self-contained `SKILL.md` (plus any bundled resources) with frontmatter describing **when** to use it and instructions for **how**. Skills load on demand — the agent only reads one when the task actually matches, so the jar can grow without bloating context. The format is portable across any agent that supports skills. +Each skill is a self-contained `SKILL.md` (plus any bundled resources) with +frontmatter describing **when** to use it and instructions for **how**. Skills +load on demand — the agent only reads one when the task actually matches, so the +jar can grow without bloating context. The format is portable across any agent +that supports skills. ## Using a skill @@ -75,9 +122,9 @@ Reading this repo programmatically? Route from [`skills.json`](skills.json) — Development and systems-design skills also ship generated sub-agent packs in [`development/agents/`](development/agents/README.md) and [`systems-design/agents/`](systems-design/agents/README.md). Each pack's `manifest.json` is the source of truth; `python scripts/gen-agent-packs.py` renders copy-ready Claude Code and Codex agent files, and the audit gate verifies they stay in sync. Install only the roles a loop, panel, or design review actually needs. -## Self-hosted loop +## Self-Hosted Loop Details -The jar takes its own medicine. [loop-engineer](development/loop-engineer/SKILL.md) scaffolded a loop system into this very repo (state spine in `agent-state/`, role agents in `.claude/agents/`, drivers in `docs/prompts/`): +[loop-engineer](development/loop-engineer/SKILL.md) scaffolded a loop system into this very repo (state spine in `agent-state/`, role agents in `.claude/agents/`, drivers in `docs/prompts/`): - **jar-audit** — keeps the jar publish-ready. Discovery is a deterministic gate, `python scripts/audit-jar.py`: frontmatter parses, descriptions carry triggers, names match directories, every relative link resolves, scripts compile, the scaffolder stays idempotent. Red check → one fix per cycle, verified by a separate agent. - The repo also dogfoods the [**bug-pipeline**](development/bug-pipeline/SKILL.md) skill on itself — its instance lives in `.claude/agents/` + `docs/prompts/bug-pipeline-driver.md`, tracking to `agent-state/BUG_TRACKER.md`.