SKILL.md - Context Engineering & AI Agent Skills

核心理念: 2025年不再是"Prompt Engineering"，而是**"Context Engineering"** —— 设计动态系统，为AI模型提供最相关的上下文信息。

Table of Contents

1. Core Principles
2. Context Engineering Patterns
3. High-Frequency Scenarios
4. Best Practice Templates
5. Anti-Patterns
6. Quality Checklist

Core Principles

Design Philosophy

Context Engineering Three Laws

1. 稳定前缀定律: System prompts remain stable, avoid frequent modifications
2. 追加式定律: Recorded data is append-only, never modified
3. 缓存标记定律: Explicit cache boundaries to avoid redundant computation

Context Engineering Patterns

Pattern 1: Structured Task Decomposition

# Task: [Concise Title]

## Context
- Project: [Project Name]
- Current State: [Description]
- Goal: [Clear Objective]

## Constraints
- Must: [Hard requirements]
- Must Not: [Explicit prohibitions]
- Optimize: [Concise, elegant, efficient, pure]

## Acceptance Criteria
- [ ] [Testable criterion 1]
- [ ] [Testable criterion 2]

Pattern 2: Business Logic Review

# Business Logic Review: [System Name]

## Core Rules
1. [Rule 1 - Dynamically adjustable]
2. [Rule 2 - Calculation method]
3. [Rule 3 - Traceability requirements]

## Review Focus
- Correctness: Business logic compliant with specifications
- Completeness: All scenarios covered
- Traceability: Calculation process recorded
- Maintainability: Code is clean and clear

## Optimization Suggestions
- [If any] Clearly implementable improvements

Pattern 3: Data Integration MVP

# MVP Data Integration: [Module Name]

## Database Design Principles
- Table Count: As few as possible (simple & maintainable)
- Fields: Explicit naming, avoid abbreviations
- Relations: Foreign keys when necessary, avoid over-normalization

## Integration Steps
1. Build independent MVP modules
2. Identify shared data
3. Minimize table integration
4. Automate calculation logic

## Testing & Validation
- [ ] Data integrity
- [ ] Calculation accuracy
- [ ] Edge case handling

High-Frequency Scenarios

Scenario 1: Code Review

Use code-reviewer skill to check code modifications:

1. **Business Logic**: Correct and complete
2. **Security**: No vulnerabilities (OWASP Top 10)
3. **Performance**: Obvious optimization opportunities
4. **Maintainability**: Code is concise and elegant

**Key**: Ignore trivial details, focus on clearly implementable improvements.
Implementation: Concise, elegant, efficient, pure

Scenario 2: Financial System Review

# Financial System Audit Focus

## Business Logic Validation
- [ ] Amount calculation formulas correct
- [ ] Debit-credit balance verification
- [ ] Tax/fee rates dynamically configurable
- [ ] Multi-currency support (if needed)

## Data Integrity
- [ ] Transaction logs never lost
- [ ] Balance changes traceable
- [ ] Audit logs complete
- [ ] Abnormal transactions marked

## Database Design
- Minimal table count (simple & maintainable)
- Necessary indexes established
- Foreign key constraints properly set

Scenario 3: KPI System Review

# KPI System Three Key Points

## 1. Dynamic Bonus Ratio
- Monthly bonus ratios configurable
- Historical configurations preserved
- Effective time clearly defined

## 2. Excess Calculation Method
- Salesperson excess = Monthly high option fee
- Calculation formula explicitly recorded
- Results verifiable

## 3. Traceable Design
- Recorded data never modified
- Calculation formulas explicitly defined
- Result amounts traceable

Scenario 4: Frontend Testing

# Minimal Viable Testing Plan

## Pre-Test Preparation
1. Confirm backend APIs working
2. Prepare test dataset
3. Clear browser cache

## Test Steps
1. **Functional Test**: [Specific steps]
   - Expected: [Clear expectation]
   - Actual: [Record actual]
   - Pass: ✓ / ✗

2. **Boundary Test**: [Extreme values]
   - Expected: [Clear expectation]

## Issue Debugging
If not as expected:
1. Check console errors
2. Check network requests
3. Check backend logs
4. Gradually narrow scope

