@moon791017/neo-skills 1.1.21 → 1.1.22

package/skills/neo-agent-protocol/SKILL.md

@@ -1,68 +0,0 @@
----
-name: neo-agent-protocol
-description: >
-  Use this skill when an AI agent is executing software development, code generation,
-  refactoring, debugging, or system architecture tasks to enforce strict harness principles,
-  self-verification gates, non-destructive editing, context collapse defense, and
-  human-in-the-loop boundaries.
----
-
-# Agent Execution Protocol & Harness Principles
-
-## Trigger On
-- An AI agent is assigned to build, refactor, debug, or architect software.
-- The user demands strict code quality, zero-hallucination verification, or non-destructive editing.
-- Long-running or multi-file development tasks requiring state persistence and context degradation defense.
-
-## Core Principle
-AI agents MUST operate as disciplined software engineering components, not unconstrained text generators. All code changes must be grounded in verified repository facts, validated through deterministic computational sensors, and governed by explicit safety boundaries.
-
-Humans design the scaffolding, evaluators, and constraints; agents execute 100% of the implementation and self-correct using log evidence.
-
-## The 5 Agent Harness Laws
-
-### 1. Feedforward First (Read Before Modify)
-- **Inspect worktree facts**: Inspect `AGENTS.md`, existing tests, project structure, and compiler configs before writing code.
-- **Never guess implementation details**: Never infer API signatures, struct fields, database schemas, or file paths. Inspect the authoritative source files first.
-- **Progressive disclosure**: Keep main execution context clean. Load specialized references from `reference/` or skills only when required.
-
-### 2. Deterministic Sensors & Verification Gates (Never Declare Victory Without Proof)
-- **Run verification commands**: After every edit, execute the corresponding deterministic local sensor (unit tests, typecheck, lint, build).
-- **Zero-fake pass**: Never patch errors by masking symptoms, swallowing exceptions, returning dummy fallbacks, commenting out broken assertions, or deleting failing unit tests.
-- **Log-driven diagnosis**: When a sensor fails, read the full un-truncated error log. Fix the root cause based on empirical log evidence.
-
-### 3. Dual Closed-Loop Execution Protocol
-- **Online Execution Loop**:
-  1. *Perceive*: Read user requirements and target code.
-  2. *Execute*: Apply atomic, minimal-diff code changes.
-  3. *Sense*: Run fast local verification sensors.
-  4. *Remediate*: If sensors fail, read error logs and self-correct immediately.
-- **Offline Evolution Loop**: Record recurring agent mistakes or fragile patterns, and convert them into permanent linter rules, test templates, or project guidelines.
-
-### 4. Context Collapse Defense & State Persistence
-- **Persist state on disk**: For long-horizon or multi-file tasks, maintain an explicit state file (`Plan.md`, `Progress.md`, or state JSON).
-- **Clean session handoffs**: When moving across major task milestones or session context resets, summarize completed sub-tasks, remaining risks, and next steps in a persistent handoff artifact.
-- **Keep diffs small**: Avoid massive single-step refactors that exhaust context windows.
-
-### 5. Human Decision Points & Safety Redlines
-Immediately pause and request human decision (Hand off to Human) when encountering:
-- Destructive operations (deleting core directories, dropping databases, resetting git history).
-- Secret / Token / Credential modifications or exposures.
-- High-risk production deployment, compliance, or architecture trade-offs.
-- Ambiguous or conflicting product requirements.
-
-## Workflow SOP
-
-1. **Phase 1: Perceive & Plan**
-   - Read local `AGENTS.md` and target source files.
-   - Break down the task into small, verifiable steps.
-2. **Phase 2: Atomic Execution**
-   - Modify code incrementally. Maintain existing styling and public API contracts.
-3. **Phase 3: Sensor Check**
-   - Execute test/lint/build commands. If failed, analyze logs and fix.
-4. **Phase 4: State Persistence**
-   - Update task progress in state markdown artifacts.
-5. **Phase 5: Human Handoff**
-   - Report concise summary of work done, sensor output proof, and any remaining risks.
-
-For detailed diagnostic checklists and antipattern prevention, read [reference/agent-execution-rules.md](reference/agent-execution-rules.md).

