Local Development

Test changes to skills and agents locally before committing.

Quick Start

From the repo root:

# Set up local development symlinks
./scripts/dev-setup.sh

# Start Claude Code to test
claude

# Clean up when done
./scripts/dev-setup.sh --clean

How It Works

The dev-setup.sh script creates symlinks from your local repo to ~/.claude/:

~/.claude/
├── skills/
│   └── bigquery-etl-skills -> /path/to/repo/skills/
└── agents/
    └── etl-orchestrator.md -> /path/to/repo/agents/etl-orchestrator.md

Changes you make to skills or agents in the repo are immediately available in Claude Code sessions.

Testing Skills

After running dev-setup.sh:

Start a new Claude Code session: claude
Invoke a skill: /query-writer or /metadata-manager
Verify your changes work as expected
Iterate on the skill files and test again

No restart needed

Skills are loaded fresh each time they're invoked. You don't need to restart Claude Code after editing a skill.

Testing Agents

After running dev-setup.sh:

Start a new Claude Code session: claude
Give a task that would invoke the agent
The agent prompt is loaded when the Task tool spawns a subagent

Agent testing

Agents run as subagents via the Task tool. To test an agent directly, you can also paste its content into a conversation and give it a task.

Development Workflow

For skill changes

# 1. Set up (once)
./scripts/dev-setup.sh

# 2. Edit skill files
# skills/query-writer/skill.md
# skills/query-writer/references/*.md
# skills/query-writer/assets/*

# 3. Test in Claude Code
claude
# > /query-writer
# > [test your changes]

# 4. Iterate until satisfied

# 5. Clean up (optional - symlinks don't hurt)
./scripts/dev-setup.sh --clean

For agent changes

# 1. Set up (once)
./scripts/dev-setup.sh

# 2. Edit agent file
# agents/etl-orchestrator.md

# 3. Test in Claude Code
claude
# > Build a new table for user metrics...
# > [agent should be invoked]

# 4. Or test by pasting the prompt directly:
# > [paste agent prompt content]
# > ---
# > Build a new table for user metrics...

Cleanup

Remove symlinks when you're done testing:

./scripts/dev-setup.sh --clean

This removes only the symlinks created by the setup script, leaving other ~/.claude content intact.

Troubleshooting

Skills not appearing

Verify symlinks exist: ls -la ~/.claude/skills/
Start a new Claude Code session
Check for errors in setup: ./scripts/dev-setup.sh

Agent not being invoked

Agents are invoked automatically when appropriate tasks are given. To force-test an agent:

Copy the agent prompt content
Paste it at the start of a conversation
Give a task that matches the agent's purpose

Conflicts with installed plugin

If you have the plugin installed via marketplace AND local symlinks:

Local symlinks take precedence for agents (same filename)
Skills may conflict - uninstall the marketplace version during development:
```
/plugin uninstall bigquery-etl-skills
```
Re-install when done testing:
```
/plugin install bigquery-etl-skills
```

Team Workflow

When multiple team members are developing:

Each developer runs ./scripts/dev-setup.sh locally
Make changes on a feature branch
Test locally with Claude Code
Push and create PR
Reviewers can check out the branch and test with the same setup
Merge to main when approved
Plugin updates are available to all users on next sync