Agent skill

Srtd Dev

by t1mmen in t1mmen/srtd

Expert knowledge for developing the SRTD codebase itself. An agent skill from t1mmen/srtd.

MITAuto-check passedDatabases

Install Srtd Dev

skills CLI
$ npx skills add t1mmen/srtd --skill srtd-dev -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install t1mmen/srtd srtd-dev --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/t1mmen/srtd.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/srtd-dev .claude/skills/srtd-dev && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
srtd-dev
GitHub stars
105
Token cost
~2.3k tokens
SKILL.md length
419 words
Files
1
Skills in repo
3
Repo updated
First seen
Licence
MIT

At a glance

Expert knowledge for developing the SRTD codebase itself. An agent skill from t1mmen/srtd.

  • Works in 5 steps: Dual build logs: .buildlog.json (what… → Hash-based change detection: currentHash… → EventEmitter pattern: Loose coupling… → …
  • Implementing features
  • SKILL.md covers Quick Reference, Architecture Mental Model, Debugging Workflows and Testing Patterns, plus 4 more sections
  • Calls npm and npx

What it does

Srtd Dev is an agent skill from t1mmen/srtd. Expert knowledge for developing the SRTD codebase itself. Use when implementing features, fixing bugs, understanding architecture, or writing tests for SRTD internals. NOT for end users of srtd CLI.

Its SKILL.md is about 2.3k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Databases. It works with Supabase, SQL and PostgreSQL. The repository describes itself as: 🪄 Supabase migrations made magical: Live-reloading SQL + Sane, reviewable diffs + Maintainable templates = Delightful DX. The licence is MIT.

When your agent uses it

  • Implementing features
  • Understanding architecture
  • Writing tests for SRTD internals

Example prompts

  • “/srtd-dev”

Requirements

  • Node.js

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

  1. Dual build logs: .buildlog.json (what was built, commit) + .buildlog.local.json (what was applied, gitignore)
  2. Hash-based change detection: currentHash !== lastAppliedHash && currentHash !== lastBuiltHash
  3. EventEmitter pattern: Loose coupling between services
  4. Disposable pattern: await using for automatic cleanup
  5. Queue-based processing: FIFO with recheck for modified templates

What it can do on your machine

Read from SKILL.md and the folder at commit 271b138. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • npm
    • npx

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use npm and npx, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Srtd Dev loads about 2.3k tokens when it runs. Until then it costs about 52 tokens; SKILL.md has 419 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~52
When it runs · the whole SKILL.md, loaded when a task matches
~2.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from t1mmen/srtd at commit 271b138, republished under its MIT licence (© t1mmen). 419 words, ~2,296 tokens.

Download SKILL.mdSave it as .claude/skills/srtd-dev/SKILL.md (or your agent's skills folder).
name
srtd-dev
description
Expert knowledge for developing the SRTD codebase itself. Use when implementing features, fixing bugs, understanding architecture, or writing tests for SRTD internals. NOT for end users of srtd CLI.

SRTD Development Skill

Expert guidance for working with the SRTD codebase - a CLI tool for live-reloading SQL templates into Supabase local databases.

Quick Reference

Key Commands
bash
npm test                           # Run all tests
npx vitest run -t "pattern"        # Run specific test
npm run typecheck                  # Type check
npm run lint                       # Biome lint + fix
npm start -- watch                 # Run watch command
npm run supabase:start             # Start test database
Key Files by Task
TaskPrimary Files
Add CLI optionsrc/commands/{command}.ts, src/cli.ts
Modify template processingsrc/services/Orchestrator.ts
Change state trackingsrc/services/StateService.ts
Fix database issuessrc/services/DatabaseService.ts
Modify migration outputsrc/services/MigrationBuilder.ts
Change file watchingsrc/services/FileSystemService.ts
Update configsrc/utils/config.ts, src/types.ts

Architecture Mental Model

Unidirectional flow - data flows one direction through the system:

File Change → FileSystemService → Orchestrator → StateService
                                       ↓
                              DatabaseService / MigrationBuilder
                                       ↓
                              StateService (update) → Event Emission
Service Boundaries (Critical)

FileSystemService owns:

  • Template discovery (glob matching)
  • File watching (Chokidar, 100ms debounce)
  • File I/O (read, write, rename)
  • Hash computation (MD5)

StateService owns:

  • All state mutations (single source of truth)
  • Build log persistence (.buildlog.json, .buildlog.local.json)
  • State machine transitions (UNSEEN → CHANGED → APPLIED/BUILT → SYNCED)
  • Hash comparison for change detection

DatabaseService owns:

  • Connection pooling (pg.Pool, max 10 connections)
  • Retry logic (3 attempts, exponential backoff)
  • Error categorization (CONNECTION_ERROR, SYNTAX_ERROR, etc.)
  • Transaction management (BEGIN/COMMIT/ROLLBACK)
  • Advisory locks per template

MigrationBuilder owns:

  • Timestamp generation (increments from buildLog.lastTimestamp)
  • Migration file formatting (banner, footer, transaction wrap)
  • Bundle mode (multiple templates → single file)

Orchestrator owns:

  • Service coordination (does NOT own state)
  • Queue management (processQueue, pendingRecheck)
  • Event emission (templateChanged, templateApplied, templateError)
  • Command execution (apply, build, watch)
Key Design Decisions
  1. Dual build logs: .buildlog.json (what was built, commit) + .buildlog.local.json (what was applied, gitignore)
  2. Hash-based change detection: currentHash !== lastAppliedHash && currentHash !== lastBuiltHash
  3. EventEmitter pattern: Loose coupling between services
  4. Disposable pattern: await using for automatic cleanup
  5. Queue-based processing: FIFO with recheck for modified templates

Debugging Workflows

Template Not Processing
typescript
// Check 1: Is template being found?
// FileSystemService.findTemplates() uses glob pattern from config.filter

// Check 2: Is hash comparison returning false?
// StateService.hasTemplateChanged() compares against BOTH build logs

// Check 3: Is it a WIP template?
// isWipTemplate() checks for config.wipIndicator suffix (.wip.sql)

// Debugging: Add to Orchestrator.processTemplate():
console.log({
  path,
  hash: currentHash,
  state: this.stateService.getTemplateStatus(path)
});
Database Connection Errors
typescript
// DatabaseService categorizes errors via DatabaseErrorType:
// - CONNECTION_ERROR: ECONNREFUSED, ENOTFOUND, ECONNRESET
// - POOL_EXHAUSTED: "pool is exhausted", "too many clients"
// - TIMEOUT_ERROR: ETIMEOUT or timeout in message

// Check pool status:
console.log({
  total: pool.totalCount,
  idle: pool.idleCount,
  waiting: pool.waitingCount
});
State Machine Issues
typescript
// Valid transitions in StateService:
// UNSEEN → CHANGED
// CHANGED → APPLIED, BUILT, ERROR
// APPLIED → CHANGED, SYNCED
// BUILT → CHANGED, SYNCED
// SYNCED → CHANGED
// ERROR → CHANGED

// Check current state:
const info = stateService.templateStates.get(absolutePath);
console.log({ state: info?.state, lastAppliedHash, lastBuiltHash });

Testing Patterns

Show full SKILL.md (167 more words)Show less
Command Tests
typescript
import { setupCommandTestSpies, createMockUiModule } from '../helpers/testUtils.js';

beforeEach(() => {
  vi.clearAllMocks();
  vi.resetModules();  // Critical: reload modules
  spies = setupCommandTestSpies();
});

afterEach(() => spies.cleanup());

it('handles success', async () => {
  const { buildCommand } = await import('../commands/build.js');
  mockOrchestrator.build.mockResolvedValue({ built: ['file.sql'], errors: [] });

  await buildCommand.parseAsync(['node', 'test']);

  spies.assertNoStderr();  // Catch Commander parse errors
  expect(spies.exitSpy).toHaveBeenCalledWith(0);
});
Service Tests with TestResource
typescript
import { createTestResource } from '../helpers/index.js';

it('applies template to database', async () => {
  using resources = await createTestResource({ prefix: 'apply' });
  await resources.setup();

  // Create template with unique function name
  const templatePath = await resources.createTemplateWithFunc('test', '_v1');

  // Execute within transaction for isolation
  const result = await resources.withTransaction(async (client) => {
    // ... test logic
    return client.query('SELECT ...');
  });

  // Verify function exists
  expect(await resources.verifyFunctionExists()).toBe(true);
  // Auto-cleanup via Symbol.asyncDispose
});
Mock Patterns
typescript
// Mock Orchestrator (most common)
vi.mock('../services/Orchestrator.js', () => ({
  Orchestrator: {
    create: vi.fn().mockResolvedValue({
      apply: vi.fn().mockResolvedValue({ applied: [], errors: [], skipped: [] }),
      build: vi.fn().mockResolvedValue({ built: [], errors: [], skipped: [] }),
      watch: vi.fn().mockResolvedValue(undefined),
      [Symbol.asyncDispose]: vi.fn(),
    }),
  },
}));

// Mock config
vi.mock('../utils/config.js', () => ({
  getConfig: vi.fn().mockResolvedValue({
    templateDir: '/tmp/templates',
    migrationDir: '/tmp/migrations',
    // ... other config
  }),
}));

Adding New Features

New CLI Option
  1. Add option to command in src/commands/{command}.ts:
typescript
.option('-x, --example', 'Description')
  1. Pass to orchestrator method:
typescript
const result = await orchestrator.apply({ force, example: options.example });
  1. Handle in orchestrator:
typescript
async apply(options: ApplyOptions & { example?: boolean }) {
  if (options.example) { /* ... */ }
}
  1. Add test:
typescript
it('respects --example flag', async () => {
  await command.parseAsync(['node', 'test', '--example']);
  expect(mockOrchestrator.apply).toHaveBeenCalledWith(
    expect.objectContaining({ example: true })
  );
});
New Service Method
  1. Define interface in src/types.ts
  2. Implement in service class
  3. Expose via Orchestrator if needed
  4. Add unit test for service
  5. Add integration test for full flow
New Event Type
  1. Define event type in Orchestrator:
typescript
type OrchestratorEvents = {
  newEvent: [payload: NewEventPayload];
  // ... existing events
};
  1. Emit from appropriate location:
typescript
this.emit('newEvent', payload);
  1. Listen in command:
typescript
orchestrator.on('newEvent', (payload) => {
  // Update UI
});

Error Handling Patterns

Service Layer
typescript
// Categorize and wrap errors
try {
  await pool.query(sql);
} catch (error) {
  const dbError = this.categorizeError(error);
  this.emit('sql:error', { error: dbError });
  throw dbError;
}
Command Layer
typescript
try {
  const result = await orchestrator.apply();
  process.exit(result.errors.length > 0 ? 1 : 0);
} catch (error) {
  console.log(chalk.red(getErrorMessage(error)));
  process.exit(1);
}
Interactive Commands
typescript
try {
  const answer = await select({ /* ... */ });
} catch (error) {
  if (isPromptExit(error)) {
    process.exit(0);  // Ctrl+C is clean exit
  }
  throw error;
}

Common Pitfalls

  1. Forgetting vi.resetModules() - Command tests fail silently without it
  2. Not capturing console.error - Commander writes parse errors to stderr
  3. Direct state mutation - Always use StateService methods, never modify directly
  4. Missing transaction cleanup - Use using pattern or explicit dispose
  5. Testing with shared state - Use TestResource for isolation
  6. Forgetting Symbol.asyncDispose - Orchestrator requires async disposal

Validation Before Commit

bash
npm run typecheck && npm run lint && npm test

All three must pass. CI runs on Node 20.x and 22.x with PostgreSQL 15.

© t1mmen, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .claude/skills/srtd-dev of t1mmen/srtd.

Open the folder on GitHubat commit 271b138

Compare with similar skills

Srtd Dev next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Srtd Dev compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Srtd Dev this skillt1mmen/srtd105—~2.3kAutomated safety check: PassMIT
Clickhouse Logs Queriessupabase/supabase111k—~2.4kAutomated safety check: PassApache-2.0
Safe SQL Executionsupabase/supabase111k—~4.2kAutomated safety check: PassApache-2.0
Take Doc Screenshotspgplex/pgconsole155—~841Automated safety check: PassApache-2.0
Expert DatabaseReJeCtAll/ExpertTeam-Codex113—~692Automated safety check: PassMIT
DB Migratealexeykrol/claude-code-starter194—~405Automated safety check: NotesNone

Similar skills

  • Clickhouse Logs Queries

    supabase/supabase

    Official

    Write, review, and migrate Supabase logs queries against the ClickHouse-backed logs table (the logs.all.otel analytics endpoint).

    111k GitHub stars~2.4k tokensUpdated today
    DatabasesAuto-check passed
  • Safe SQL Execution

    supabase/supabase

    Official

    A skill your agent uses whenever code will build, return, fetch, or execute SQL that runs against a user's real Postgres database — even when the request reads like an ordinary feature or bug fix…

    111k GitHub stars~4.2k tokensUpdated today
    DatabasesAuto-check passed
  • Take Doc Screenshots

    pgplex/pgconsole

    Take screenshots of the running pgconsole app for documentation.

    155 GitHub stars~841 tokensUpdated 1 mo ago
    DatabasesAuto-check passed
  • Expert Database

    ReJeCtAll/ExpertTeam-Codex

    数据库优化专家入口。用于 Codex CLI 的 $expert-database 调用. An agent skill from ReJeCtAll/ExpertTeam-Codex.

    113 GitHub stars~692 tokensUpdated 3 mo ago
    DatabasesAuto-check passed
  • DB Migrate

    alexeykrol/claude-code-starter

    Миграция схемы базы данных: SQLite → PostgreSQL/Supabase. An agent skill from alexeykrol/claude-code-starter.

    194 GitHub stars~405 tokensUpdated 2 mo ago
    DatabasesAuto-check: notes
  • Connects an existing, externally owned Postgres/MySQL database to a Lunora app through Cloudflare Hyperdrive.

    283 GitHub stars~1.8k tokensUpdated today
    DatabasesAuto-check passed

More from t1mmen/srtd

  • Srtd CLI

    t1mmen/srtd

    This skill should be used when the user mentions "srtd", "sql templates", "migrations-templates", "live reload sql", "supabase functions", when working with files in supabase/migrations-templates/…

    105 GitHub stars~360 tokensUpdated 1 mo ago
    Auto-check passed
  • Structured code review workflow for SRTD development. An agent skill from t1mmen/srtd.

    105 GitHub stars~807 tokensUpdated 1 mo ago
    Auto-check passed

Questions about Srtd Dev

What does Srtd Dev do?

Expert knowledge for developing the SRTD codebase itself. An agent skill from t1mmen/srtd. Srtd Dev is an agent skill from t1mmen/srtd. Expert knowledge for developing the SRTD codebase itself.

When should I use Srtd Dev?

Srtd Dev fits situations like: implementing features; understanding architecture; writing tests for SRTD internals.

How do I install Srtd Dev in Claude Code?

Run `npx skills add t1mmen/srtd --skill srtd-dev -a claude-code`. Or copy the skill folder (.claude/skills/srtd-dev in t1mmen/srtd) into .claude/skills/srtd-dev in your project. Claude Code loads it when a task matches its description.

How do I install Srtd Dev in Codex?

Run `npx skills add t1mmen/srtd --skill srtd-dev -a codex`. Or copy the skill folder (.claude/skills/srtd-dev in t1mmen/srtd) into .agents/skills/srtd-dev in your project. Codex loads it when a task matches its description.

Can I use Srtd Dev in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add t1mmen/srtd --skill srtd-dev -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/srtd-dev, .gemini/skills/srtd-dev, .github/skills/srtd-dev and .opencode/skills/srtd-dev in your project.

What does Srtd Dev need to run?

Going by SKILL.md and its folder, Srtd Dev needs the command-line tools its instructions call (npm and npx). Our summary lists: Node.js.

Does Srtd Dev access the network?

SKILL.md contains no URLs. Its commands use npm and npx, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Srtd Dev safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Srtd Dev use?

Srtd Dev is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Srtd Dev use?

About 2.3k tokens (SKILL.md is roughly 9.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Srtd Dev?

Skills that share tags, products or a category with Srtd Dev: Clickhouse Logs Queries (supabase/supabase, 111k stars), Safe SQL Execution (supabase/supabase, 111k stars), Take Doc Screenshots (pgplex/pgconsole, 155 stars) and Expert Database (ReJeCtAll/ExpertTeam-Codex, 113 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Srtd Dev?

t1mmen (a GitHub user) maintains it in t1mmen/srtd, which has 105 GitHub stars. The repository holds 3 skills in this directory. The repository was last updated on September 5, 2026.

Source: t1mmen/srtd on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.