agentleFS
valperevalpere/session-indexer/.claude/skills/improve/SKILL.md

improve

Skill42 starsChanged 4 months agoApache-2.0View on GitHub

Critique any plan, architecture decision, or implementation approach. Research-first — gives SHIP IT / IMPROVE IT / RETHINK IT / KILL IT verdict. Usage: /improve <topic>

70 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use deploy-platform, setup-platform and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • agno-agiSkill

    deploy-platform

    Deploy this AgentOS using its own provider instructions, configure JWT verification, and verify the public service. Use for first deployment, redeployment, or production configuration changes.

    Also in 4 projects that use this

  • agno-agiSkill

    setup-platform

    Set up this AgentOS from a fresh clone — confirm Docker, configure .env, boot the containers, prove the MCP endpoint live, connect the AgentOS UI, then build the user's first agent. Use when the user asks to set up the platform, get started, or bring this repo up on a new machine.

    Also in 4 projects that use this

  • MicrosoftSkill

    create-agent

    Create a new MCS2 Copilot Studio agent and PAC-connected local workspace with `pac copilot init`, then optionally add modern instructions, skills, tools, knowledge, and settings before synchronizing it. Use when the user asks to create, scaffold, initialize, or build a Copilot Studio agent.

    Also in 5 projects that use this

  • HeshamFSSkill

    loop

    Run a command or check on a recurring interval

    Also in 5 projects that use this

  • admin-remixSkill

    workspace

    Google Workspace administration - manage users, groups, email, Drive, calendars, and devices through natural conversation. Triggers on: Google Workspace, G Suite, user management, group management, admin tasks, offboarding, onboarding, email forwarding, Drive permissions, suspended users, organizational units, ChromeOS devices, audit logs, admin reports.

    Also in 3 projects that use this

  • AmirofcodesSkill

    goal

    Use when the user starts, manages, or asks about an OpenClaw goal mode with /goal. Enforces a bounded goal contract, visible progress blocks, proof requirements, stop conditions, and honest limitation language when no runtime goal-loop plugin is active.

    Also in 4 projects that use this

  • +3 more from agno-agi

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 4 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 68 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read CLAUDE.md for architecture constraints and conventions

    line 39
  2. Very specific:

    Read any proposal or decision files (.proposals.md, docs/architecture.md, ADRs)

    line 40
  3. Distinctive:

    Read the affected source files directly

    line 41
  4. Distinctive:

    External if needed: look for established patterns in the domain (official docs, RFCs, well-known library conventions).

    line 43
  5. Distinctive:

    If the subject has project-specific context (CLAUDE.md conventions, known constraints), apply it — don't critique things that are …

    line 118

“Common” is measured: kept by at least 6 in 10 of the 68 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Skill: /improve

Technical Design Critic

Research-first — never critique from zero.

subject → find best references → extract patterns → critique → verdict + fixes

When to run proactively

Suggest /improve when:

  • A design proposal is being elevated to active work
  • A new interface or API contract is being designed
  • A non-trivial architectural decision needs validation before implementation

Say: "This is new design — want me to run /improve on it before we build?"


Procedure

Step 1 — Understand the subject

  • What is it? (interface design, algorithm, API shape, data model, config structure)
  • What problem does it solve?
  • What's the current proposal?

Step 2 — Research

Internal first:

  • Read CLAUDE.md for architecture constraints and conventions
  • Read any proposal or decision files (.proposals.md, docs/architecture.md, ADRs)
  • Read the affected source files directly

External if needed: look for established patterns in the domain (official docs, RFCs, well-known library conventions). Reference specific sources — not vague "best practices."

Step 3 — Structured critique

3A — Architecture alignment

  • Does this respect the project's layer boundaries and separation of concerns?
  • Does it follow Dependency Inversion (interfaces defined near consumers)?
  • Does it introduce circular dependencies or tight coupling?

3B — Flaws and risks

  • What can go wrong?
  • Worst-case: data corruption, silent failure, resource leak, blocked request, security hole?
  • What assumptions are being made that could be wrong?

3C — Best-practice gap

  • How does this compare to established patterns in this domain?
  • What are production systems doing that this is missing?
  • What is being overengineered?

3D — Simplicity (YAGNI / KISS)

  • Can this be simpler?
  • What is the minimum viable version?
  • What can be cut without losing core value?

3E — Testability

  • Can this be tested in isolation (without real DB, external API, network)?
  • Are the interfaces narrow enough to mock easily?

3F — Security

  • Any user input reaching file paths, shell, or external calls unvalidated?
  • Any new configuration that could leak secrets?

Step 4 — Improvement proposals

For each issue found:

ISSUE     : [what's wrong or missing]
REFERENCE : [who does it better and how]
FIX       : [specific change to make]
IMPACT    : [what improves]
EFFORT    : Low / Medium / High

Step 5 — Verdict and score

DimensionScore (1–10)Notes
Architecture alignment
Correctness
Simplicity
Best-practice match
Testability
Security
Overall
  • SHIP IT (8+) — good enough, minor tweaks only
  • IMPROVE IT (5–7) — solid foundation, fix specific issues before building
  • RETHINK IT (3–4) — core approach has problems, consider alternatives
  • KILL IT (<3) — doesn't serve the goals, redirect energy elsewhere

Step 6 — Apply or propose

  • SHIP IT / IMPROVE IT → apply fixes directly.
  • RETHINK IT → present 2–3 alternatives with pros/cons and references.
  • KILL IT → explain clearly why; suggest where energy should go instead.

Rules

  • Research before critiquing. Opinions without references are noise.
  • Reference specific sources — "RFC 7231 §6.5" not "REST best practices."
  • Score honestly. Inflated scores waste time.
  • If the subject has project-specific context (CLAUDE.md conventions, known constraints), apply it — don't critique things that are intentional project decisions.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.