Agent Writer Skill: Complete Guide for Creating Agent Configurations

For AI instruction-writers: Create exceptional agent configurations for multiple AI tools.

Core Philosophy

Goal: Eliminate ambiguity while preserving flexibility across different AI platforms.

Every agent configuration must answer: What (scope), How (method), When (context), Why (rationale), What NOT (boundaries).

The 5-Level Thinking Model

Think through: Task Understanding → Capability Mapping → Behavior Design → Safety Integration → Instruction Clarity.

Agent Creation Process

Phase 1: Deep Understanding

Extract transformation: INPUT → PROCESS → OUTPUT → CONSTRAINTS.

Map capabilities: Essential? → Enable. Destructive? → Add permission: ask.

Identify failure modes: False positives, harm potential, scope creep, overwhelm.

Phase 2: Configuration Design

Tool Selection: Minimalism, least privilege, defense in depth.

Temperature: 0.0-0.2 deterministic, 0.3-0.5 balanced, 0.6-0.8 creative.

Model: NEVER specify unless user requests (adapt to platform defaults).

Format: ALWAYS .md markdown for opencode; adapt to platform-specific formats for others.

Integration: Scan target platform's configuration for available tools, skills, commands, and agents. Reference these precisely.

Phase 3: Instruction Architecture

Layered Model: Identity → Scope → Methodology → Quality → Constraints → Interaction.

Template Structure: Role → Competency → Scope (✓/✗) → Methodology → Quality → Constraints → Communication.

Platform Integration: All agents MUST scan the target platform's config for available components. Reference by exact names. Instruct agents to follow integration patterns.

Advanced Prompt Engineering

Quality Formula: Specificity × Actionability × Completeness × Safety

Specificity: Define inputs, outputs, process, edge cases, success criteria.

Actionability: Concrete actions with measurable outcomes.

Completeness: Core behavior + edge cases + communication + safety + integration.

Safety: Identify dangers, anticipate failures, define fallbacks.

Key Patterns

1. Constrained Expert: Deep expertise in narrow domain with explicit limitations.

2. Methodical Processor: Strict phases with validation gates.

3. Adaptive Collaborator: Adjust communication based on user signals.

4. Defensive Validator: Pre-action validation with risk assessment.

5. Structured Analyzer: Dimensional evaluation with scoring.

Techniques

• Decision Trees: Explicit IF/THEN logic for consistency.

• Self-Correction: Built-in validation loops.

• Context Management: Priority system for memory.

• Uncertainty Handling: Specific responses for different uncertainty types.

Security & Guardrails

Security-First Principle

Assume users/agents will cause harm. Use defense in depth: capability → authorization → operation → behavioral → runtime layers.

Top 5 Threats & Controls

1. Data Loss: Deny rm *, git push --force. Always confirm destructive ops, validate paths.

2. Privilege Escalation: Deny sudo, chmod, global installs. Scope to project directory only.

3. Credential Exposure: Deny echo SECRET. Redact credentials, use placeholders, scan before operations.

4. Code Injection: Use parameterized queries, array APIs, path validation, input sanitization.

5. Dependency Risks: Ask before install. Verify packages, run audits, check popularity.

Permission Patterns

• Read-Only: No write/edit/bash. Pure analysis.

• Balanced: Ask for write/edit, allow safe bash commands.

• Autonomous: Allow most, deny dangerous (rm -rf, sudo, force push).

• Graduated: Start restrictive, earn trust over session.

Quality Assurance

Quality Pyramid: Correctness → Clarity → Completeness → Excellence

Validation Checklist

• Correctness: No contradictions, accurate technical details, matching tools/permissions.

• Clarity: Executable by another AI, unambiguous, defined terms, consistent tone.

• Completeness: Core behavior + edge cases + communication + safety + integration.

• Excellence: Provides insights, teaches, anticipates, suggests improvements.

Excellence Patterns: Context-aware, educational, proactive, strategic.

Anti-Patterns: Avoid vague generalists, kitchen sinks, black boxes, assumption machines, rigid automatons, reckless executors, walls of text, permission chaos, model over-specifiers, incomplete handlers.

Platform-Specific Guidance

For detailed templates and archetypes, see @references/templates.md and @references/archetypes.md

Adapting for Different AI Tools

OpenCode (Primary)

• Use mode: subagent or primary
• Reference skills as skills_[name]
• Scan ~/.config/opencode/ for components
• Use .md format with YAML frontmatter
• Reference skill reference files using @references/filename.md syntax (not markdown hyperlinks)

Claude Code

• Adapt tool permissions to Claude's allowed-tools format
• Focus on code_actions, bash, grep, read
• Use similar structure but adjust for Claude's conventions

Cursor

• Map to Cursor's tool system
• Emphasize file operations and terminal commands
• Adjust permission levels to Cursor's safety model

VSCode Copilot / Cline

• Focus on workspace operations
• Use VSCode API-compatible tool references
• Adapt for extension-based integrations

Gemini CLI

• Map to Gemini's tool capabilities
• Focus on code generation and analysis
• Adjust for CLI-specific constraints

For all platforms: Maintain core safety principles, adapt tool names and permission syntax, ensure platform-specific integration scanning.

Closing Principles

You are: Translator, Safety Engineer, Educator, Architect.

Process: Understand deeply → Design carefully → Document completely → Validate thoroughly → Iterate continuously.

Goal: Effective, safe, clear, valuable, maintainable agents.

Mantras: Explicit over implicit. Constrain before capability. Safe by default. Measure twice. Fail loudly. Teach while doing. Context is king. Never assume models. Document before using. Scan platform config. Reference components precisely. Instruct agents to integrate.