Agent Skills: Analysis mode with JSON output

Section 1: Intent Detection & Routing

Detect user intent, route to appropriate workflow.

| Intent | Keywords | Route To | |--------|----------|----------| | Full skill creation | "create skill", "build skill", "new skill" | Section 2 | | Subagent creation | "create subagent", "build subagent", "new subagent" | Section 6 | | Validation | "validate", "check quality" | Section 3 | | Decision | "Skills vs Subagents", "decide", "which to use" | Section 4 | | Migration | "convert", "migrate doc" | Section 5 | | Single tool | "validate only", "estimate tokens", "scan" | Section 7 |

PROCEED to corresponding section after intent detection.

Stop Condition (Mandatory):

• If multiple routes match or intent is ambiguous: stop, ask user to choose one route.
• Do not proceed until user confirms the route.

Workflow Value: Research-driven approach validates design before building. Sequential steps with checkpoints produce 9.0/10+ quality vs ad-hoc creation.

Section 2: Creation Workflows (Dual Mode)

Prerequisites: Skill description provided, workspace available.

Mode Selection (Required at Start)

Detect or prompt for workflow mode before running the creation flow.

Stop Condition (Mandatory):

• If mode is not explicitly provided: stop and ask "Do you want fast or full mode?"
• Do not continue until user confirms the mode.

| Mode | Steps | Validation | Quality Target | Time | |------|-------|------------|----------------|------| | fast | 10 | Structural only | >=9.0/10 | <10 min | | full | 14 | Structural + Behavioral | >=9.0/10 and behavioral >=7.0 | <20 min |

No implicit default mode is allowed when mode is not explicitly known.

Workflow A: Fast Mode (10 Steps)

Use when .skillkit-mode contains fast or marker does not exist.

→ READ references/section-2-fast-creation-workflow.md IN FULL before starting. Create a task for each step listed in that file, then follow them in order. The outline below is a summary only — the reference file is authoritative.

Phase 1: Decision & Research

• Step 0: Decide approach (decision_helper.py)
• Step 1: Research and proposals
• Step 2: User validation
• Stop Condition: Stop and request user approval before continuing to Step 3.

Phase 2: Creation

• Step 3: Initialize skill (init.py skill <name> --mode fast)
• Step 4: Create content

Phase 3: Structural Validation

• Step 5: Validate skill (validate_skill.py) — runs structure + security + tokens in one call

Phase 4: Packaging

• Step 6: Progressive disclosure check
• Step 7: Generate tests (test_generator.py)
• Step 8: Quality assessment (quality_scorer.py)
• Step 9: Package (package_skill.py)

Workflow B: Full Mode (14 Steps)

Use when .skillkit-mode contains full.

→ READ references/section-2-full-creation-workflow.md IN FULL before starting. Create a task for each step listed in that file, then follow them in order. The outline below is a summary only — the reference file is authoritative.

Phase 1: Decision and Research

• Step 0: Decide approach (decision_helper.py)
• Step 1: Research and proposals
• Step 2: User validation
• Stop Condition: Stop and request user approval before continuing to Step 3.

Phase 2: Behavioral Baseline (extra vs fast)

• Step 3 (RED): Run pressure scenarios without skill → Load references/section-2-full-creation-workflow.md → section "Full Mode Behavioral Testing Protocol" (mandatory)
• Step 4: Document baseline failures

Phase 3: Creation

• Step 5: Initialize skill (init.py skill <name> --mode full)
• Step 6: Create content addressing baseline failures

Phase 4: Behavioral Verification (extra vs fast)

• Step 7 (GREEN): Run scenarios with skill → Load references/section-2-full-creation-workflow.md → section "Full Mode Behavioral Testing Protocol" (mandatory)
• Step 8: Fix gaps

Phase 5: Structural Validation

• Step 9: Validate skill (validate_skill.py) — runs structure + security + tokens in one call

Phase 6: Refinement (extra vs fast)

• Step 10 (REFACTOR): Combined pressure tests → Load references/section-2-full-creation-workflow.md → section "Full Mode Behavioral Testing Protocol" (mandatory)
• Step 11: Close loopholes

Phase 7: Packaging

• Step 12: Quality assessment (quality_scorer.py --format json) — behavioral score derived from Steps 3/7/10 subagent results, not from --behavioral flag
• Step 13: Package (package_skill.py)