package/skills/neo-agent-protocol/reference/agent-execution-rules.md

@@ -1,58 +0,0 @@
-# Agent Execution Rules & Diagnostic Reference
-
-This reference provides concrete execution guidelines, diagnostic checklists, and antipattern rules for AI Agents performing software development tasks.
-
-## Agent Execution Checklist
-
-### 1. Pre-Execution Phase (Perception & Boundaries)
-- [ ] Have I checked `AGENTS.md` and repository guidelines?
-- [ ] Have I identified the project type, build toolchain, and primary language?
-- [ ] Do I have exact one-click verification commands (e.g., `npm test`, `pytest`, `cargo test`)?
-- [ ] Am I editing only files relevant to the task?
-
-### 2. Execution Phase (Code Generation & Modification)
-- [ ] Are code edits atomic, minimal, and targeted?
-- [ ] Did I preserve existing comments, public API contracts, and naming conventions?
-- [ ] Am I using explicit imports and verified symbols instead of guessing exports?
-- [ ] Did I avoid adding unrequested dependencies or third-party packages?
-
-### 3. Post-Execution Phase (Sensors & Verification)
-- [ ] Did I execute local tests, linters, or typecheck commands?
-- [ ] If a command failed, did I inspect the full error log instead of guessing?
-- [ ] Did I verify that all tests PASS before claiming completion?
-- [ ] Is there any unhandled exception or silent fallback introduced?
-
----
-
-## High-Risk Antipatterns (Strictly Forbidden)
-
-| Antipattern | Description & Risk | Required Alternative |
-| :--- | :--- | :--- |
-| **Silent Exception Swallowing** | Wrapping broken logic in empty `try/catch` or returning empty default arrays without logging. | Let errors surface or handle explicitly with verified logging. |
-| **Test Deletion / Suppression** | Commenting out or deleting failing unit test assertions to force a CI build to pass. | Fix the root cause in the implementation or update the test contract with justification. |
-| **Hallucinated Signatures** | Calling imported functions or methods without inspecting their definition file. | Read the target symbol definition using code search or view_file first. |
-| **Unverified Success Claim** | Reporting to the user that a bug is fixed or feature is complete without running verification commands. | Run exact test/build commands and present empirical sensor output. |
-| **Context Exhaustion Shift** | Modifying dozens of files in a single turn without saving progress. | Break tasks into small chunks and persist state in `Plan.md` or `Progress.md`. |
-
----
-
-## State Persistence & Session Handoff Template
-
-When executing multi-step tasks across session resets or context compaction, create or update a persistent progress file using this format:
-
-```markdown
-# Task Progress & State Persistence
-
-## Active Goal
-- [Description of current task objective]
-
-## Completed Milestones
-- [x] Milestone 1: Verified project structure and tests.
-- [x] Milestone 2: Implemented feature module.
-
-## Pending Verification
-- [ ] Milestone 3: Run full integration test suite.
-
-## Remaining Risks & Decisions
-- [Open question or architectural tradeoff needing human review]
-```

package/skills/neo-agentic-design/SKILL.md

