131 lines
4.7 KiB
Markdown
131 lines
4.7 KiB
Markdown
# Domain Hooks
|
|
|
|
Architect-specific questions and anti-patterns for brainstorming. Reference the relevant section based on what's being designed.
|
|
|
|
---
|
|
|
|
## Skill
|
|
|
|
### Key Questions
|
|
|
|
- **Trigger**: When should this skill activate? What user intent or request invokes it?
|
|
- **Context needs**: What does Claude need to know to execute? Where does that knowledge live?
|
|
- **Boundaries**: What is explicitly out of scope? What should trigger a different skill?
|
|
- **Output**: What does success look like? A file? A conversation? An action?
|
|
|
|
### Anti-patterns to Critique
|
|
|
|
| Anti-pattern | What to look for |
|
|
|--------------|------------------|
|
|
| Over-specification | Skill tells Claude HOW to do things instead of WHAT knowledge exists and WHERE |
|
|
| Kitchen-sink scope | Skill tries to handle too many scenarios; should be split |
|
|
| Missing escape hatch | No guidance on when NOT to use the skill |
|
|
| Implementation in SKILL.md | SKILL.md contains code examples or step-by-step procedures instead of pointers to references |
|
|
|
|
### Progressive Disclosure Check
|
|
|
|
- Does SKILL.md fit in ~50 lines?
|
|
- Are details in referenced docs, not inline?
|
|
- Can Claude load context incrementally as needed?
|
|
|
|
---
|
|
|
|
## Plugin
|
|
|
|
### Key Questions
|
|
|
|
- **Cohesion**: What unifies the skills in this plugin? What's the theme?
|
|
- **Boundary**: Where does this plugin's responsibility end? What's adjacent but separate?
|
|
- **Dependencies**: Does this plugin depend on others? Should it?
|
|
- **User**: Who installs this plugin? What problem are they solving?
|
|
|
|
### Anti-patterns to Critique
|
|
|
|
| Anti-pattern | What to look for |
|
|
|--------------|------------------|
|
|
| Kitchen-sink | Plugin contains unrelated skills that happen to be made by same author |
|
|
| Overlapping scope | Skills within plugin have unclear boundaries with each other |
|
|
| Missing entry point | No clear CLAUDE.md or SKILL.md directing users to capabilities |
|
|
| Dependency bloat | Plugin requires many other plugins to function |
|
|
|
|
### Structure Check
|
|
|
|
- Does plugin have clear CLAUDE.md explaining what it offers?
|
|
- Are skills cohesive (related purpose) not just co-located?
|
|
- Is the plugin installable and usable independently?
|
|
|
|
---
|
|
|
|
## Agent
|
|
|
|
### Key Questions
|
|
|
|
- **Task fit**: What specific task type does this agent handle? When is it dispatched?
|
|
- **Tools**: What tools does the agent need? What tools should it NOT have?
|
|
- **Autonomy level**: How much should it decide on its own vs. ask for guidance?
|
|
- **Output contract**: What does the agent return to the caller?
|
|
|
|
### Anti-patterns to Critique
|
|
|
|
| Anti-pattern | What to look for |
|
|
|--------------|------------------|
|
|
| Tool overload | Agent has access to tools it doesn't need |
|
|
| Unclear boundaries | Agent's responsibility overlaps with other agents or main thread |
|
|
| Missing output contract | Caller doesn't know what to expect back |
|
|
| Over-autonomy | Agent makes decisions that should be escalated |
|
|
|
|
### Dispatch Check
|
|
|
|
- Is it clear when to use this agent vs. doing the work in main thread?
|
|
- Does the agent description in Task tool registry accurately describe capability?
|
|
- Can the agent complete its task with the tools provided?
|
|
|
|
---
|
|
|
|
## Slash Command
|
|
|
|
### Key Questions
|
|
|
|
- **Trigger**: What does the user type to invoke? Is it memorable?
|
|
- **Input**: What arguments does it accept? What's required vs. optional?
|
|
- **Output**: What happens when invoked? File created? Action taken? Skill loaded?
|
|
- **Discoverability**: How does user learn this command exists?
|
|
|
|
### Anti-patterns to Critique
|
|
|
|
| Anti-pattern | What to look for |
|
|
|--------------|------------------|
|
|
| Overloaded command | Command does too many different things based on args |
|
|
| Unclear invocation | User can't guess what to type |
|
|
| Missing feedback | Command runs silently without confirming action |
|
|
| Duplicates skill | Command is just an alias for a skill with no added value |
|
|
|
|
### Naming Check
|
|
|
|
- Is the command name a verb? (commit, audit, review)
|
|
- Is it 1-2 words max?
|
|
- Does it conflict with existing commands?
|
|
|
|
---
|
|
|
|
## Description (Frontmatter)
|
|
|
|
### Key Questions
|
|
|
|
- **Escape hatch**: Does the description help Claude know when NOT to use this?
|
|
- **Trigger clarity**: Is it clear what user intent/request activates this?
|
|
- **Specificity**: Is it specific enough to avoid false positives?
|
|
|
|
### Anti-patterns to Critique
|
|
|
|
| Anti-pattern | What to look for |
|
|
|--------------|------------------|
|
|
| Too broad | Description matches requests it shouldn't handle |
|
|
| Too narrow | Description misses valid use cases |
|
|
| Missing negative triggers | No "don't use when" guidance |
|
|
| Marketing language | Description sells rather than describes |
|
|
|
|
### Test
|
|
|
|
Read the description and ask: "If I were Claude seeing a user request, would this description help me decide correctly whether to use this?"
|