diff --git a/GETTING-STARTED.md b/GETTING-STARTED.md index fe03a63..fa8569a 100644 --- a/GETTING-STARTED.md +++ b/GETTING-STARTED.md @@ -152,20 +152,27 @@ always-on, but covers most situations. ## Step 4: Create your first personal skill (15 minutes) Skills transform Claude Code from "general AI assistant" into -"my assistant that knows how I work." You do not write skill -files by hand. You describe what you need and let Claude create -the file with the correct format. +"my assistant that knows how I work." You use the **plugin-dev** +plugin to create them. It handles the file format, YAML +frontmatter, description quality, and file placement. + +If you do not have plugin-dev installed: +``` +/install plugin-dev +``` ### How it works -Tell Claude what you want the skill to do. It creates the file -with proper YAML frontmatter (required for Claude Code to -recognize it as a skill) and markdown body. +Run `/skill-development` and describe what you need. The guided +workflow creates the skill file with proper structure. You never +need to write skill files by hand. ### Example: Weekly status report ``` -Create a skill called "weekly-status" that generates my weekly +/skill-development + +I need a skill called "weekly-status" that generates my weekly status report. It should: 1. Read CLAUDE.md for current priorities 2. Check git log for this week's activity @@ -173,21 +180,21 @@ status report. It should: 4. Write a concise report: what was completed, what is in progress, what is blocked, plan for next week Format: bullet points, under 300 words, lead with wins. -Save it to .claude/skills/weekly-status.md ``` -Claude creates the file. Now you can run `/weekly-status` every -Monday morning. Or text "Run /weekly-status" from your phone. +The plugin creates the file. Now you can run `/weekly-status` +every Monday morning. Or text "Run /weekly-status" from your phone. ### Example: Research and save ``` -Create a skill called "deep-research" that researches a given +/skill-development + +I need a skill called "deep-research" that researches a given topic thoroughly. It should search the web, cross-reference claims across sources, and write a structured summary to research/[topic-slug]-[date].md with key findings, details, what could not be verified, and source URLs. -Save it to .claude/skills/deep-research.md ``` ### Example: Daily briefing @@ -213,6 +220,10 @@ each section at 3 bullets and total output at 200 words. Claude updates the skill file. Run it again. Most skills take 2-3 iterations to produce output you are happy with. +After iterating, run `/skill-reviewer` to check quality. It catches +common issues: vague descriptions that will not trigger correctly, +missing edge cases, and structural problems. + ### When to create a skill A skill is worth creating when you: @@ -233,8 +244,9 @@ Start with 1-2 skills. Add more as you notice patterns. ## Step 5: Add your tools via MCP (15 minutes per tool) MCP servers connect Claude Code to external services. -The repo includes Playwright (browser). Here are the most -useful ones to add: +The repo includes Playwright (browser). Use `/mcp-integration` +from the plugin-dev plugin for guided setup of new servers. +Or add them manually: ### Slack (post messages, read channels) diff --git a/examples/14-build-your-agent/prompt.md b/examples/14-build-your-agent/prompt.md index 83ddc11..8b4735d 100644 --- a/examples/14-build-your-agent/prompt.md +++ b/examples/14-build-your-agent/prompt.md @@ -18,9 +18,15 @@ add safety guardrails, and test it on real work from your actual week. **Time needed:** 90 minutes for the full build. You will iterate on it over the first week. Most people say it clicks around day 3. -**What you need:** A project directory (new or existing) where you -will set up your personal agent system. Everything you build here -is portable. Move it to any project later. +**What you need:** +- A project directory (new or existing) where you will set up your + personal agent system. Everything you build here is portable. +- The **plugin-dev** plugin installed in Claude Code. This is the + tool that creates skills, agents, and hooks with correct structure + and best practices. If you do not have it: + ``` + /install plugin-dev + ``` --- @@ -144,16 +150,25 @@ Every agent you create in Phase 3 inherits this context automatically. ## Phase 3: Create your agent team (20 minutes) -Now build the 2-3 agents you identified in Phase 1. You do not write -agent files by hand. You tell Claude what each agent should do and -let it create the files. +Now build the 2-3 agents you identified in Phase 1. You use the +**plugin-dev** plugin to create them. It knows the correct file +format, frontmatter fields, system prompt structure, and triggering +conditions. You describe what you need; it builds the agent properly. ### Create your first agent -Pick the role you need most. Tell Claude: +Pick the role you need most. Run: ``` -Create an agent called "[role-name]" that [what it does]. +/agent-development +``` + +The plugin-dev skill will guide you through creating the agent: +what it does, what tools it needs, when it should trigger, and +what its system prompt should contain. Describe your agent clearly: + +``` +I need an agent called "[role-name]" that [what it does]. It should: - [Specific capability 1] @@ -163,67 +178,75 @@ It should: It should NOT: - [Boundary 1] - [Boundary 2] - -Save it to .claude/agents/[role-name].md ``` +The plugin creates the file in `.claude/agents/` with proper +frontmatter (name, description, model hint, tools) and a focused +system prompt. + **Concrete examples for three different people:** A marketing manager might say: ``` -Create an agent called "market-scanner" that monitors competitor +/agent-development + +I need an agent called "market-scanner" that monitors competitor activity. It should search the web for news about [competitor names], extract pricing changes, new feature launches, and partnership announcements. It should produce a structured report with source URLs for every claim. It should not include rumors or unverified information. -Save it to .claude/agents/market-scanner.md ``` An engineering lead might say: ``` -Create an agent called "tech-researcher" that evaluates technologies +/agent-development + +I need an agent called "tech-researcher" that evaluates technologies for our stack. It should search documentation and GitHub repos, compare features, check community health (stars, issues, release frequency), and produce a recommendation with pros, cons, and risks. It should not recommend anything without checking the last 3 months of GitHub issues -for dealbreakers. Save it to .claude/agents/tech-researcher.md +for dealbreakers. ``` A consultant might say: ``` -Create an agent called "client-briefer" that prepares meeting briefs. +/agent-development + +I need an agent called "client-briefer" that prepares meeting briefs. It should research the client's company (recent news, financials, leadership changes), review my notes in memory/, and produce a one-page briefing with talking points and potential questions they will ask. It should not include anything I cannot verify in the -meeting. Save it to .claude/agents/client-briefer.md +meeting. ``` ### Create your second agent -Every good system needs a quality gate. Create a reviewer: +Every good system needs a quality gate. Run `/agent-development` +again for a reviewer: ``` -Create an agent called "[domain]-reviewer" that reviews output from +I need an agent called "[domain]-reviewer" that reviews output from my other agents. It should check for: - [Your specific accuracy requirements] - [Your formatting standards] - [Common mistakes in your domain] When it finds issues, it should list them with specific fix -instructions, not vague feedback. Save it to .claude/agents/[name].md +instructions, not vague feedback. ``` ### Create your third agent (optional but powerful) A writer/formatter that takes raw output and shapes it for your -audience: +audience. Run `/agent-development`: ``` -Create an agent called "[output]-writer" that transforms research +I need an agent called "[output]-writer" that transforms research and analysis into [format your audience expects]. It should follow [your organization's style/tone]. It should be concise: [your word -limit]. Save it to .claude/agents/[name].md +limit]. ``` ### Test each agent individually @@ -253,10 +276,15 @@ handles a complete workflow. ### Create the pipeline skill -Tell Claude to create a skill that orchestrates your agents: +Run `/skill-development` to create the pipeline skill. This is more +complex than a simple task skill because it orchestrates multiple +agents, so the plugin-dev guided workflow helps you get the +frontmatter, description, and triggering conditions right. + +Describe your pipeline: ``` -Create a skill called "weekly-[your-workflow]" that runs my complete +I need a skill called "weekly-[your-workflow]" that runs my complete [task name] workflow. Steps: @@ -269,14 +297,18 @@ Steps: 7. Save the final output to pipeline-output/[your-output]-[date].md 8. Update memory/[your-state-file].md with what was done and when 9. Show me the first 10 lines of the output to confirm - -Save it to .claude/skills/weekly-[your-workflow].md ``` +After the skill is created, run `/skill-reviewer` to check its +quality. The reviewer catches common issues: vague descriptions, +missing triggering conditions, incomplete step definitions. + **Concrete example for a marketing manager:** ``` -Create a skill called "weekly-competitive-intel" that runs my +/skill-development + +I need a skill called "weekly-competitive-intel" that runs my Monday morning competitive intelligence workflow. Steps: @@ -295,8 +327,6 @@ Steps: 8. Update memory/competitive-intel-state.md with today's date and what was found 9. Show me the executive summary - -Save it to .claude/skills/weekly-competitive-intel.md ``` ### Test the pipeline @@ -338,24 +368,34 @@ set up the guardrails you identified in Phase 1. ### Create your custom hooks -Tell Claude to create hooks for your specific risks: +Run `/hook-development` for each hook. The plugin-dev guided workflow +handles the hook event type (PreToolUse, PostToolUse), the matching +logic, registration in settings.json, and testing. + +**For blocking dangerous commands:** ``` -Create a PreToolUse hook that blocks Bash commands containing any of: +/hook-development + +I need a PreToolUse hook that blocks Bash commands containing: - [pattern 1: e.g., "rm -rf", "DROP TABLE"] -- [pattern 2: e.g., commands targeting your production directories] +- [pattern 2: e.g., commands targeting my production directories] - [pattern 3: e.g., curl commands with API tokens in arguments] - -Save to hooks/[your-hook-name].sh and register it in -.claude/settings.json ``` +**For audit logging:** + ``` -Create a PostToolUse hook that logs every tool call to -hooks/audit.log with timestamp, tool name, and a summary of what -was done. Save to hooks/audit-logger.sh and register it. +/hook-development + +I need a PostToolUse hook that logs every tool call to +hooks/audit.log with timestamp, tool name, and a summary of +what was done. ``` +The plugin creates the shell scripts and registers them in +`.claude/settings.json` so they run on every tool call. + ### Verify the hooks work ``` @@ -502,21 +542,32 @@ whether this changed how you work. ## Growing from here -**More agents.** As you notice new recurring patterns, create agents -for them. Each agent you add is a building block that any pipeline -skill can use. +**More agents.** As you notice new recurring patterns, run +`/agent-development` to create agents for them. Each agent you add +is a building block that any pipeline skill can use. Run +`/skill-reviewer` on existing agents periodically to catch quality +drift. **More pipelines.** A pipeline is just a skill that calls agents in -sequence. Once you have 3-4 agents, creating a new pipeline for a -different workflow takes minutes. +sequence. Run `/skill-development` to create new pipelines. Once you +have 3-4 agents, creating a new pipeline for a different workflow +takes minutes. **More integrations.** MCP servers connect your agents to external -services: Slack, Google Drive, databases, APIs. Each integration -multiplies what your pipelines can do without manual data gathering. +services: Slack, Google Drive, databases, APIs. Run +`/mcp-integration` to add new servers with correct configuration. +Each integration multiplies what your pipelines can do without +manual data gathering. **Tighter security.** As automation increases, so should guardrails. -Add domain-specific hook patterns. Review audit logs. Set up alerts -for blocked actions that might indicate a prompt going wrong. +Run `/hook-development` to add domain-specific hook patterns. Review +audit logs. Set up alerts for blocked actions that might indicate a +prompt going wrong. + +**Validate your setup.** Run `/plugin-validator` periodically to +check that all your files have correct structure, frontmatter, and +cross-references. Catches problems before they cause silent failures +in automated runs. **Shared agents.** The agents and pipelines you build are markdown files. You can share them with colleagues, version control them, or