@@ -1,89 +0,0 @@
----
-name: neo-agentic-design
-description: >
-  Use this skill when designing, evaluating, or implementing Agent workflows, prompt chains, routing, planning, reflection, multi-agent collaboration, memory management, or other framework-agnostic LLM orchestration patterns.
-license: MIT
-compatibility: No specific language runtime required; conceptual-only patterns.
-metadata:
-  version: "1.0.0"
-  type: "conceptual-design"
----
-
-# Neo Agentic Design
-
-This skill provides architectural concepts and orchestration patterns for building LLM Agent systems. It covers 21 core design patterns categorized into four themes. The orchestration logic remains abstract and independent of specific programming languages or frameworks.
-
-## Gotchas
-* **Over-engineering**: Prioritize simple prompt chains (Chapter 1) or routing (Chapter 2). Use complex multi-agent collaboration (Chapter 7) or hierarchical networks only when necessary to reduce token overhead.
-* **Reflection Infinite Loops**: When implementing reflection (Chapter 4) or self-correction (Chapter 12), enforce a maximum iteration limit (e.g., 3-5 iterations) to prevent the LLM from getting stuck in an infinite loop.
-* **Blocking Operations**: High-risk operations (such as direct database deletions or large fund transfers) must include a Human-in-the-Loop review gate (Chapter 13).
-* **Context Pruning State Loss**: When compressing context, protect critical agent instructions from being pruned to prevent behavioral degradation.
-
-## Workflow Checklist
-Progress:
-- [ ] Step 1: Analyze Requirements (define objectives, inputs, constraints, and complexity levels).
-- [ ] Step 2: Select Orchestration Patterns (load corresponding reference documents based on requirements).
-- [ ] Step 3: Plan System Components (determine memory, learning mechanisms, and protocol specifications).
-- [ ] Step 4: Define Resilience and Safety (establish exception handling, human review gates, and input/output guardrails).
-- [ ] Step 5: Draft Design Proposal (create system topology diagrams and describe the architecture).
-
-## Detailed Guidelines
-
-### Step 1 — Analyze Requirements
-Evaluate problem complexity (Level 1, 2, or 3) and confirm:
-1. **Latency Sensitivity**: For low-latency requirements, prioritize parallelization (Chapter 3) and routing (Chapter 2).
-2. **Task Fragility**: For strict sequential tasks or error-prone processes, use chaining (Chapter 1) or planning (Chapter 6).
-
-### Step 2 — Load Design Patterns (Progressive Loading)
-Load specific reference files as needed to avoid loading all concepts at once:
-* Base workflows (Prompt Chaining, Routing, Parallelization, Reflection, Tool Use, Planning, Multi-Agent Collaboration):
-  👉 **Load [base-workflows](references/base-workflows.md)**
-* System infrastructure (Memory Management, Learning and Adaptation, MCP, Goal Setting and Monitoring):
-  👉 **Load [system-components](references/system-components.md)**
-* Exception handling, HITL, RAG fact-grounding:
-  👉 **Load [resilience-hitl](references/resilience-hitl.md)**
-* Advanced safety, evaluation, prioritization, A2A communication, exploration and discovery:
-  👉 **Load [advanced-safety](references/advanced-safety.md)**
-
-### Step 3 — System Architecture Planning
-The design document must clearly document:
-1. **State Space**: Context window management method and division of short-term and long-term memory (cognitive/procedural memory).
-2. **Tool Boundaries**: Tool call schema protocols and sandbox rules.
-3. **Safety Boundaries**: Specific conditions for triggering human approval (HITL) or falling back to backup models.
-
----
-
-## Output Template (Agentic Architecture Design Proposal)
-
-When presenting agent designs to users, use this template format:
-
-```markdown
-# Agentic System Design Proposal: [System Name]
-
-## 1. Executive Summary
-* **Complexity Level**: [Level 1 / Level 2 / Level 3]
-* **Target Objective**: [System Goal]
-* **Key Constraints**: [Constraints such as latency, cost, security, etc.]
-
-## 2. Core Orchestration Architecture
-* **Selected Patterns**: [e.g., Router -> Parallel Agents -> Synthesizer]
-* **Workflow Description**: [System data flow and control flow description]
-
-### Topology Diagram (Mermaid)
-```mermaid
-[Mermaid diagram representing the Agent Loop / Topology]
-```
-
-## 3. Reference Patterns Applied
-* **[Pattern Name] (Chapter X)**: [Specific application and rationale in the system]
-* **[Pattern Name] (Chapter Y)**: [Specific application and rationale in the system]
-
-## 4. Resilience, Safety & HITL Rules
-* **Exception Recovery**: [Handling flow for API timeouts, rate limits, and JSON formatting errors]
-* **Human-in-the-Loop Gates**: [Conditions triggering human review]
-* **Guardrails**: [Input filtering and output validation mechanisms]
-
-## 5. Next Steps / Implementation Roadmap
-1. [Step 1]
-2. [Step 2]
-```

package/skills/neo-agentic-design/evals/eval_queries.json

