Agent Native Product

Agent-Native Product Transform

ROLE: AG is the transformation orchestrator. AG dispatches Scout (assessment), Transformer (generation), and Auditor (verification) subagents via task-delegate. AG does NOT generate project files itself — all generation is done by subagents.

[!IMPORTANT] This skill transforms a project's agent-facing interface — API design, documentation, environment abstraction, observability. It does NOT modify application logic or development process infrastructure. For dev-process changes, use agent-native-devflow.

When to Trigger

• User says "让 agent 更好用这个 SDK"、"改造 API"、"agent-friendly"
• User wants to improve API/CLI usability for LLM agents
• User wants to generate AGENTS.md / CLAUDE.md for an existing project
• After deep-analysis reveals product-layer gaps (A2-A5)

Maturity Model

A1 (Conceptual Model) is a prerequisite. If the underlying conceptual model has poor orthogonality, incomplete abstractions, or missing convenience layers, then agent-native docs and tooling built on top will be fragile. Use concept-model-review skill for deep A1 assessment; results feed into this skill's ASSESS phase.

Dimensions

[!TIP] A1 assessement is handled by concept-model-review skill (DISCOVER → EVALUATE → PATH DESIGN). Its output (concept_map.md + evaluation + opening path) feeds directly into this skill's Phase 1 ASSESS as pre-existing context. If concept-model-review was already run, Scout can skip A1 and use its output.

[!NOTE] A6 is optional. Include it when: (1) the project has a runnable workflow, (2) you want to catch runtime-only issues that static assessment misses. Smoke tests on quant_trading showed the most severe bugs (ZeroDivisionError, wrong column names, EOD state traps) were invisible to code reading.

Prompt Files

All subagent prompts live in prompts/. AG reads the template, fills {{PLACEHOLDERS}}, and passes the result to task-delegate.

3-Phase Workflow

ASSESS (Scout) → [user ✓] → TRANSFORM (per-dim) → [user ✓] → AUDIT (独立验证)

Phase 1: ASSESS

1. AG detects project metadata: language, build system, entry points
2. AG prepares Scout prompt from prompts/scout.txt:
   • Fill {{PROJECT_PATH}}, {{LANGUAGE}}, {{OUTPUT_PATH}}
   • If A6 enabled: read prompts/scout_a6_agent_trial.txt and inject into {{AGENT_TRIAL_SECTION}}
   • If A6 disabled: replace {{AGENT_TRIAL_SECTION}} with empty string
3. AG dispatches Scout via task-delegate (read-only assessment)
4. AG reads Scout output → writes maturity_report.md (L0-L3 per dimension)
5. ✅ USER CHECKPOINT: present maturity scores, ask which dimensions to transform

TRANSFORM_ID="{YYYYMMDD_HHMM}_{project_name}"
TRANSFORM_DIR="${HOME}/.agent-native-transform/${TRANSFORM_ID}/product"
mkdir -p "${TRANSFORM_DIR}/assess"

# AG reads prompts/scout.txt, fills placeholders, writes to task dir
# Launch via task-delegate
bash ~/agent-skills/task-delegate/scripts/task_launch.sh \
  ${TRANSFORM_ID}_scout ${PROJECT_DIR} --backend cc

Phase 2: TRANSFORM

AG processes selected dimensions. Recommended order: A1 first (API quality is foundation), then A5 (docs), A2 (surface), A4 (observability), A3 (environment).

Per dimension, AG:

1. Reads the dimension-specific prompt from prompts/transform_{dim}.txt
2. Fills placeholders with project context + assessment findings
3. Dispatches Transformer via task-delegate
4. Reads output, verifies generated files
5. ✅ USER CHECKPOINT per dimension

Phase 3: AUDIT

Executor ≠ Verifier: Auditor runs on a DIFFERENT backend than Transformer.

AG reads prompts/auditor.txt and dispatches the Auditor. The auditor prompt has expanded checks that align with A5 mandatory documentation items and A6 Agent Trial.

Friction Log Standard

[!TIP] The standard friction log format is defined in prompts/friction_log_template.txt. It is used by Scout (A6 sub-task) and Auditor (A6 audit). AG should also use this format when documenting friction from any manual testing.

Severity classification:

• 🔴 Blocker: Crashes, data loss, cannot proceed
• 🟡 Misleading: Docs say X but reality is Y
• 🟢 Missing: Feature absent, user writes boilerplate
• ⚪ Friction: Works but confusing or surprising

Mandatory Rules

1. ASSESS before TRANSFORM — no generation without understanding current state
2. User checkpoint after ASSESS — user selects dimensions + targets
3. User checkpoint after each TRANSFORM batch — user reviews generated files
4. Executor ≠ Verifier — Auditor on different backend than Transformer
5. No fabrication — if no real failures exist, use <!-- TODO: Add after real incidents -->
6. Verify all references — every path/command in generated docs must actually exist
7. CLAUDE.md length limit — ≤40 lines simple project, ≤80 lines complex
8. Prompts in files — all subagent prompts live in prompts/, not inline in SKILL.md

Anti-Patterns

❌ AG generates CLAUDE.md directly instead of dispatching subagent
   → AG is orchestrator. All file generation goes through task-delegate

❌ Fabricating anti-patterns or troubleshooting entries
   → Empty honesty > fabricated completeness. Use <!-- TODO --> markers

❌ Single monolithic "transform everything" prompt
   → Each dimension gets its own focused prompt file

❌ Transformer and Auditor are the same subagent session
   → Violates Executor ≠ Verifier. Auditor must have fresh eyes

❌ Listing commands in CLAUDE.md without verifying they work
   → Every command must be tested with command -v or --help

❌ Generating 200-line CLAUDE.md for a 10-file project
   → Match doc size to project complexity. Overgeneration breeds staleness

❌ Skipping ASSESS and jumping to TRANSFORM
   → Without baseline, can't measure improvement or set targets

❌ Inlining prompts in SKILL.md instead of using prompts/ files
   → Prompts are versioned separately, easier to iterate

❌ Skipping A6 Agent Trial when user opted in, reporting only static assessment
   → Static reading misses runtime-only bugs (ZeroDivisionError, state traps, wrong column names)

Troubleshooting

Composability