writing-agents

Name: writing-agents
Author: aaddrick

120stars16forks

How to install writing-agents?

aaddrick/claude-pipeline/writing-agents

$npx -y skills add aaddrick/claude-pipeline --skill writing-agents

Installs into the current project.

Summary

Use when creating new agents, editing existing agents, or defining specialized subagent roles for the Task tool

Files · 1

View on GitHub

SKILL.md

1	# Writing Agents
2
3	## Overview
4
5	Writing agents IS Test-Driven Development applied to role definitions.
6
7	Agents are specialized subagents invoked via the Task tool. They receive full conversation context and execute autonomously with a defined persona, tools, and behavioral guidelines.
8
9	Core principle: If you didn't test the agent on representative tasks, you don't know if it performs correctly.
10
11	REQUIRED BACKGROUND: Understand test-driven-development and writing-skills before using this skill. Same RED-GREEN-REFACTOR cycle applies.
12
13	## Agents vs Skills
14
15	\| Aspect \| Agents \| Skills \|
16	\|--------\|--------\|--------\|
17	\| Invocation \| Task tool with `subagent_type` \| Skill tool with skill name \|
18	\| Context \| Full conversation history \| Loaded on-demand \|
19	\| Execution \| Autonomous, multi-turn \| Single response guidance \|
20	\| Persona \| Explicit role/identity \| Reference documentation \|
21	\| Location \| `.claude/agents/` \| `.claude/skills/` \|
22	\| Use for \| Complex, autonomous tasks \| Reusable patterns/techniques \|
23
24	## Agent File Structure
25
26	Agents are PROJECT-LEVEL. They live in the project's `.claude/agents/` directory, not personal directories.
27
28	```
29	.claude/agents/
30	agent-name.md # Single file with frontmatter + persona
31	```
32
33	Frontmatter (YAML):
34	```yaml
35	---
36	name: agent-name
37	description: Role description. Use for [specific task types].
38	model: opus # Optional: opus, sonnet, haiku (defaults to parent)
39	---
40	```
41
42	IMPORTANT: After creating or modifying an agent, prompt the user to restart their Claude Code session. Agents are loaded at session start and won't be available until restart.
43
44	## Agent Creation Workflow
45
46	Before writing the agent, gather domain knowledge and project context:
47
48	### Step 1: Research Domain Best Practices
49
50	Use WebSearch to find domain-specific guidance. Search for:
51	- Best practices for [domain] development
52	- Common [domain] mistakes/anti-patterns
53	- [Domain] code review checklist
54	- [Technology] security considerations
55
56	Example searches by domain:
57	```
58	# Laravel backend agent
59	"Laravel best practices 2026"
60	"Laravel anti-patterns to avoid"
61	"Eloquent ORM performance mistakes"
62	"PHP security vulnerabilities OWASP"
63
64	# React frontend agent
65	"React component best practices 2026"
66	"React performance anti-patterns"
67	"React accessibility checklist"
68
69	# DevOps/infrastructure agent
70	"AWS Lambda best practices"
71	"Infrastructure as Code anti-patterns"
72	"Cloud security common mistakes"
73
74	# Database agent
75	"PostgreSQL query optimization"
76	"Database schema anti-patterns"
77	"SQL injection prevention"
78	```
79
80	Incorporate findings into:
81	- Anti-patterns section (domain-specific mistakes)
82	- Best practices (positive patterns to follow)
83	- Security considerations (if applicable)
84
85	### Step 2: Gather Codebase Context
86
87	Explore the project to make the agent project-specific:
88
89	1. Read CLAUDE.md and README.md for project conventions
90	2. Identify existing patterns using Glob/Grep:
91	- Directory structure relevant to agent's domain
92	- Existing services, controllers, models the agent will work with
93	- Testing patterns and conventions
94	3. Check existing agents in `.claude/agents/` for:
95	- Coordination protocols to follow
96	- Deferral relationships to establish
97	- Naming conventions
98
99	Example exploration:
100	```bash
101	# Find project structure for a backend agent
102	Glob: "app/*/.php"
103	Grep: "class.*Service"
104	Read: "CLAUDE.md", "README.md"
105
106	# Find existing agent patterns
107	Glob: ".claude/agents/*.md"
108	```
109
110	### Step 3: Write the Agent
111
112	Combine research + codebase context into the agent definition:
113	- Persona grounded in project specifics
114	- Anti-patterns from both research AND project history
115	- Project structure and commands the agent needs
116	- Coordination with existing agents
117
118	### Step 4: Session Restart
119
120	After writing the agent file, inform the user:
121
122	```
123	Agent created: .claude/agents/[agent-name].md
124
125	ACTION REQUIRED: Please restart your Claude Code session for the new agent to be available. Agents are loaded at session start.
126
127	To use the agent after restart:
128	- It will appear in the Task tool's available agents
129	- Invoke with: Task tool, subagent_type="[agent-name]"
130	```
131
132	## Anatomy of an Effective Agent
133
134	### 1. Clear Persona Definition
135
136	The persona is the agent's DNA. A well-defined persona produces consistent behavior across interactions.
137
138	```markdown
139	You are a [specific role] with expertise in [domains]. You specialize in [specific capabilities] for [context/project].
140	```
141
142	Good persona:
143	```markdown
144	You are a senior PHP/Laravel backend developer with deep expertise in Laravel, PHP, and server-side architecture. You specialize in building robust, scalable backend systems with clean architecture and secure coding practices for the [Project Name] platform.
145	```
146
147	Bad persona:
148	```markdown
149	You are a helpful assistant that can help

People who liked this also viewed

6 picks

Type

paperclip-create-agentCreate new agents in Paperclip with governance-aware hiring. Use when you need to inspect adapter configuration options, compare existing agent configs, draft a new agent prompt/config, and submit a hSkillsJul 2026157k5
subagent-driven-developmentUse when executing implementation plans with independent tasks in the current sessionSkillsJul 2026154k259k
dispatching-parallel-agentsUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesSkillsJul 2026143k259k
browser-act-skill-forgeForges reusable Skill packages (SKILL.md + scripts) from website exploration via browser-act — no re-exploration later. Use when: user wants a reusable Skill for any website, needs to understand a sitSkillsJul 202685k4.6k
wizardGenerate an interactive bash wizard that walks a human through a manual procedure — third-party setup, a one-off migration, an A→B state transition — opening URLs, capturing values, confirming each stSkillsJul 202675k182k
wonda-cliUsing the Wonda CLI to generate images, videos, music, and audio from the terminal — plus LinkedIn, Reddit, and X/Twitter research and automationSkillsJul 202666k137

writing-agents

120stars16forks

View on GitHub

How to install writing-agents?

aaddrick/claude-pipeline/writing-agents

$npx -y skills add aaddrick/claude-pipeline --skill writing-agents

Installs into the current project.

Summary

Use when creating new agents, editing existing agents, or defining specialized subagent roles for the Task tool

Files · 1

View on GitHub

SKILL.md

1	# Writing Agents
2
3	## Overview
4
5	Writing agents IS Test-Driven Development applied to role definitions.
6
7	Agents are specialized subagents invoked via the Task tool. They receive full conversation context and execute autonomously with a defined persona, tools, and behavioral guidelines.
8
9	Core principle: If you didn't test the agent on representative tasks, you don't know if it performs correctly.
10
11	REQUIRED BACKGROUND: Understand test-driven-development and writing-skills before using this skill. Same RED-GREEN-REFACTOR cycle applies.
12
13	## Agents vs Skills
14
15	\| Aspect \| Agents \| Skills \|
16	\|--------\|--------\|--------\|
17	\| Invocation \| Task tool with `subagent_type` \| Skill tool with skill name \|
18	\| Context \| Full conversation history \| Loaded on-demand \|
19	\| Execution \| Autonomous, multi-turn \| Single response guidance \|
20	\| Persona \| Explicit role/identity \| Reference documentation \|
21	\| Location \| `.claude/agents/` \| `.claude/skills/` \|
22	\| Use for \| Complex, autonomous tasks \| Reusable patterns/techniques \|
23
24	## Agent File Structure
25
26	Agents are PROJECT-LEVEL. They live in the project's `.claude/agents/` directory, not personal directories.
27
28	```
29	.claude/agents/
30	agent-name.md # Single file with frontmatter + persona
31	```
32
33	Frontmatter (YAML):
34	```yaml
35	---
36	name: agent-name
37	description: Role description. Use for [specific task types].
38	model: opus # Optional: opus, sonnet, haiku (defaults to parent)
39	---
40	```
41
42	IMPORTANT: After creating or modifying an agent, prompt the user to restart their Claude Code session. Agents are loaded at session start and won't be available until restart.
43
44	## Agent Creation Workflow
45
46	Before writing the agent, gather domain knowledge and project context:
47
48	### Step 1: Research Domain Best Practices
49
50	Use WebSearch to find domain-specific guidance. Search for:
51	- Best practices for [domain] development
52	- Common [domain] mistakes/anti-patterns
53	- [Domain] code review checklist
54	- [Technology] security considerations
55
56	Example searches by domain:
57	```
58	# Laravel backend agent
59	"Laravel best practices 2026"
60	"Laravel anti-patterns to avoid"
61	"Eloquent ORM performance mistakes"
62	"PHP security vulnerabilities OWASP"
63
64	# React frontend agent
65	"React component best practices 2026"
66	"React performance anti-patterns"
67	"React accessibility checklist"
68
69	# DevOps/infrastructure agent
70	"AWS Lambda best practices"
71	"Infrastructure as Code anti-patterns"
72	"Cloud security common mistakes"
73
74	# Database agent
75	"PostgreSQL query optimization"
76	"Database schema anti-patterns"
77	"SQL injection prevention"
78	```
79
80	Incorporate findings into:
81	- Anti-patterns section (domain-specific mistakes)
82	- Best practices (positive patterns to follow)
83	- Security considerations (if applicable)
84
85	### Step 2: Gather Codebase Context
86
87	Explore the project to make the agent project-specific:
88
89	1. Read CLAUDE.md and README.md for project conventions
90	2. Identify existing patterns using Glob/Grep:
91	- Directory structure relevant to agent's domain
92	- Existing services, controllers, models the agent will work with
93	- Testing patterns and conventions
94	3. Check existing agents in `.claude/agents/` for:
95	- Coordination protocols to follow
96	- Deferral relationships to establish
97	- Naming conventions
98
99	Example exploration:
100	```bash
101	# Find project structure for a backend agent
102	Glob: "app/*/.php"
103	Grep: "class.*Service"
104	Read: "CLAUDE.md", "README.md"
105
106	# Find existing agent patterns
107	Glob: ".claude/agents/*.md"
108	```
109
110	### Step 3: Write the Agent
111
112	Combine research + codebase context into the agent definition:
113	- Persona grounded in project specifics
114	- Anti-patterns from both research AND project history
115	- Project structure and commands the agent needs
116	- Coordination with existing agents
117
118	### Step 4: Session Restart
119
120	After writing the agent file, inform the user:
121
122	```
123	Agent created: .claude/agents/[agent-name].md
124
125	ACTION REQUIRED: Please restart your Claude Code session for the new agent to be available. Agents are loaded at session start.
126
127	To use the agent after restart:
128	- It will appear in the Task tool's available agents
129	- Invoke with: Task tool, subagent_type="[agent-name]"
130	```
131
132	## Anatomy of an Effective Agent
133
134	### 1. Clear Persona Definition
135
136	The persona is the agent's DNA. A well-defined persona produces consistent behavior across interactions.
137
138	```markdown
139	You are a [specific role] with expertise in [domains]. You specialize in [specific capabilities] for [context/project].
140	```
141
142	Good persona:
143	```markdown
144	You are a senior PHP/Laravel backend developer with deep expertise in Laravel, PHP, and server-side architecture. You specialize in building robust, scalable backend systems with clean architecture and secure coding practices for the [Project Name] platform.
145	```
146
147	Bad persona:
148	```markdown
149	You are a helpful assistant that can help

People who liked this also viewed

6 picks

Type