@@ -1,58 +0,0 @@
-[
-  {
-    "query": "I need to design a system that routes incoming user queries to specialized LLM prompts depending on their category.",
-    "should_trigger": true
-  },
-  {
-    "query": "How do I implement reflection and self-correction in a multi-agent system to make it write better code?",
-    "should_trigger": true
-  },
-  {
-    "query": "Can you review my LLM orchestration workflow? It currently uses prompt chaining but has high latency.",
-    "should_trigger": true
-  },
-  {
-    "query": "I want to set up a Model Context Protocol (MCP) server for my agent so it can read local files.",
-    "should_trigger": true
-  },
-  {
-    "query": "What is the best way to handle long-term semantic memory and episodic memory in an autonomous agent?",
-    "should_trigger": true
-  },
-  {
-    "query": "Please design a pipeline workflow for generating technical reports, with a human-in-the-loop validation step.",
-    "should_trigger": true
-  },
-  {
-    "query": "How does dynamic re-prioritization work when an agent has conflicting goals?",
-    "should_trigger": true
-  },
-  {
-    "query": "Review the exception handling and recovery mechanism in my LLM agent loop.",
-    "should_trigger": true
-  },
-  {
-    "query": "I need to write a Python script that calculates the Fibonacci sequence using recursion.",
-    "should_trigger": false
-  },
-  {
-    "query": "What is the difference between supervised learning and reinforcement learning in traditional machine learning?",
-    "should_trigger": false
-  },
-  {
-    "query": "How do I configure my local PostgreSQL database on macOS?",
-    "should_trigger": false
-  },
-  {
-    "query": "Write a CSS stylesheet for a dark mode website.",
-    "should_trigger": false
-  },
-  {
-    "query": "I want to build a simple web scraper in Python using beautifulsoup4.",
-    "should_trigger": false
-  },
-  {
-    "query": "How do I write a prompt to make ChatGPT act like a professional English translator?",
-    "should_trigger": false
-  }
-]

package/skills/neo-agentic-design/evals/evals.json

@@ -1,27 +0,0 @@
-{
-  "skill_name": "neo-agentic-design",
-  "evals": [
-    {
-      "id": 1,
-      "prompt": "Design an agentic system that generates monthly financial reports. It must parse transaction raw data, categorize expenses, draft a report, let a human reviewer approve/edit the draft, and then output a final PDF. Minimize latency and ensure high accuracy.",
-      "expected_output": "An Agentic System Design Proposal containing Routing, Chaining, and Human-in-the-Loop patterns, structured with the standard output template.",
-      "assertions": [
-        "The output starts with 'Agentic System Design Proposal' or matches the template format",
-        "The proposal mentions Routing, Chaining, and Human-in-the-Loop patterns",
-        "The proposal contains a Mermaid sequence or flowchart diagram representing the topology",
-        "The proposal lists specific Gotchas or risks like latency and cost control"
-      ]
-    },
-    {
-      "id": 2,
-      "prompt": "I need to design a system that reviews incoming code commits for potential security vulnerabilities and performance bottlenecks. It needs to check thousands of commits daily and must fail-safely if any analysis tool crashes.",
-      "expected_output": "An Agentic System Design Proposal containing Parallelization, Routing, Guardrails, and Exception Recovery patterns, structured with the standard output template.",
-      "assertions": [
-        "The proposal includes Parallelization and Exception Recovery patterns",
-        "The proposal provides a Mermaid topology diagram showing parallel evaluation and a merge point",
-        "The proposal includes specific Exception Handling rules for crashed analysis tools",
-        "The proposal includes Guardrails policies for input/output sanitization"
-      ]
-    }
-  ]
-}

package/skills/neo-agentic-design/references/advanced-safety.md

