codify-to-knowhow

Codify to Knowhow

General manifest-driven knowledge asset generator. Reads knowhow-manifest.json, creates knowhow files and spec entries according to the declaration, and builds an index-detail bridge via ref.

Applicable scenarios: Use when any workflow output needs to be solidified into a knowledge asset. Upstream skills (such as maestro-impeccable --codify) are responsible for generating the manifest, and this skill is responsible for executing knowledge writes.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│  Codify to Knowhow (SKILL.md) — Manifest-Driven            │
│  → Read manifest → Create knowhow → Create specs → Verify  │
└──────────────────────────┬──────────────────────────────────┘
                           │
    ┌──────────┬───────────┼───────────┬──────────┐
    ↓          ↓           ↓           ↓          │
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐      │
│Phase 1 │ │Phase 2 │ │Phase 3 │ │Phase 4 │      │
│ Load   │ │Generate│ │Generate│ │ Index  │      │
│Manifest│ │Knowhow │ │ Specs  │ │ Verify │      │
└───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘      │
    │          │          │          │             │
 manifest   AST-/DCS-  spec-entry  verified       │
 parsed     files       + ref       assets        │

Key Design Principles

1. Manifest-driven: All behavior is declared by knowhow-manifest.json , containing no hardcoded domain knowledge
2. Idempotent execution: Before each write, check by slug whether the asset already exists; if it exists, skip it
3. ref bridge: spec-entry references the knowhow detail via ref Reference knowhow details
4. Closing tag: All entries use <spec-entry>/<knowhow-entry> closing tag
5. Upstream generates manifest: This skill does not perform knowledge extraction, only knowledge writing

Manifest Format

knowhow-manifest.json is generated by the upstream skill and placed in the package directory:

{
  "slug": "my-style-v1",
  "domain": "ui-design",
  "roles": ["implement", "review"],
  "packagePath": ".workflow/reference_style/my-style-v1",

  "knowhow": [
    {
      "prefix": "AST",
      "fileSlug": "tokens",
      "title": "Design Tokens",
      "category": "asset",
      "assetType": "design-tokens",
      "codePaths": ["src/styles/"],
      "tags": ["design-tokens", "colors"],
      "entries": [
        {
          "category": "pattern",
          "keywords": "colors,tokens",
          "title": "Color System",
          "body": "## Colors\n\n..."
        }
      ]
    }
  ],

  "specs": [
    {
      "category": "coding",
      "keywords": "colors,design-tokens",
      "title": "颜色编码约定",
      "ref": "knowhow/AST-my-style-v1-tokens.md",
      "body": "主色使用 var(--color-primary)..."
    }
  ]
}

Execution Flow

Input: <package-path> (must contain knowhow-manifest.json)

Phase 1: Load and Validate Manifest
   └─ Ref: phases/01-load-manifest.md
      ├─ Validate package path and manifest existence
      ├─ Parse knowhow-manifest.json
      └─ Output: manifest object

Phase 2: Generate Knowhow Assets
   └─ Ref: phases/02-generate-knowhow.md
      ├─ Idempotency check per file
      ├─ Write knowhow files per manifest.knowhow[]
      └─ Output: knowhowPaths[]

Phase 3: Generate Spec Entries
   └─ Ref: phases/03-generate-specs.md
      ├─ Idempotency check per entry
      ├─ Write spec entries per manifest.specs[]
      └─ Output: specEntryCount

Phase 4: Index and Verify
   └─ Ref: phases/04-index-verify.md
      └─ Output: verification report

Phase Reference Documents:

Phase	Document	Purpose
1	phases/01-load-manifest.md	Load and validate manifest
2	phases/02-generate-knowhow.md	Create knowhow files
3	phases/03-generate-specs.md	Create spec entries with ref
4	phases/04-index-verify.md	Verify assets and index

Core Rules

1. Manifest required: If there is no manifest, report an error and exit
2. Idempotent writing: If a file with the same slug exists, skip it
3. Closing tag: All entries use the closing tag format
4. Auto-Continue: After a Phase completes, automatically execute the next Phase
5. Do not extract knowledge: This skill only writes; knowledge extraction is completed by the upstream

Data Flow

Input (packagePath)
    ↓
Phase 1 → manifest: { slug, knowhow[], specs[] }
    ↓
Phase 2 → knowhowPaths: string[], knowhowIds: string[]
    ↓
Phase 3 → specEntryCount: number
    ↓
Phase 4 → verificationResult
    ↓
Completion report

TodoWrite Pattern

[
  {"content": "Phase 1: 加载 Manifest", "status": "in_progress"},
  {"content": "Phase 2: 生成 Knowhow 资产", "status": "pending"},
  {"content": "Phase 3: 生成 Spec 条目", "status": "pending"},
  {"content": "Phase 4: 索引验证", "status": "pending"}
]

Error Handling

• Manifest does not exist: Report an error and indicate that the upstream skill must first generate the manifest
• Manifest format error: Report missing fields
• Idempotency conflict: Skip existing assets and report the number skipped
• CLI failure: Fall back to the Write tool to write the file directly

Related Commands

Upstream: maestro-impeccable --codify, learn decompose, or any skill that generates a manifest Follow-up: maestro wiki list --category coding, maestro load --type spec --keyword <slug>