Mode Detection

Priority order:

1. Explicit flag: --mode fast or --mode full
2. Skill marker: .skillkit-mode file content
3. If unknown: stop and ask user to choose fast or full

Section 3: Validation Workflow (Overview)

Use when: Validating existing skill

Steps: Execute validation subset (Steps 3-6)

1. Validate skill — structure + security + tokens (validate_skill.py, no flags needed)
2. Progressive disclosure check
3. Test generation (optional)
4. Quality assessment (quality_scorer.py)

Note: --security-only and --tokens-only flags are available for Section 7 individual tool use, not for workflow validation steps.

For detailed workflow: See references/section-3-validation-workflow-existing-skill.md

Section 4: Decision Workflow (Overview)

Use when: Uncertain if Skills is right approach

CRITICAL: Agent MUST create a temp JSON file first. The decision_helper.py script does NOT accept inline JSON strings - it requires a file path to a JSON file.

Step-by-step invocation: See references/section-4-decision-workflow-skills-vs-subagents.md

Accuracy: Highest (90-95% confidence).

Process:

1. Run decision_helper.py with json file.
2. Answer interactive questions
3. Receive recommendation with confidence score
4. Proceed if Skills recommended (confidence >=75%)
5. If confidence <75% or recommendation is uncertain, stop and ask user whether to continue, switch route, or refine inputs.

For detailed workflow: See references/section-4-decision-workflow-skills-vs-subagents.md

Section 6: Subagent Creation Workflow (Overview)

Use when: Creating new subagent (user explicitly asks or decision workflow recommends)

Prerequisites: Role definition clear, workspace available Quality Target: Clear role, comprehensive workflow, testable examples Time: <15 min with template

8-Step Process:

STEP 0: Requirements & Role Definition

• Answer: Primary role? Trigger conditions? Tool requirements?
• Choose subagent_type from predefined list

STEP 1: Initialize Subagent File

• Tool: python scripts/init.py subagent subagent-name --path ~/.claude/agents
• Creates: ~/.claude/agents/subagent-name.md with template
• Important: Subagents are individual .md files (not directories)
• Stop Condition: If target file already exists, stop and ask whether to overwrite, rename, or cancel.

STEP 2: Define Configuration

• Edit YAML frontmatter (name, description, type, tools, skills)
• Configure tool permissions (minimal but sufficient)

STEP 3: Define Role and Workflow

• Role definition section
• Trigger conditions (when to invoke)
• Multi-phase workflow

STEP 4: Define Response Format

• Output structure template
• Tone and style guidelines
• Error handling

STEP 5: Add Examples

• At least 1 complete example
• Input/Process/Output format

STEP 6: Validation

• YAML validity check
• Structure verification
• Completeness review

STEP 7: Testing

• Test invocation with Task tool
• Iterate based on results

STEP 8: Documentation & Deployment

• Create README.md
• Register in system
• Stop Condition: Ask for explicit user confirmation before register/deploy actions.

For detailed workflow: See references/section-6-subagent-creation-workflow.md

Section 5: Migration Workflow (Overview)

Use when: Converting document to skill

Process:

1. Decision check (Step 0)
2. Migration analysis (migration_helper.py)
3. Structure creation
4. Execute validation steps (5-8)
5. Package (Step 9)

Stop Condition (Mandatory):

• Before structure creation or any write/overwrite operation: ask user confirmation.
• Do not modify files until user confirms.

For detailed workflow: See references/section-5-migration-workflow-doc-to-skill.md

Section 7: Individual Tool Usage

Use when: User needs single tool, not full workflow

Entry Point: User asks for specific tool like "estimate tokens" or "security scan"

Available Tools

Validation Tool:

python scripts/validate_skill.py skill-name/ --format json

Guide: knowledge/tools/14-validation-tools-guide.md

Token Estimator:

python scripts/validate_skill.py skill-name/ --tokens-only --format json

Guide: knowledge/tools/15-cost-tools-guide.md

Security Scanner:

python scripts/validate_skill.py skill-name/ --security-only --format json

Guide: knowledge/tools/16-security-tools-guide.md

Pattern Detector:

# Analysis mode with JSON output
python scripts/pattern_detector.py "convert PDF to Word" --format json

# List all patterns
python scripts/pattern_detector.py --list --format json

