🛡️ AI Agent Skills Framework

The Physical Sandbox & Aesthetic Governance Suite for Coding Agents
Stop letting AI "vibe code." A contract-driven development, anti-style-leak, and runtime self-healing agent skill library for Cursor, Claude Code, Windsurf, and Copilot.

简体中文

---

💡 Why Do You Need It?

Under large contexts or complex coding workflows, AI coding agents often suffer from "Instruction Drift", resulting in:

• Evasion & Laziness: AI hardcodes inline styles (e.g. style="color: #fff") or pollutes structure layout files with raw hex/rgb constants.
• Coupled Styling: Skeleton layout structures (layout.css) and dynamic themes (theme.css) get combined, preventing easy rebranding.
• Runtime Exceptions: Generated web components crash due to improper lifecycle mounting.

🚨 Anti-Evasion Matrix

Scenario	Traditional Approach (Soft Rules)	This Framework (Hard Sandboxing)	Outcome
Absolute Path Leak	Prompts asking to "use relative links"	Skill Auditor Gate: skill_integrity_auditor.py blocks any skill containing absolute drive paths or local protocol links.	Enforced Portability
Hardcoded Inline Colors	Prompts asking to "use CSS variables"	DoD Gatekeeper: pipeline_validator.py scans and blocks any inline color styling in HTML or Web Components.	Strict Separated CSS
Fact Hallucination	Standard AI hallucinations in copywriting	Bidirectional Fact Lock: Cross-validates all page parameters against .extracted_facts.json and flags unmapped numbers.	Pure Fact Consistency
Broken Data Lineage	Hardcoded numbers without data trace	Data Lineage Validator: Blocks page integration if numerical facts lack explicit trace tags (data-fact-source).	100% Traceability
Skipping Pipeline Stages	Agent decides flow dynamically	Physical State Lock: Code changes are blocked unless the preceding stage in .pipeline_state.json is completed.	Step-by-Step Delivery
Subagent Concurrency	Race conditions and git conflicts	Sandbox Isolation Gate: Enforces workspace = branch isolation. Parent Agent acts as merge reviewer.	Safe Autopilot Merge

---

📂 Repository Structure

agent-skills/
├── README.md                      <-- Global English documentation
├── README_zh.md                   <-- Chinese documentation
├── config.json                    <-- Skills configurations
├── scripts/
│   ├── install.sh                 <-- One-click curl installer script
│   ├── pipeline_validator.py      <-- Static checkgate validator
│   ├── skill_integrity_auditor.py <-- Meta-skill compliance checker
│   └── generate_mdc.py            <-- MDC rules compiler
└── skills/
    ├── web-autobuild/
    │   ├── SKILL.md               <-- [Master] 10-Phase Web industrial pipeline
    │   └── sub-skills/
    │       ├── 1-content-extraction.md
    │       ├── 2-narrative-alignment.md
    │       ├── 3-data-structuring.md
    │       ├── 4-geo-anchors.md
    │       ├── 5-skeleton-html.md
    │       ├── 6-web-components.md
    │       ├── 7-style-separation.md
    │       ├── 8-merging-gatekeeper.md <-- Phase 8: Concurrency merging gateway
    │       ├── 9-runtime-debugging.md  <-- Phase 9: Runtime self-healing loop
    │       └── 10-vibecoding-defense.md <-- Phase 10: Vibe Coding facts lock and decision gateway
    ├── web-design/
    │   └── SKILL.md               <-- [Aesthetics] B2B visual design system and contrast token schema
    ├── skill-governance/
    │   ├── SKILL.md               <-- [Router] Central Central pipeline orchestrator & dynamic sub-skill router
    │   └── sub-skills/
    │       ├── workflow-contract.md <-- Safe temporary sandbox and ideation isolation specs
    │       ├── url-extractor.md     <-- Deduces intent and extracts website value using POE framework
    │       ├── static-auditor.md    <-- Formats audit schemas and blocks local path leaks
    │       ├── scenario-tester.md   <-- Enforces BaseScenarioTest 4-stage lifecycle assertions
    │       └── skill-generator.md   <-- Automatic skill generation and registration rules
    └── boilerplate-skill.md       <-- Standardized general skill boilerplate (derivation baseline)

---

⚡ Quick Start (1-Minute Setup)

Option 1: One-click Installer (Recommended)

Run the following command in the root of your target project to fetch the skills, deploy the checking scripts, and automatically compile local Cursor MDC rules:

curl -fsSL https://raw.githubusercontent.com/luoning/agent-skills/main/scripts/install.sh | bash

Option 2: Compile MDC Rules Locally

If you cloned this repository, compile the relative skills into Cursor native rules .cursor/rules/*.mdc:

python scripts/generate_mdc.py

Cursor will now dynamically load corresponding phase rules on-demand based on the files you modify, minimizing token consumption.

---

🔌 Core Developer Workflows

Flow 1: Direct Build Mode

Invoke web-autobuild directly. The agent scaffolds functional layouts, hooks custom components, runs static validation, and merges the pipeline.

Flow 2: Premium Design-Build Mode

1. Run web-design first. The Agent plans variables, typography letter-spacing, and transition curves.
2. Trigger web-autobuild afterwards. Visual properties are inherited as Phase 1 input variables, delivering a polished, high-fidelity landing page.

---

🔬 Core Gates Mechanisms

Gate 1: Project-level pipeline_validator.py

Fails integration pipeline if styling variables leak or facts mismatch:

• Block: Hex/RGB/HSL declarations or color keywords inside layout.css.
• Block: Colors declared inside inline HTML style attributes.
• Block: Unregistered business numerical fact or broken data lineage (data-fact-source).
• Self-Healing recovery: Automatically compiles a .pipeline_fix_suggestions.json mapping out actionable correction guidelines (such as approve_decision or correct_data_source) on failure.

Gate 2: Skill-level skill_integrity_auditor.py

Ensures portability and prevents private leaks in the skills repository:

• Block: Any local absolute path or disk drive prefixes (e.g. windows/unix absolute paths).
• Block: Syntax error in YAML frontmatter or missing trigger description.
• Block: Custom forbidden terms or path patterns listed in .skill_audit_blacklist (e.g. project-specific names or local directory names).

---

🚫 Custom Audit Blacklist (.skill_audit_blacklist)

To prevent project-specific parameters or local folder namespaces from leaking into your reusable skill files, populate the .skill_audit_blacklist file in the repository root:

• Add patterns to block (one keyword/path per line).
• Lines starting with # are treated as comments and ignored.
• The meta-auditor will block the verification check if any skill markdown file or generated MDC rule matches these words.