communicationengineering

Create Agent Markdown

Create high-quality AI agent definition files that follow the Agent Skills specification. Produces behavioral prompts with real mental models, decision frameworks, and domain expertise — not generic filler.

agentsagent-skillsbehavioral-promptssystem-promptspersonas

Works well with agents

Technical PM Agent VP of Product Agent

Works well with skills

PRD Writing

$ npx skills add The-AI-Directory-Company/(…) --skill create-agent-markdown

create-agent-markdown/

anti-patterns.md

Markdown

1	# Anti-Patterns in Agent Definitions
2
3	Common mistakes that make agent definitions generic, unhelpful, or ineffective — and how to fix them.
4
5	## 1. Job description, not persona
6
7	The problem: The definition reads like an HR job posting — lists of responsibilities without establishing how the agent thinks.
8
9	Before (bad):
10	```markdown
11	You are responsible for:
12	- Code reviews
13	- Security assessments
14	- Performance optimization
15	- Mentoring junior developers
16	```
17
18	After (good):
19	```markdown
20	You are a senior code reviewer with the rigor and judgment of a staff
21	engineer who has seen thousands of pull requests. You care deeply about
22	correctness, security, and maintainability — in that order.
23	```
24
25	Why it matters: The bad version tells the model WHAT to do. The good version tells it HOW to think. LLMs already know what code review is — they need the opinionated perspective.
26
27	## 2. Generic advice
28
29	The problem: Phrases like "be thorough," "ensure quality," "follow best practices" add zero information. Every role should be thorough. This is noise.
30
31	Red flag phrases to eliminate:
32	- "Ensure quality and consistency"
33	- "Be thorough in your analysis"
34	- "Follow industry best practices"
35	- "Provide comprehensive feedback"
36	- "Maintain high standards"
37	- "Use appropriate tools and techniques"
38
39	Fix: Replace each with a SPECIFIC principle. "Be thorough" becomes "Check the data flow from input to output. Where does user input enter? How is it validated?"
40
41	## 3. Feature list
42
43	The problem: Describes the agent like a product marketing page — what it CAN do, not how it BEHAVES.
44
45	Before (bad):
46	```markdown
47	## What This Agent Does
48	- Reviews code for bugs and security issues
49	- Provides actionable feedback
50	- Supports multiple programming languages
51	- Integrates with CI/CD pipelines
52	```
53
54	After (good):
55	```markdown
56	## Your review philosophy
57	- Correctness first. Does the code do what it claims?
58	Logic errors, race conditions, unhandled edge cases.
59	- Security second. Injection, auth bypasses, data exposure?
60	You treat security issues as blockers, never suggestions.
61	```
62
63	Why it matters: The "feature list" format is for humans choosing a tool. The agent needs behavioral guidance, not marketing copy.
64
65	## 4. Missing boundaries
66
67	The problem: The agent tries to be everything. Without "refuse to do" constraints, it over-extends into areas where its persona isn't strong, producing mediocre output.
68
69	Fix: Every agent should have 3-5 clear refusals. Each refusal should name what the agent DOESN'T do and redirect to what it DOES.
70
71	## 5. Flat structure
72
73	The problem: All concerns are at the same priority level. The model can't tell what matters most.
74
75	Before (bad):
76	```markdown
77	When reviewing code, check for:
78	- Bugs
79	- Security issues
80	- Style violations
81	- Test coverage
82	- Documentation
83	- Performance
84	- Accessibility
85	```
86
87	After (good):
88	```markdown
89	## Your review philosophy
90	1. Correctness first — logic errors, race conditions
91	2. Security second — vulnerabilities are blockers
92	3. Maintainability third — readability in 6 months
93	4. Style last — defer to linter if one exists
94	```
95
96	Why it matters: Prioritization IS the expertise. Anyone can list things to check. A senior reviewer knows correctness matters more than style.
97
98	## 6. Over-engineering
99
100	The problem: 200+ lines of exhaustive rules, edge cases, and exceptions. The model can't meaningfully follow all of it, and the important signals get lost in noise.
101
102	The research says: Anthropic's guidance explicitly recommends "the minimal set of information that fully outlines your expected behavior." Keep agent bodies to 60-120 lines. Above that, you're either including filler or trying to cover too many scenarios.
103
104	Fix: If your definition exceeds 120 lines, split it:
105	- Core behavioral prompt stays in the body (60-120 lines)
106	- Detailed checklists, reference material, or extended scenarios go in supporting files
107
108	## 7. Persona without substance
109
110	The problem: Assigns a persona ("You are a world-class security expert") without backing it up with domain-specific knowledge. Research shows demographics-only personas explain ~1.5% of behavioral variance. The expertise content is what drives quality.
111
112	Before (bad):
113	```markdown
114	You are a world-class security expert with decades of experience.
115	You are extremely thorough and always find vulnerabilities.
116	```
117
118	After (good):
119	```markdown
120	You are a security auditor who thinks like an attacker first, then a defender.
121
122	For every change, you check:
123	- [ ] User input is validated and sanitized before use
124	- [ ] SQL queries use parameterized statements
125	- [ ] Auth is enforced at the right layer
126	- [ ] Sensitive data is not logged or exposed in errors
127	```
128
129	Why it matters: "World-class expert" is empty. The checklist IS the expertise.
130