Handle Approval Skill

Manages the Human-in-the-Loop (HITL) approval workflow - the safety layer for all sensitive actions.

Core Responsibilities

Create Approval Requests: Generate structured approval files for sensitive actions
Monitor Approval Status: Check Vault/Approved and Vault/Rejected folders for human decisions
Execute Approved Actions: Safely execute actions once approved
Maintain Audit Trail: Log all approval decisions and outcomes
Enforce Security Rules: Ensure compliance with approval thresholds

When This Skill Activates

Trigger phrases:

"check approvals"
"handle pending approvals"
"what needs my approval"
"approve this"
"check approval status"
"pending approvals"

Auto-activates when:

Any action requires human approval
Monitoring approval folders for decisions
Before executing potentially risky operations

Core Workflow

Phase 1: Creating Approval Requests

When a skill needs approval (e.g., process-emails, post-to-linkedin):

Determine Action Type
- Identify category: payment, email, social, file, or other
- Check approval-thresholds.md to confirm approval needed
- Verify action aligns with Vault/Business_Goals.md and Vault/Company_Handbook.md
Create Approval Request File
- Filename format: APPROVAL_[TYPE]_[DESCRIPTION]_[DATE].md
- Example: APPROVAL_EMAIL_ClientA_Invoice_2026-01-11.md
- Save in Vault/Pending_Approval folder
- Use approval-template.md
Include Critical Information
- Action Summary: One-line clear description
- Details: Action type, target, reason, source
- Parameters: All required values (recipient, amount, content, etc.)
- Draft/Preview: Show what will be sent/posted
- Risks: What could go wrong
- Expiration: When approval expires (24-72 hours based on action type)
- Instructions: How to approve (move to Vault/Approved) or reject (move to Vault/Rejected)
Log to Dashboard
- Update Vault/Dashboard.md with approval request created
- Include timestamp, action type, priority

See approval-template.md for complete format.

Phase 2: Monitoring Approval Status

Run when user asks to "check approvals" or periodically:

Scan Vault/Pending_Approval Folder
- List all pending approval files
- Check for expired approvals (past expiration timestamp)
- Report summary (count by priority)
Check Vault/Approved Folder
- Find newly approved files
- For each: validate format, re-check parameters, proceed to execution
Check Vault/Rejected Folder
- Find newly rejected files
- Read rejection reason (human adds at bottom)
- Log to Dashboard, move to Vault/Done
Handle Expired Approvals
- Move to Vault/Rejected with "EXPIRED - No decision made" note
- Log expiration to Dashboard

Helper Script:

python .claude/skills/handle-approval/scripts/check_approval_status.py [--json]

Phase 3: Executing Approved Actions

CRITICAL: Only execute if file is in Vault/Approved folder and passes validation

Validate Approval File
- Confirm proper structure and required sections
- Check not expired
- Verify all parameters present and valid
- Confirm action type supported
Re-Validate Parameters
- Check against security-rules.md
- Verify recipient/target still valid
- Confirm amounts within limits (for payments)
- Check for duplicates (prevent double-execution)
Execute Action by Type
- Email: Use Email MCP server
- Social Media: Use platform-specific MCP (LinkedIn, Twitter, etc.)
- Payment: Use Banking/Payment MCP
- File: Perform file operation
- Capture result (success/failure, confirmation ID, errors)
Log Execution
- Add to approval file Execution Log section
- Include timestamp, result, confirmation IDs, errors
- Mark executed_by: "claude_code"
Move to Vault/Done
- Archive completed approval
- Update Vault/Dashboard.md

Phase 4: Error Handling

If execution fails:

Capture Error Details
- Full error message and code
- Timestamp of failure
Log to Approval File
- Add error to Execution Log section
- Mark status: "failed"
DO NOT Move to Vault/Done
- Keep in Vault/Pending_Approval for human review
- Allows retry or rejection decision
Alert User
- Update Dashboard with high-priority error
- Include next steps
Never Auto-Retry
- Financial/communication actions must not auto-retry
- Always require fresh approval after failure

Security Safeguards

Before Creating Approval:

✅ Action not in auto-approve list
✅ Aligns with Vault/Business_Goals.md
✅ Follows Vault/Company_Handbook.md rules
✅ All parameters valid

Before Executing Approval:

✅ File in Vault/Approved folder
✅ Not expired
✅ Parameters pass security validation
✅ Action type supported
✅ MCP server available

Never Execute If:

❌ File in Vault/Pending_Approval
❌ Approval expired
❌ Parameters violate security rules
❌ MCP server unavailable
❌ Any validation fails

See security-rules.md for complete policies.

Reference Files

Progressive disclosure - load on demand:

approval-thresholds.md
- What requires approval vs auto-approve
- Thresholds by action type (email, payment, social, files)
- Conditional approval rules
approval-template.md
- Standard format for approval requests
- Template variations by action type
- Required vs optional sections
security-rules.md
- Security validation rules
- Never auto-approve list
- Expiration policies
- Rate limiting
troubleshooting.md
- Common issues and solutions
- Error message reference
- Debugging workflow

Helper Scripts

check_approval_status.py

Purpose: Scan approval folders and generate status report

Usage:

# Human-readable output (may have encoding issues on Windows)
python .claude/skills/handle-approval/scripts/check_approval_status.py

# JSON output (recommended for Windows, programmatic parsing)
python .claude/skills/handle-approval/scripts/check_approval_status.py --json

# Specify vault path
python .claude/skills/handle-approval/scripts/check_approval_status.py --vault-path Vault/

Output:

Summary: Count of pending, approved, rejected, expired
Pending approvals with priority and age
Actions awaiting execution
Recently rejected items
Expired approvals

Integration with Other Skills

Skills that call handle-approval:

process-emails → Creates approval for sending emails
post-to-linkedin → Creates approval for social posts
process-tasks → May create approval for sensitive file operations

Workflow:

1. Skill determines action needs approval
2. Calls handle-approval to create approval request
3. handle-approval creates file in `Vault/Pending_Approval`
4. Human manually moves to `Vault/Approved` or `Vault/Rejected`
5. User invokes handle-approval to check status
6. handle-approval executes approved actions

Dashboard Logging

All approval activity logged to Vault/Dashboard.md:

### [Timestamp] - Approval Activity

**Request Created:**
- Type: [email/payment/social/file]
- Action: [Description]
- Status: Pending Approval
- File: Vault/Pending_Approval/[filename]

**Approval Executed:**
- Type: [email/payment/social/file]
- Result: Success/Failed
- Details: [Confirmation ID or error]

**Approval Rejected:**
- Type: [email/payment/social/file]
- Reason: [Human's rejection reason]

Success Criteria

This skill works correctly when:

✅ All sensitive actions create approval requests ✅ Approval files properly formatted and complete ✅ Approved actions execute successfully with logs ✅ Rejected actions logged and archived ✅ Expired approvals handled automatically ✅ Dashboard maintains complete audit trail ✅ Zero unauthorized actions ✅ No duplicate or partial executions

Common Issues

See troubleshooting.md for complete guide.

Quick fixes:

Action not executing: Verify file in Vault/Approved (not Vault/Pending_Approval)
MCP server error: Check server running and authenticated
Expired prematurely: Verify timestamps in UTC (ISO 8601 with Z)
Can't find approvals: Check filename matches APPROVAL_*.md pattern
Encoding errors (Windows): Use --json flag with check_approval_status.py

Skill Version: 2.1 (Updated for Vault structure) Last Updated: 2026-01-11 Branch: feat/silver-core-workflows

handle-approval

SKILL.md.claude/skills/handle-approval/SKILL.md