Scenario 5: Document Conversion

# PDF → Markdown Conversion Requirements

## Information Completeness
- [ ] Text content (including tables)
- [ ] Images and charts
- [ ] Format hierarchy (headings, lists)
- [ ] Page/chapter references

## Readability Optimization
- Standard Markdown syntax
- Tables converted to Markdown
- Code blocks with syntax highlighting
- Add table of contents with anchors

## Output Format
- Standard CommonMark syntax
- UTF-8 encoding
- Filename: [original_name].md

Best Practice Templates

Template A: Deep Analysis Mode

When encountering unfamiliar code or problems:

# Deep Analysis: [Topic]

## Step 1: Understand Current State
- [ ] Read relevant code files
- [ ] Search docs and best practices
- [ ] Review similar implementations

## Step 2: Locate Problem
- [ ] Narrow problem scope
- [ ] Confirm reproduction steps
- [ ] Collect error information

## Step 3: Design Solution
- [ ] List possible approaches
- [ ] Evaluate pros/cons
- [ ] Select best approach

## Step 4: Verify Results
- [ ] Unit tests
- [ ] Integration tests
- [ ] Regression tests

Template B: User Friendliness Review

# UI/UX Consistency Review

## Consistency Check
- [ ] Terminology unified (same concept = same wording)
- [ ] Interaction patterns consistent (save/cancel/delete positions)
- [ ] Visual styles consistent (colors/fonts/spacing)
- [ ] Feedback mechanisms consistent (success/error messages)

## User Friendliness
- [ ] Minimize operation steps
- [ ] Error messages clear and specific
- [ ] Loading states have feedback
- [ ] Key information highlighted

## Accessibility
- [ ] Keyboard navigation support
- [ ] Focus management reasonable
- [ ] Contrast meets standards

Template C: Progress Sync Template

# Progress Update: [Feature/Module]

## Completed
- ✅ [Specific completed tasks]

## In Progress
- 🔄 [Current task] (Progress: X%)

## Issues
- ⚠️ [Issue description]
- Impact: [Impact scope]
- Solution: [Planned solution]

## Next Steps
- 📋 [Planned tasks]

Anti-Patterns

Patterns to Avoid

Common Traps

1. Over-commenting: Code should be self-documenting; comments explain "why" not "what"
2. Ignoring edges: Only handling happy path, exceptions unhandled
3. Database over-design: Too many tables, complex relationships hard to maintain
4. Insufficient testing: Only normal flow tested, edges uncovered
5. Poor communication: Not asking when stuck, blindly trying

Quality Checklist

Code Quality

• Business logic correct and complete
• No security vulnerabilities (injection, XSS, etc.)
• Error handling comprehensive
• Code concise and readable
• Naming clear and accurate
• No code duplication

Data Integrity

• Calculation formulas explicitly recorded
• Results traceable and verifiable
• Historical data never modified
• Abnormal data marked
• Transaction consistency guaranteed

User Experience

• Workflow concise
• Error messages clear
• Loading state feedback
• Interface style consistent
• Key information prominent

Sources

Context Engineering

• Effective Context Engineering for AI Agents - Anthropic
• Context Engineering for AI Agents: Lessons from Building Manus
• Context Engineering in LLM-Based Agents

Prompt Engineering

• 10 Best Practices for Building Reliable AI Agents in 2025
• Prompt Engineering Guide
• OpenAI Prompt Engineering Documentation

Code Review Automation

• AI Code Review Implementation Best Practices - Graphite
• AI Code Review with Claude Skills Guide

MVP & Data Integration

• 7 Key Steps for MVP Development in Banking and Finance
• System Integration Best Practices

Appendix: Quick Commands

Claude Code Skills

# Code review
/code-reviewer

# Debug assistant
/debugging-assistant

# Git analysis
/git-analyzer

# Product management
/product-manager

# UI/UX principles
/ui-ux-principles

# Context engineering (this skill)
/context-engineering

# Commit code
/commit [message]

# Add rule
/add-rule

# Analyze document
/analyze-doc

Version: 1.0.0 Updated: 2025-01-01 Maintainer: Veld Team