SkilledAgent

SkilledAgent is an always-active local developer workspace and workflow manager for AI coding agents like Claude Code and Gemini CLI. It provides 44 pre-configured skills, lightweight index references, and structured markdown workflows directly inside your repository.

Instead of letting an AI agent make assumptions, write unstructured code, or lose context across turns, SkilledAgent guides it through a persistent, repeatable development lifecycle: persistent prompt grilling, token-optimized index lookups, formal specifications, ticket-by-ticket implementation, test-driven development, and parallel code reviews.

The entire workspace lives inside a .agents/ directory. It does not pollute your root project configuration. You can remove it completely with a single command.

---

What's New in v1.1.0

• ⚡ Always-Active Persistent Agent: SkilledAgent stays active on EVERY user prompt to clear ambiguities, check spec alignment, present implementation options, and match skills before writing code.
• 💰 Token Optimization Engine (Save 80%+ Token Costs):
  • Lazy Skill Loading: Uses SKILLS_INDEX.md (1-line lookup) so agents don't parse heavy skill files during initial turns.
  • Stateful Summary Caching: Reads .agents/SUMMARY_INDEX.md for fast context recovery instead of re-scanning repository file trees.
  • Scoped Reading Directives: Enforces narrow line windowing (20-100 lines max) when reading files.
  • Strict 12k Ceiling: Caps all documentation files under 12k lines to prevent model degradation.
• 🎯 Updated kickoff Sequence: Big Decision Grilling (Why, Stack, Architecture, Constraints) now executes before wayfinder ticket mapping.
• 📦 Top 5 skills.sh Integrations: Includes frontend-design, vercel-react-best-practices, web-design-guidelines, webapp-testing, and api-design.
• 🔄 Incremental Ticket Loop: Implements features ticket-by-ticket with user verification, optional git commits after each ticket, and code reviews in clean context windows.

---

Quick Start

You can add SkilledAgent to any project directory in about 30 seconds.

1. Install the workspace

Run the package directly using npx to set up the workspace:

npx skilledagent

Or, to lock the version in your project dependencies:

npm i skilledagent

Both commands scaffold the complete .agents/ directory into your project.

2. Run the initial setup

Open your terminal AI agent (Claude Code, Gemini CLI, or similar) and run:

kickoff

---

The Kickoff Workflow (Updated Pipeline)

kickoff runs a 12-phase pipeline that takes a project from idea to test-driven production code.

Phase 0 — Project Scan

Lightweight scan of repo landscape using .agents/SUMMARY_INDEX.md to summarize existing stack, structure, and dependencies.

Phase 1 — User Vision Intake

The agent asks for your vision: what you want to build, priorities, and technical/non-technical details. It listens fully, then acts as a constructive critic (grill-me) to surface risks and alternative resolutions.

Phase 2 — Big Decision Grilling

Before mapping tickets, the agent grills you on foundational decisions: why the project exists, target stack, database, architecture, deployment, and constraints. Skill: grilling

Phase 3 — Wayfinder

With foundational decisions locked, the agent charts remaining unknowns and decision maps. Skill: wayfinder

Phase 4 — Code Review (optional)

Audits existing code for design alignment and standards before changes are introduced. Skill: code-review

Phase 5 — Deep Grilling

Interviews you on detailed edge cases, data handling, and concurrency, populating CONTEXT.md and ADRs. Skill: grill-with-docs

Phase 6 — Spec Synthesis

Compiles all decisions into .agents/ACTIVE_SPEC.md covering problem statement, architecture, testing, and explicit out-of-scope boundaries. Skill: to-spec

Phase 7 — Ticket Breakdown

Splits .agents/ACTIVE_SPEC.md into vertical-slice implementation tasks with explicit blocking edges. Skill: to-tickets

Phase 8 — Incremental Ticket Implementation Loop

Picks up tickets one by one, implements them test-first (tdd), asks for user verification, offers optional git commit per ticket, and runs code-review in a clean context window. Skills: implement + tdd + code-review

Phase 9 — Post-Implementation Review

Audits all new code against the spec and coding standards.

Phase 10 — Suggestions & Next Steps

Reports technical debt, UX polish, and performance optimization opportunities.

Phase 11 — Skill Catalog Tour

Explores the catalog of 44 available skills.

---

Directory Structure

Once installed, the .agents/ directory looks like this:

.agents/
  SKILLS_INDEX.md      # Fast 1-line token-optimized lookup table for all 44 skills
  SUMMARY_INDEX.md     # Compact index of codebase map, active spec, and ticket status
  ACTIVE_SPEC.md       # Single source of truth for active feature specification
  CONTEXT.md           # Shared memory: standards, ubiquitous domain language, ADRs
  AGENTS.MD            # Core rules, persistent prompt grilling protocol, skill routing
  skills/              # 44 reusable skills
  workflows/           # Orchestrated markdown workflows (kickoff)
  skills-lock.json     # Installed skills version lockfile

---

Available Skills (44 Catalog)

Frontend & Web Aesthetics (skills.sh Top Integrations)

Skill	What it does
frontend-design	Guidance on visual aesthetics, HSL color palettes, glassmorphism, and modern CSS
vercel-react-best-practices	40+ performance and architecture rules for React and Next.js
web-design-guidelines	Audits UI code against 100+ rules covering WCAG accessibility and UX
webapp-testing	Playwright end-to-end testing, visual regression testing, and assertion patterns

Architecture & API Design

Skill	What it does
api-design	RESTful/GraphQL API contracts, error schemas, and deep module boundaries
codebase-design	Vocabulary for deep, well-encapsulated modules with small interfaces
design-an-interface	Generates multiple interface designs for comparison
improve-codebase-architecture	Scans module coupling and generates interactive HTML reports

Planning & Routing

Skill	What it does
ask-matt	High-level router over the 44 skills
wayfinder	Maps decisions and unknowns for greenfield or foggy projects
grill-me	Stateless interactive interview to stress-test plans
grill-with-docs	Stateful interview saving decisions to CONTEXT.md & ADRs
to-spec	Synthesizes discussions into .agents/ACTIVE_SPEC.md
to-tickets	Breaks spec into vertical-slice implementation tasks
triage	State-machine triage role manager for issue trackers

Implementation & Quality

Skill	What it does
implement	Implements tasks using TDD and code review
tdd	Enforces strict Red-Green-Refactor test-first development
code-review	Two-axis review (Standards + Spec compliance)
diagnosing-bugs	Scientific diagnosis loop for hard bugs and performance regressions
prototype	Throwaway code to verify design ideas fast
research	Primary source research generating cited markdown reports
handoff	Compacts session context into markdown to fork into clean window

---

Removing SkilledAgent

To remove SkilledAgent, simply delete the .agents/ folder:

# Linux / macOS
rm -rf .agents

# Windows PowerShell
Remove-Item -Recurse -Force .agents

---

Publishing & Contributing

GitHub: github.com/AryanMotiani/SkilledAgent NPM: npmjs.com/package/skilledagent