Skill: nishantapatil3/self-improving-intent-security-agent (version 1.0.7)

--- name: self-improving-intent-security-agent description: "Documentation-first skill and workflow toolkit for intent-based security. Provides templates, examples, and local helper scripts for capturing intent, reviewing actions, documenting rollbacks, and recording learnings. Use when: (1) designing or prototyping intent validation workflows, (2) documenting high-risk operations, (3) creating audit trails and rollback records, (4) building your own runtime enforcement layer." --- # Self-Improving Intent Security Agent ## Install ```bash npx skills add nishantapatil3/self-improving-intent-security-agent ``` Use this skill to structure and document intent validation workflows. It does not ship a production runtime engine that automatically intercepts agent actions; instead, it provides templates, examples, and local scripts that help you build, simulate, or document that workflow. ## Scope Clarification - This package includes markdown templates, examples, and helper shell scripts - The helper shell scripts operate on local files only - Automatic enforcement, anomaly detection, rollback execution, and learning application must be implemented by the host agent or surrounding system ## Quick Reference | Situation | Action | |-----------|--------| | Starting autonomous task | Capture intent specification (goal, constraints, expected behavior) | | Before each action | Validate against intent, check authorization | | Action violates intent | Document the violation and follow the rollback workflow | | Unusual behavior detected | Log an anomaly, assess severity, and decide whether to halt or roll back | | Task completes | Analyze outcome, extract patterns, update strategies | | High-risk operation | Require human approval before execution | | Need transparency | Review audit log with full action history | | Strategy improves | A/B test new approach, adopt if better | | Recurring violation | Promote to permanent constraint in CLAUDE.md | ## Setup Create `.agent/` directory in project root: ```bash mkdir -p .agent/{intents,violations,learnings,audit} ``` Copy templates from `assets/` or create files with headers. Review the included shell scripts before running them if you want to understand exactly what they do. For a complete conversation-driven working folder, scaffold a run pack: ```bash ./scripts/scaffold-run.sh examples/my-demo customer_feedback medium ``` This creates: - `conversation.md` for the user/agent transcript - `report.md` for the final summary - a local `.agent/` tree with intent, audit, violation, rollback, learning, and strategy files ## Intent Specification Format Before executing autonomous tasks, capture structured intent: ```markdown ## [INT-YYYYMMDD-XXX] task_name **Created**: ISO-8601 timestamp **Risk Level**: low | medium | high **Status**: active | completed | violated ### Goal What you want to achieve (single clear objective) ### Constraints - Boundary 1 (e.g., "Only modify files in ./src") - Boundary 2 (e.g., "Do not make network calls") - Boundary 3 (e.g., "Preserve existing test coverage") ### Expected Behavior - Pattern 1 (e.g., "Read files before modifying") - Pattern 2 (e.g., "Run tests after changes") - Pattern 3 (e.g., "Create backups of modified files") ### Context - Relevant files: path/to/file.ext - Environment: development | staging | production - Previous attempts: INT-20250115-001 (if retry) --- ``` Save to `.agent/intents/INT-YYYYMMDD-XXX.md`. ## Validation Workflow ## Conversation-Driven Workflow Use this when you want the skill to document not just the intent, but the full user and agent interaction over time. ### Recommended Sequence 1. Capture the user request in `conversation.md` 2. Translate it into a structured intent in `.agent/intents/` 3. Record allowed and blocked actions in `.agent/audit/` 4. Log suspicious behavior in `.agent/violations/ANOMALIES.md` 5. Log hard validation failures in `.agent/violations/` 6. Record recovery steps in `.agent/audit/ROLLBACKS.md` 7. Extract reusable learnings in `.agent/learnings/` 8. Promote stable improvements into `.agent/learnings/STRATEGIES.md` 9. Summarize the run in `report.md` ### Good Fit - High-risk or privacy-sensitive tasks - Tasks where you need a human-readable transcript - Demos and evaluations - Incident reviews and postmortems ### Example See [REDACTED_SECRET] for a full run showing: - intent capture - per-action validation - anomaly detection - blocked violation - rollback - learning promotion ### Pre-Execution Validation Before each action, validate: 1. **Goal Alignment**: Does this action serve the stated goal? 2. **Constraint Check**: Does it respect all boundaries? 3. **Behavior Match**: Does it fit expected patterns? 4. **Authorization**: Do we have permission for this? If ANY check fails → block action, log violation. ### Example Validation ```yaml Intent: "Process customer feedback files" Constraints: ["Only read ./feedback", "No file modifications"] Action: "delete ./feedback/temp.txt" Validation: - Goal Alignment: ❌ Deleting isn't "processing" - Constraint Check: ❌ Violates "no modifications" - Behavior Match: ❌ Not expected for this task - Authorization: ✓ (but blocked by other checks) Result: BLOCKED → Log violation → Consider rollback ``` ## Logging Violations When validation fails, log to `.agent/violations/`: ```markdown ## [VIO-YYYYMMDD-XXX] violation_type **Logged**: ISO-8601 timestamp **Severity**: low | medium | high | critical **Intent**: INT-20250115-001 **Status**: pending_review ### What Happened Action that was attempted ### Validation Failures - Goal Alignment: [reason] - Constraint Check: [which constraint violated] - Behavior Match: [how it deviated] ### Action Taken - [ ] Action blocked - [ ] Checkpoint rollback - [ ] Alert sent - [ ] Execution halted ### Root Cause Why the agent attempted this (if analyzable) ### Prevention How to prevent this in the future ### Metadata - Related Intent: INT-20250115-001 - Action Type: file_delete | api_call | command_execution - Risk Level: high - See Also: VIO-20250110-002 (if recurring) --- ``` ## Anomaly Detection Monitor execution for behavioral anomalies: ### Anomaly Types | Type | Description | Response | |------|-------------|----------| | **Goal Drift** | Actions diverging from stated goal | Halt, request clarification | | **Capability Misuse** | Using tools inappropriately | Rollback to checkpoint | | **Side Effects** | Unexpected consequences detected | Log warning, continue with monitoring | | **Resource Exceeded** | CPU/memory/time limits breached | Throttle or halt | | **Pattern Deviation** | Behavior differs from expected | Log for analysis | ### Anomaly Logging Log to `.agent/violations/ANOMALIES.md`: ```markdown ## [ANO-YYYYMMDD-XXX] anomaly_type **Detected**: ISO-8601 timestamp **Severity**: low | medium | high **Intent**: INT-20250115-001 ### Anomaly Details What unusual behavior was detected ### Evidence - Metric that triggered alert - Baseline vs. actual values - Timeline of deviation ### Assessment Why this is anomalous ### Response Taken - [ ] Continued with monitoring - [ ] Applied constraints - [ ] Rolled back - [ ] Halted execution --- ``` ## Learning Workflow After task completion, log learnings to `.agent/learnings/`: ```markdown ## [LRN-YYYYMMDD-XXX] category **Logged**: ISO-8601 timestamp **Intent**: INT-20250115-001 **Outcome**: success | failure | partial ### What Was Learned Pattern or insight discovered ### Evidence - Success rate: 95% - Execution time: 2.3s - Actions taken: 15 - Checkpoints: 3 ### Strategy Impact How this affects future executions ### Application Scope - Tasks: file_processing, data_transformation - Risk Levels: low, medium - Conditions: when X and Y are true ### Safety Check - Complexity: low | medium | high - Performance: baseline_comparison - Risk: assessment ### Metadata - Category: pattern | optimization | error_handling | security - Confidence: low | medium | high - Sample Size: N tasks observed - Pattern-Key: file.batch_processing (if recurring) --- ``` ## Rollback Operations ### Creating Checkpoints Before risky operations: ```typescript const checkpoint = await agent.checkpoint.create({ intent: currentIntent, reason: "Before bulk file operations" }); ``` ### Rollback on Violation Automatic rollback when intent violated: ```typescript // Happens automatically, but can also trigger manually: await agent.rollback.restore(checkpointId, { reason: "Detected constraint violation", notify: true }); ``` ### Rollback Log Track in `.agent/audit/ROLLBACKS.md`: ```markdown ## [RBK-YYYYMMDD-XXX] checkpoint_id **Executed**: ISO-8601 timestamp **Intent**: INT-20250115-001 **Trigger**: automatic | manual ### Reason Why rollback was necessary ### Actions Reversed - Action 1 (reversed successfully) - Action 2 (reversed successfully) - Action 3 (reversal failed - manual intervention needed) ### Checkpoint Restored - Checkpoint: CHK-20250115-001 - Created: 2025-01-15T10:00:00Z - Actions since checkpoint: 15 ### Status - [ ] Fully restored - [ ] Partially restored (see notes) - [ ] Manual intervention required --- ``` ## Strategy Evolution When agent learns better approaches: ### A/B Testing 1. **Baseline**: Current strategy (90% of tasks) 2. **Candidate**: New strategy (10% of tasks) 3. **Measure**: Compare success rate, time, resource usage 4. **Validate**: Safety checks pass 5. **Adopt**: Roll out if candidate is 10%+ better 6. **Rollback**: Revert if candidate degrades performance ### Strategy Log Track in `.agent/learnings/STRATEGIES.md`: ```markdown ## [STR-YYYYMMDD-XXX] strategy_name **Created**: ISO-8601 timestamp **Domain**: file_processing | api_interaction | error_handling **Status**: testing | adopted | rejected | superseded ### Approach What this strategy does differently ### Performance - Baseline: 85% success, 3.2s avg - Candidate: 92% success, 2.1s avg - Improvement: +7% success, -34% time ### A/B Test Results - Test Tasks: 50 - Candidate Used: 5 tasks - Wins: 4, Losses: 1, Ties: 0 ### Safety Validation - Complexity: within limits (complexity: 45/100) - Permissions: no expansion - Risk: acceptable (no high-risk changes) ### Adoption Decision - [ ] Adopt (outperforms baseline) - [ ] Reject (underperforms baseline) - [ ] Extend testing (inconclusive) --- ``` ## Promoting to Permanent Memory When learnings are broadly applicable, promote to project files: ### Promotion Targets | Target | What Belongs There | |--------|-------------------| | `CLAUDE.md` | Intent patterns, common constraints for this project | | `AGENTS.md` | Agent-specific workflows, validation rules | | `.github/copilot-instructions.md` | Security guidelines, constraint templates | | `SECURITY.md` | Security-critical constraints and validation rules | ### When to Promote Promote when: - Violation occurs 3+ times (recurring constraint) - Learning applies across multiple task types - Strategy is adopted and proven (success rate 90%+) - Security pattern prevents entire class of violations ### Promotion Examples **Violation** (recurring): > VIO-20250115-001: Attempted to modify files outside ./src > VIO-20250118-002: Attempted to modify files outside ./src > VIO-20250120-003: Attempted to modify files outside ./src **Promote to CLAUDE.md**: ```markdown ## File Modification Constraints - Only modify files within `./src` directory - Other directories are read-only unless explicitly authorized ``` **Learning** (proven strategy): > LRN-20250115-005: Batch processing with checkpoints every 10 files > Results: 95% success, 40% faster, easy rollback on failures **Promote to AGENTS.md**: ```markdown ## File Processing Strategy - Use batch processing (10 files per batch) - Create checkpoint before each batch - Enables fast rollback on errors ``` ## Configuration ### Environment Variables **Important**: All environment variables are **optional**. The skill works with sensible defaults without any configuration. **Security Note**: This skill does NOT require any credentials or secrets. All data stays local in the `.agent/` directory. No data is transmitted externally. ```bash # Paths (optional - defaults shown) export AGENT_INTENT_PATH=".agent/intents" # Default: .agent/intents export AGENT_AUDIT_PATH=".agent/audit" # Default: .agent/audit # Security Settings (optional tuning) export AGENT_RISK_THRESHOLD="medium" # low | medium | high export AGENT_AUTO_ROLLBACK="true" # true | false export AGENT_ANOMALY_THRESHOLD="0.8" # 0.0 - 1.0 # Learning Settings (optional tuning) export AGENT_LEARNING_ENABLED="true" # true | false export AGENT_MIN_SAMPLE_SIZE="10" # Min observations before adopting export AGENT_AB_TEST_RATIO="0.1" # 10% of tasks for A/B testing # Monitoring (optional tuning) export AGENT_METRICS_INTERVAL="1000" # Metrics collection (ms) export AGENT_AUDIT_LEVEL="detailed" # minimal | standard | detailed ``` ### Configuration File Create `.agent/config.json`: ```json { "security": { "requireApproval": ["file_delete", "api_write", "command_execution"], "autoRollback": true, "anomalyThreshold": 0.8, "maxPermissionScope": "read-write" }, "learning": { "enabled": true, "minSampleSize": 10, "abTestRatio": 0.1, "maxStrategyComplexity": 100 }, "monitoring": { "metricsInterval": 1000, "auditLevel": "detailed", "retentionDays": 90 } } ``` ## ID Generation Format: `TYPE-YYYYMMDD-XXX` - `INT`: Intent specification - `VIO`: Violation (failed validation) - `ANO`: Anomaly (behavioral deviation) - `LRN`: Learning (insight from execution) - `STR`: Strategy (new approach) - `RBK`: Rollback operation - `CHK`: Checkpoint Examples: `INT-20250115-001`, `VIO-20250115-A3F`, `LRN-20250115-002` ## Priority Guidelines | Priority/Severity | When to Use | |-------------------|-------------| | `critical` | Immediate security risk, data loss, system compromise | | `high` | Intent violation, unauthorized action, goal drift | | `medium` | Anomaly detected, suboptimal strategy, warning condition | | `low` | Minor deviation, optimization opportunity, observation | ## Best Practices ### Intent Specification 1. **Be specific** - Vague goals lead to validation failures 2. **List all constraints** - Implicit boundaries often get violated 3. **Define expected behavior** - Helps catch deviations early 4. **Set correct risk level** - Triggers appropriate approval gates ### Validation 1. **Validate early** - Before execution, not after 2. **Fail safe** - Block on doubt, don't assume permission 3. **Log all violations** - Even if they seem minor 4. **Review regularly** - Patterns emerge over time ### Learning 1. **Let it learn** - Requires sample size to be effective 2. **Monitor A/B tests** - Don't adopt blindly 3. **Safety first** - Reject strategies that reduce safety 4. **Promote proven patterns** - Turn learnings into permanent rules ### Audit 1. **Keep detailed logs** - Debugging requires context 2. **Archive old logs** - Retention policies prevent bloat 3. **Review anomalies** - Often reveal edge cases 4. **Share learnings** - Team benefits from documented patterns ## Detection Triggers Automatically apply intent security when: **High-Risk Operations**: - File deletion or bulk modifications - API calls with write permissions - Command execution with elevated privileges - Database modifications - Deployment operations **Autonomous Workflows**: - Multi-step task sequences - Background job execution - Scheduled automation - Agent-initiated operations **Learning Opportunities**: - Task completes successfully - Failure with identifiable cause - User provides correction - Better approach discovered ## Hook Integration (Optional) Enable automatic intent validation through agent hooks. ### Setup (Claude Code / Codex) Create `.claude/settings.json`: ```json { "hooks": { "UserPromptSubmit": [{ "matcher": "", "hooks": [{ "type": "command", "command": "./skills/self-improving-intent-security-agent/scripts/intent-capture.sh" }] }], "PostToolUse": [{ "matcher": "Bash|Edit|Write", "hooks": [{ "type": "command", "command": "./skills/self-improving-intent-security-agent/scripts/action-validator.sh" }] }] } } ``` ### Available Hook Scripts | Script | Hook Type | Purpose | |--------|-----------|---------| | `scripts/intent-capture.sh` | UserPromptSubmit | Prompts for intent specification | | `scripts/action-validator.sh` | PostToolUse | Validates actions against intent | | `scripts/learning-capture.sh` | TaskComplete | Captures learnings after tasks | See `references/hooks-setup.md` for detailed configuration. ## Quick Commands ```bash # Initialize agent structure mkdir -p .agent/{intents,violations,learnings,audit} # Count active intents grep -h "Status**: active" .agent/intents/*.md | wc -l # List high-severity violations grep -B5 "Severity**: high" .agent/violations/*.md | grep "^## \[" # Find learnings for file processing grep -l "Domain**: file_processing" .agent/learnings/*.md # Review recent rollbacks ls -lt .agent/audit/ROLLBACKS.md | head -5 # Check strategy adoption rate grep "Status**: adopted" .agent/learnings/STRATEGIES.md | wc -l ``` ## Examples See [examples/README.md](examples/README.md) for detailed usage examples: - Basic intent specification and validation - Handling violations and rollbacks - Learning from task outcomes - Strategy evolution through A/B testing - Security monitoring and anomaly detection ## References - [Architecture](references/architecture.md) - System design and components - [Intent Security](references/intent-security.md) - Validation and authorization - [Self-Improvement](references/self-improvement.md) - Learning mechanisms - [Hooks Setup](references/hooks-setup.md) - Automation configuration - [API Reference](references/api.md) - Programmatic usage ## Multi-Agent Support Works with Claude Code, Codex CLI, GitHub Copilot, and OpenClaw. See `references/multi-agent.md` for agent-specific configurations. ## Safety Guarantees ✓ Intent Alignment - Every action validated against goal ✓ Permission Boundaries - Cannot exceed authorized scope ✓ Reversibility - Checkpoint-based rollback ✓ Auditability - Complete action history ✓ Bounded Learning - Safety-constrained improvements ✓ Human Oversight - Approval gates for high-risk operations ## License MIT --- **Note**: This skill provides strong safety mechanisms but requires proper configuration and usage. Always: - Define clear, specific intents - Review violation logs regularly - Monitor learning effectiveness - Keep approval gates enabled for high-risk operations - Test in non-production environments first **Intent-based security is a powerful approach, but human judgment remains essential.**


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)