Agent-Skills.md

Agent Skills: Claude Engineering Best Practices

General-purpose guidance for Claude Code (terminal) and Claude Dev (platform). Covers stable principles (progressive disclosure, hooks, security) and volatile details with lookup workflows.

UncategorizedID: Git-Fg/thecattoolkit/claude-engineering-best-practices

Repository

Git-Fg/thecattoolkit
Git-FgLicense: MIT
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/Git-Fg/thecattoolkit/tree/HEAD/.agent/skills/claude-engineering-best-practices

Skill Files

Browse the full folder contents for claude-engineering-best-practices.

Download Skill

Loading file tree…

.agent/skills/claude-engineering-best-practices/SKILL.md

Skill Metadata

Name
claude-engineering-best-practices
Description
General-purpose guidance for Claude Code (terminal) and Claude Dev (platform). Covers stable principles (progressive disclosure, hooks, security) and volatile details with lookup workflows.

Claude Engineering Best Practices

Quick Start

Use this Skill for:

  • Claude Code configuration (plugins, hooks, sandboxing, settings)
  • Claude Dev Agent SDK (tools, sessions, subagents, MCP)
  • Plugin development and agent architecture
  • Security patterns and best practices

Lookup workflow (verify volatile details):

# 1. Search for topic
rg -n "pattern" references/claude-*/**/*.md

# 2. Find official URL
rg -n "pattern" references/sources/llms_claude_*.txt

# 3. Fetch official doc
curl -sL "https://code.claude.com/docs/en/topic.md" | rg -A 5 "fieldName"

Core Principles (Stable Patterns)

1. Progressive Disclosure

Information revealed in stages based on need:

| Level | What | Token Cost | When Loaded | |-------|------|-----------|------------| | Metadata | name + description | ~100 tokens | Always (startup) | | Instructions | SKILL.md body | <5k tokens | On trigger | | Resources | Bundled files | Unlimited | As needed (via bash) |

2. Hook-Based Architecture

Universal event system across Claude Code and SDK:

  • PreToolUse: Validate/modify before execution
  • PostToolUse: Log/validate after execution
  • SessionStart: Initialize context
  • Stop: Control completion criteria

3. Security-First Design

Multiple defensive layers:

  • Principle of least privilege: Minimal permissions
  • Defense in depth: Sandbox + IAM + hooks
  • Zero trust: Verify at every layer

Navigation Guide

By Topic

Plugin Architecture

rg -n "plugin" references/claude-code/plugins.md
# Structure, manifest, caching, components

Hooks & Events

rg -n "PreToolUse\|PostToolUse" references/claude-code/hooks.md
# All events, types, schemas, patterns

Sandboxing

rg -n "sandbox\|network\|filesystem" references/claude-code/sandboxing.md
# Security, isolation, configuration

Agent SDK

rg -n "sessions\|hooks\|subagents" references/claude-dev/agent-sdk.md
# Sessions, hooks, tools, permissions

Skills Authoring

rg -n "progressive\|SKILL\.md" references/claude-dev/skills.md
# 3-tier architecture, best practices

By Product

Claude Code (Terminal)

  • references/claude-code/plugins.md - Plugin architecture
  • references/claude-code/hooks.md - Hook system
  • references/claude-code/sandboxing.md - Security isolation
  • references/claude-code/settings-permissions.md - Configuration
  • references/claude-code/mcp-lsp.md - MCP & LSP integration
  • references/claude-code/workflows.md - Common workflows

Claude Dev (Platform)

  • references/claude-dev/agent-sdk.md - SDK patterns
  • references/claude-dev/skills.md - Skills architecture
  • references/claude-dev/tool-use.md - Tool use patterns
  • references/claude-dev/prompt-engineering.md - Prompting best practices
  • references/claude-dev/security-evaluation.md - Security & testing

Common Workflows

Author Workflow (Design → Implement)

  1. Identify capability needed (skill, agent, hook, plugin)
  2. Check latest docs for current schema/patterns
  3. Design with progressive disclosure (3-tier)
  4. Implement with stable patterns
  5. Test with verification hooks

Operator Workflow (Use → Execute)

  1. Determine tool/agent needed
  2. Verify permissions & sandbox settings
  3. Execute with appropriate oversight
  4. Validate results via hooks/logs

Reviewer/Auditor Workflow (Evaluate → Score)

  1. Check objective completion (artifact/verdict)
  2. Verify security compliance (permissions, sandbox, hooks)
  3. Assess engineering quality (reproducibility, clarity)
  4. Review documentation & patterns used

