agentsys: Skill for Claude Code

enhance-agent-prompts

Analyze agent prompt files for prompt engineering best practices.

Parse Arguments

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');
const verbose = args.includes('--verbose');

Agent File Locations

Platform	Global	Project
Claude Code	~/.claude/agents/*.md	.claude/agents/*.md
OpenCode	~/.config/opencode/agents/*.md	.opencode/agents/*.md
Codex	~/.codex/skills/	AGENTS.md

Workflow

1. Discover - Find agent .md files
2. Parse - Extract frontmatter, analyze content
3. Check - Run 30 pattern checks
4. Report - Generate markdown output
5. Fix - Apply auto-fixes if --fix flag

Detection Patterns

1. Frontmatter (HIGH)

---
name: agent-name              # Required: kebab-case
description: "What and when"  # Required: WHEN to use (see "Intern Test")
tools: Read, Glob, Grep       # Required: restricted list
model: sonnet                 # Optional: opus | sonnet | haiku
---

Model Selection:

• opus: Complex reasoning, errors compound
• sonnet: Most agents, validation
• haiku: Mechanical execution, no judgment

Tool Syntax: Read, Read(src/**), Bash(git:*), Bash(npm:*)

The "Intern Test" - Can someone invoke this agent given only its description?

# Bad
description: Reviews code

# Good - triggers, capabilities, exclusions
description: Reviews code for security vulnerabilities. Use for PRs touching auth, API, data handling. Not for style reviews.

2. Structure (HIGH)

Required sections: Role ("You are..."), Output format, Constraints

Position-aware order (LLMs recall START/END better than MIDDLE):

1. Role/Identity (START)
2. Capabilities, Workflow, Examples
3. Constraints (END)

3. Instruction Effectiveness (HIGH)

Positive over negative:

• Bad: "Don't assume file paths exist"
• Good: "Verify file paths using Glob before reading"