agents-system
Treat the assigned repositories as one connected system. Design for an agent that must understand the domain, choose the correct action, observe its effects, recover from failure, and leave useful knowledge for the next task.
PaulRBerg · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add PaulRBerg/agent-skills --skill agents-systemAbout this skill
argument-hint: "[repo-path ...] [--dry-run]" disable-model-invocation: true name: agents-system skill-dependencies:
- codebase-design description: Redesign the assigned repository or repositories for agent understanding, control, and cumulative learning. Use when asked to make a system agent-intuitive, agent-ergonomic, or agent-accretive, then revise its design documents and plans.
Agents System
Treat the assigned repositories as one connected system. Design for an agent that must understand the domain, choose the correct action, observe its effects, recover from failure, and leave useful knowledge for the next task.
In this skill, the system means the repository or repositories the agent is tasked to work on. Agent means the coding agent operating those repositories. The project does not need to contain AI software.
Use these outcomes to judge improvements:
- Agent-intuitive: An agent can discover the system's purpose, vocabulary, structure, constraints, and authoritative evidence without guessing.
- Agent-ergonomic: An agent can inspect state, make a bounded change, verify the result, and recover with few steps and clear feedback.
- Agent-accretive: Completed work leaves verified knowledge and reusable capabilities that reduce the cost of later work. Obsolete knowledge is corrected or retired.
Optimize for correct results and low total resource cost across repeated tasks. Include context, tool calls, execution time, and future maintenance. Preserve the system's product goals, human usability, and required contracts.
Scope and Authority
User instructions take precedence over this skill's defaults. Apply established authorization without asking again.
- Use explicit repository paths when supplied. Otherwise, use the repositories assigned in the conversation, falling back to the current repository.
- Resolve paths and read each repository's applicable instructions. Treat unassigned dependencies as external systems. Record their contracts without adding their repositories to the write scope.
- By default, revise design documents, architecture decisions, implementation plans, and the context links needed to reach them. Record proposed code, tooling, schema, and infrastructure changes in those plans.
- Implement runtime changes only when the user's request or standing instructions also authorize them. Keep the documentation work complete and distinguish proposed behavior from implemented behavior.
- For an assessment-only request, Plan Mode, or
--dry-run, inspect and propose changes without editing repository files. Honor protected documents, generated-file ownership, coordination rules, and approval boundaries.
State the repository boundary, material assumptions, intended artifacts, and validation target before edits. Resolve discoverable facts yourself. Ask only when a missing user decision changes the outcome or prevents safe progress.
1. Establish the System Model
Inspect relevant sources before proposing a design. Start with repository entry points, design documents, active plans, manifests, task runners, representative code, and tests. Exclude dependencies, generated output, and caches from broad searches. Follow authoritative links and actual execution paths instead of reading every file indiscriminately.
Build one compact model that connects:
| Concern | Evidence to capture |
|---|---|
| Purpose | User outcomes, domain concepts, actors, and constraints that define correctness. |
| Structure | Repository and module responsibilities, interfaces, dependency direction, and ownership of invariants. |
| Behavior | Entry points, data and control flows, state transitions, persistence, and failure paths. |
| Operation | Available actions, prerequisites, side effects, status sources, validation, and recovery. |
| Knowledge | Authoritative documents, decisions, plans, generated copies, and how agents reach and update them. |
For multiple repositories, trace producer and consumer relationships across repository boundaries. Include shared contracts, version assumptions, release ordering, and the checks that prove compatibility when relevant.
Connect domain intent to workflows, interfaces, implementation, and verification. Explain what each abstraction hides, what it promises, and how it composes with adjacent abstractions. Represent real cycles and shared state explicitly. Do not force the system into a hierarchy that its behavior does not support.
Distinguish observed behavior, documented intent, and proposed behavior. Attach paths, symbols, or command evidence to material claims. Mark unresolved contradictions and unknowns explicitly.
2. Walk Through Agent Work
Choose representative tasks from the actual system. Cover a routine change, a failure and recovery path, and continuation by another agent when applicable. Trace each task through this loop:
- Find the goal, current state, applicable constraints, and authoritative source.
- Locate the smallest responsible interface and determine the change's effects on other parts of the system.
- Select an action whose inputs, side effects, and authorization are clear.
- Observe the result and run the check that establishes success.
- Recover from failure or partial completion.
- Preserve the decision or reusable procedure that the next agent would otherwise rediscover.
Record concrete friction: a hidden dependency, conflicting source, ambiguous name, opaque state, manual coordination, missing check, or repeated investigation. Identify the affected task and evidence for each finding. Do not infer a problem from file count, unfamiliar technology, or personal style alone.
Use the walkthroughs to evaluate the whole syst
Read the complete source ↗