@@ -1,158 +0,0 @@
-# Advanced Execution, Guardrails & Safety
-
-This document provides conceptual designs for advanced execution, guardrails, and safety patterns, covering agent-to-agent (A2A) communication, resource-aware optimization, reasoning techniques, guardrails, evaluation and monitoring, prioritization, and scientific exploration.
-
----
-
-## Chapter 15: Inter-Agent Communication (A2A)
-
-### 1. Definition
-An open agent communication protocol across frameworks and technology stacks. Uses standard HTTP and JSON-RPC formats to enable agent declaration, task delegation, and data exchange across different networks.
-
-### 2. Core Components
-* **Agent Card**: A JSON declaration containing the agent name, version, endpoint URL, multimodal capabilities, and skills.
-* **Task Mechanism**: Defines collaboration as a "Task" with a lifecycle state (Submitted, Working, Completed, Failed), tracked using a `contextId` for multi-turn conversation context.
-* **Communication Modes**:
-  * **Synchronous**: Direct invocation with immediate response.
-  * **Asynchronous Polling**: Submit a task to obtain a Task ID and periodically query status.
-  * **Streaming (SSE)**: Receive partial outputs in real time via Server-Sent Events.
-  * **Webhook**: Actively push notifications to a specified URL upon task completion.
-
-### 3. Problems Addressed
-* Heterogeneous framework silos: Solves communication barriers between different agent frameworks.
-* Distributed collaboration barriers: Enables agents on different servers to safely delegate tasks.
-
----
-
-## Chapter 16: Resource-Aware Optimization
-
-### 1. Definition
-Monitors computation, latency, and financial costs (tokens/API calls) in real time during agent execution. Dynamically switches between models with different capabilities or prunes context based on budget and latency constraints.
-
-### 2. Problems Addressed
-* API cost overruns: Avoids using expensive reasoning models for simple queries.
-* Rate limits and overload: Executes fallbacks and backup plans when the primary model is limited or overloaded.
-
-### 3. Workflow
-```mermaid
-graph TD
-    Query[User Query] --> Router{Router LLM}
-    Router -->|1. Simple Query| CheapModel[Lightweight Model]
-    Router -->|2. Complex Reasoning| ExpensiveModel[High-tier Reasoning Model]
-    Router -->|3. Real-time Info| SearchTool[Real-time Search Tool]
-    CheapModel --> Checker[Critique Agent: Quality Eval]
-    ExpensiveModel --> Checker
-    Checker -->|Fail| Fallback[Fallback Plan]
-    Checker -->|Pass| Output[Final Output]
-```
-
----
-
-## Chapter 17: Reasoning Techniques
-
-### 1. Definition
-Architectural techniques that allocate more computational resources at inference time to explicitly expand the agent's thought process. Covers step-by-step decomposition, tree-search path planning, code-assisted execution, and ReAct loops.
-
-### 2. Six Core Reasoning Patterns
-* **Chain of Thought (CoT)**: Guides the model to reason step-by-step to decompose complex problems.
-* **Tree of Thoughts (ToT)**: Represents the reasoning space as a tree, supporting backtracking and multi-path parallel evaluation.
-* **Reasoning and Action (ReAct)**: Interleaves tool execution with reasoning steps (Thought -> Action -> Observation -> Thought ... -> Finish).
-* **Program-Aided Language Models (PALMs)**: Offloads precise mathematical calculations to a secure code sandbox and interprets the results to eliminate calculation hallucinations.
-* **Multi-Agent Debate (Chain/Graph of Debates)**: Employs multiple agents to debate a problem across several turns, using consensus or strong logical conclusions as the final answer.
-* **Scaling Inference Law**: Uses multi-path generation, self-correction, or extended thinking paths during the inference stage, allowing smaller models to achieve performance comparable to a single generation of a larger model.
-
----
-
-## Chapter 18: Guardrails & Safety Patterns
-
-### 1. Definition
-Deploys multiple layers of filtering and defense at the input, tool execution, and output stages to ensure system compliance, safety, and protection against jailbreak attacks, prompt injection, and tool privilege escalation.
-
-### 2. Multi-Layer Defense Flow
-```mermaid
-graph TD
-    Input[User Input] --> InputGuard[1. Input Guardrails: Jailbreak/Injection Detection]
-    InputGuard -->|Violation| Block[Access Denied]
-    InputGuard -->|Safe| LLM_Core[2. Core Agent Reasoning]
-    LLM_Core -->|Call Tool| ToolCallback[3. Pre-execution Tool Validation]
-    ToolCallback -->|Reject| LLM_Core
-    ToolCallback -->|Approve| ToolExec[Tool Execution]
-    ToolExec --> OutputGen[Output Generation]
-    OutputGen --> OutputGuard[4. Output Guardrails: PII/Toxicity Filter]
-    OutputGuard -->|Safe| User[Deliver to User]
-    OutputGuard -->|Violation| Redaction[Redaction/Block/Self-Correction]
-```
-
-### 3. Problems Addressed
-* Prompt jailbreaks: Prevents users from guiding the agent to perform unauthorized or harmful actions.
-* Privilege escalation: Follows the principle of least privilege to prevent agents from unauthorized data modification or account deletion.
-
----
-
-## Chapter 19: Evaluation and Monitoring
-
-### 1. Definition
-Systematically measures and audits agent execution quality, trajectories, resource consumption, and drift. Evaluates the execution trajectory rather than just the final answer for non-deterministic systems.
-
-### 2. Three Core Evaluation Aspects
-* **Objective Metrics Monitoring**: Logs latency, token consumption, and API success rates.
-* **Trajectory Evaluation**: Compares action sequences with standard SOPs using exact matching, ordered matching, or unordered matching.
-* **LLM-as-a-Judge**: Uses an independent LLM to score answers based on specific rubrics and outputs structured feedback.
-
-### 3. Advanced Pattern: AI Contractor / Contract Pattern
-Resolves prompt drift and responsibility ambiguity:
-```mermaid
-graph TD
-    User[User] -->|1. Initiate Draft Contract| Contractor[Contractor Agent]
-    Contractor -->|2. Self-Analysis & Evaluation| Analyze[Analyze clauses, scope, cost, dependencies]
-    Analyze -->|3. Negotiate Feedback| User
-    User -->|4. Approve & Sign| Execute[5. Execution: Self-test & verify]
-    Execute -->|6. Decompose Tasks| SubContracts[Sub-contracts]
-    SubContracts --> SubAgents[Sub-agents]
-    Execute -->|7. Deliver Deliverables| User
-```
-
----
-
-## Chapter 20: Prioritization
-
-### 1. Definition
-Sorts and dynamically schedules the execution order of multiple goals and tasks when the agent is faced with resource constraints or limited budgets.
-
-### 2. Problems Addressed
-* Deadlocks and lack of focus: Prevents delays in critical tasks caused by prioritizing minor ones.
-* Inadequate crisis response: Ensures the agent can dynamically switch task context when high-priority events (e.g., safety alerts) occur.
-
-### 3. Prioritization Metrics
-* **Urgency**: Time sensitivity (closeness to deadline).
-* **Importance**: Impact on accomplishing the ultimate goal.
-* **Dependencies**: Whether the task is a prerequisite for other tasks.
-* **Cost-Benefit Ratio**: Expected payoff relative to consumed resources.
-
-### 4. Mechanism
-Tasks are scored and entered into a Priority Queue, executed sequentially by the planner. The system recalculates weights and re-orders the queue (Dynamic Re-prioritization) or interrupts the current task when the environmental state changes.
-
----
-
-## Chapter 21: Exploration and Discovery
-
-### 1. Definition
-Enables the agent to proactively explore unknown domains (Unknown Unknowns), generate new knowledge, design experiments, and prove hypotheses.
-
-### 2. Multi-Agent Scientific Discovery Flow
-```mermaid
-graph TD
-    Goal[Exploration Goal] --> GenAgent[1. Generation Agent]
-    GenAgent -->|Propose Hypothesis| RefAgent[2. Reflection Agent]
-    RefAgent -->|Peer Review / Correction Suggestions| GenAgent
-    RefAgent -->|Accepted Draft| RankAgent[3. Ranking Agent]
-    RankAgent -->|Elo Tournament Debate| BestHypotheses[Select Best Hypotheses]
-    BestHypotheses --> EvoAgent[4. Evolution Agent]
-    EvoAgent -->|Concept Merging & Non-linear Exploration| AdvancedHypo[Advanced Hypotheses]
-    AdvancedHypo --> LabAgent[5. Lab Agent]
-    LabAgent -->|Execute Code/Simulation/Analysis| FinalReport[6. Final LaTeX Report]
-```
-
-### 3. Trade-offs
-* **Pros**: Explores unknown topics autonomously, discovering insights that exceed human experience.
-* **Cons**: High uncertainty and heavy token consumption; requires strict safety guardrails to prevent generating hazardous protocols.