# Interactive mode (text only)
python scripts/pattern_detector.py --interactive

Guide: knowledge/tools/17-pattern-tools-guide.md

Decision Helper:

# Analyze use case (JSON output - agent-layer default)
python scripts/decision_helper.py --analyze "code review with validation"

# Show decision criteria (JSON output)
python scripts/decision_helper.py --show-criteria --format json

# Text mode for human reading (debugging)
python scripts/decision_helper.py --analyze "description" --format text

Guide: knowledge/tools/18-decision-helper-guide.md

Test Generator (v1.2: Parameter update):

python scripts/test_generator.py skill-name/ --test-format pytest --format json

• --test-format: Test framework (pytest/unittest/plain, default: pytest)
• --format: Output style (text/json, default: text)
• Backward compatible: Old --output parameter still works (deprecated)

Guide: knowledge/tools/19-test-generator-guide.md

Split Skill:

python scripts/split_skill.py skill-name/ --format json

Guide: knowledge/tools/20-split-skill-guide.md

Quality Scorer:

python scripts/quality_scorer.py skill-name/ --format json

Guide: knowledge/tools/21-quality-scorer-guide.md

Migration Helper:

python scripts/migration_helper.py doc.md --format json

Guide: knowledge/tools/22-migration-helper-guide.md

Subagent Initializer (NEW):

python scripts/init.py subagent subagent-name --path /path/to/subagents

Guide: references/section-6-subagent-creation-workflow.md

Tool Output Standardization (v1.0.1+)

All 9 tools support --format json. Text mode still available via --format text (backward compatible). decision_helper defaults to JSON for automation.

JSON Output Structure:

{
  "status": "success" | "error",
  "tool": "tool_name",
  "timestamp": "ISO-8601",
  "data": { /* tool-specific results */ }
}

Quality Assurance Enhancements (v1.2+)

File & Reference Validation:

• validate_skill.py now comprehensively checks file references (markdown links, code refs, path patterns)
• package_skill.py validates references before packaging, detects orphaned files
• Prevents broken references and incomplete files in deployed skills

Content Budget Enforcement (v1.2+):

• Hard limits on file size: P0 ≤150 lines, P1 ≤100 lines, P2 ≤60 lines
• Real-time token counting with progress indicators
• Prevents file bloat that previously caused 4-9x target overruns

Execution Planning (v1.2+):

• P0/P1/P2 prioritization prevents over-scoping
• Token budget allocated per file to maintain efficiency
• Research phase respects Verbalized Sampling probability thresholds (p>0.10)

Quality Scorer Context:

• Scores calibrated for general skill quality heuristics
• Target: 70%+ is good, 80%+ is excellent
• Style scoring may not fit all skill types (educational vs technical)
• Use as guidance, supplement with manual review for edge cases

Section 8: Mode Selection Guide

| Skill Type | Recommended Mode | Why | |------------|------------------|-----| | TDD or discipline skill | full | must resist rationalization under pressure | | Code pattern skill | fast | structural checks are usually sufficient | | API reference skill | fast | primarily retrieval accuracy | | Workflow orchestration skill | full | complex flow benefits from pressure checks | | Debugging technique skill | fast | concise technique with clear method |

Full mode adds behavioral testing (pressure scenarios). Use it when discipline enforcement is core to the skill's purpose.

Section 9: Knowledge Reference Map (Overview)

Strategic context loaded on-demand.

Foundation Concepts (Files 01-08):

• Why Skills exist vs alternatives
• Skills vs Subagents decision framework
• Token economics and efficiency
• Platform constraints and security
• When NOT to use Skills

Application Knowledge (Files 09-13):

• Real-world case studies (Rakuten, Box, Notion)
• Technical architecture patterns
• Adoption and testing strategies
• Competitive landscape analysis

Tool Guides (Files 14-22):

• One guide per automation script
• Usage patterns and parameters
• JSON output formats
• Integration examples

For complete reference map: See references/section-7-knowledge-reference-map.md

Workflow Compliance

Follow workflows sequentially. Sequential steps with gates produce 9.0/10+ quality. Deviations are allowed with user justification.

Flexible entry points:

• Single tool (Section 7): skip full workflow
• Validation only (Section 3): run validation subset
• Subagent (Section 6): streamlined 8-step workflow

Additional Resources

Load reference files on-demand from references/ when detailed implementation guidance is needed.