Stable vs Volatile Information

✅ Stable Principles (Always Accurate)

  • Progressive disclosure architecture
  • Hook-based event system
  • Plugin component structure
  • Security design patterns
  • Three-tier skill architecture

⚠️ Volatile Details (Look Up First)

These change frequently - never hardcode:

  • API field names (exact JSON keys)
  • Command flags (--debug, --resume, etc.)
  • Hook event schemas (input/output structures)
  • Plugin.json fields (required/optional)
  • Tool permission lists
  • Network domain allowlists

Always verify volatile details:

# Find correct URL
rg -n "topic.*\.md" references/sources/llms_claude_code.txt

# Fetch and extract
curl -sL "https://code.claude.com/docs/en/topic.md" | rg -A 5 "fieldName"

Quick Reference

Most Common Lookups

# Plugin.json required fields
curl -sL "https://code.claude.com/docs/en/plugins-reference.md" | rg -A 10 "Required fields"

# Hook events
curl -sL "https://code.claude.com/docs/en/hooks.md" | rg "^### "

# Agent SDK hooks
curl -sL "https://platform.claude.com/docs/en/agent-sdk/hooks.md" | rg -A 5 "PreToolUse"

# Sandbox configuration
curl -sL "https://code.claude.com/docs/en/sandboxing.md" | rg -A 10 "filesystem\|network"

# Structured outputs
curl -sL "https://platform.claude.com/docs/en/build-with-claude/structured-outputs" | rg -A 5 "json_schema"

Decision Matrix

| Situation | Action | |-----------|--------| | curl succeeds, domain allowed | Use fetched data, cite source | | curl succeeds, domain blocked | Document limitation, use local refs | | curl fails (network error) | Use local refs, mark outdated | | curl fails (403/permission) | Request permission, use local refs | | Can't fetch docs | Use local reference files |

Examples

Example 1: Test Framework Architecture

// Three-Agent Pattern
class TestRunner {
  // Agent A: Executor with hooks and sandbox
  async execute(task: string): Promise<void> {
    const options = {
      allowedTools: ['Read', 'Write', 'Edit', 'Bash'],
      permissionMode: 'acceptEdits',
      sandbox: { enabled: true },
      hooks: getHooks()  // PreToolUse, PostToolUse logging
    };
  }

  // Agent B: Simulator - generates tasks
  // Agent C: Evaluator - multi-step structured evaluation
}

Example 2: Plugin Audit Checklist

# 1. Check structure
rg -n "\.claude-plugin\|plugin\.json" references/claude-code/plugins.md

# 2. Verify hooks pattern
rg -n "PreToolUse\|PostToolUse" references/claude-code/hooks.md

# 3. Check security settings
rg -n "sandbox\|permission" references/claude-code/sandboxing.md

# 4. Verify progressive disclosure
rg -n "3-tier\|progressive" references/claude-dev/skills.md

Example 3: Agent SDK Configuration

# Complete SDK pattern
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],
    permission_mode="acceptEdits",
    session_persistence=True,
    hooks={
        "PreToolUse": [HookMatcher(...)],
        "PostToolUse": [HookMatcher(...)]
    },
    agents={
        "specialist": AgentDefinition(...)
    },
    setting_sources=["project"]
)

Anti-Patterns (Avoid)

❌ Hardcoding volatile details ❌ Missing progressive disclosure ❌ No validation hooks ❌ Hardcoded paths (use env vars) ❌ Overly verbose descriptions ❌ Deeply nested references (keep one level deep)

Official Documentation

Master Indexes

  • Claude Code: https://code.claude.com/docs/llms.txt
  • Claude Dev: https://platform.claude.com/docs/llms.txt

Key References

  • Agent SDK Overview: https://platform.claude.com/docs/en/agent-sdk/overview.md
  • Agent Skills: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview.md
  • Tool Use: https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview.md
  • Hooks Reference: https://code.claude.com/docs/en/hooks.md
  • Sandboxing: https://code.claude.com/docs/en/sandboxing.md
  • Plugins: https://code.claude.com/docs/en/plugins-reference.md

Verification & Maintenance

Last verified: 2026-01-13

Always verify volatile details before implementation using the lookup workflow documented above.

Monthly checks:

  • Review official documentation for updates
  • Check for deprecated features
  • Update local references if needed

About this Skill: This Skill applies progressive disclosure - only load what you need. Start with SKILL.md, reference thematic files for details, use lookup workflow for volatile information.