Agent OS Asset

Agent OS Asset v3.0.0

Use this skill as the public suite entrypoint for designing, auditing, or refactoring historical files into Agent OS assets. It owns orchestration and governance while loading three bundled child Skills by relative path:

• skills/agent-readable-doc/SKILL.md: extraction, conversion, validation, and semantic materialization.
• skills/kb-review/SKILL.md: AI-era value judgment and review decisions.
• skills/second-brain/SKILL.md: final non-PII indexing and retrieval.

Read the required child SKILL.md before invoking its scripts. If a child is missing, stop with a clear dependency error rather than silently degrading the pipeline.

Core Model

Agent Asset v3.0.0 has four layers:

1. Source: the original Office/PDF/image/XMind/Drawio/data/code file. It is the highest-fidelity, human-editable or evidentiary source of truth.
2. Semantic Entry: usually one lean .agent.md next to the original location. It is the first human/Agent reading surface, not a full replacement for the source.
3. Working Manifest: asset-manifest.jsonl or an equivalent machine ledger. It stores lifecycle, privacy, format, fidelity, source/semantic paths, sampling, and progressive disclosure details.
4. Final Index: SecondBrain or another retrieval index. It indexes only reviewed final independent assets.

Default pipeline:

inventory -> agent-readable-doc extraction -> working manifest -> kb-review suggestions -> asset decisions -> optional materialize -> final SecondBrain index

Do not build a final long-term index from unreviewed converted assets. Converted means "candidate", not "keep". kb-review is the canonical owner of value judgment rules; this skill owns only architecture, lifecycle vocabulary, and pipeline contracts.

User Invocation (Preferred)

Users should invoke $agent-os-asset in natural language rather than memorizing CLI commands. Resolve the target directory and run the corresponding pipeline stage internally:

• “对 <目录> 预览 Agent 化” → run review plan-only; report the proposed source/semantic/manifest/review flow without changing files.
• “对 <目录> 开始 Agent 化” → run prepare with the extraction gate; generate semantic entries and archive only approved non-PII originals.
• “我已经 review 完 <目录>，应用这个 decisions JSON” → dry-run the exported decisions first, then apply them only with the explicit decision gate. A successful apply writes the durable ledger and manifest, regenerates the same workbench with current decisions, audits the scope, and automatically runs asset-manifest indexing only when the scope is fully ready.
• “同步 <目录> 的原始资料变更” → run automatic maintain: successful non-PII additions/changes are materialized, validated, retained as keep/final, and then incrementally indexed only when no pending/failure remains. PII, unknown-privacy, missing, and failed assets stay excluded.
• “为 <目录> 启用自动同步” → install its per-directory macOS LaunchAgent (WatchPaths plus heartbeat).
• “同步状态 <目录>” → show baseline, recent success/failure, pending changes, heartbeat, and index state.
• “停用自动同步 <目录>” → unload and remove that directory's LaunchAgent.
• “为 <目录> 构建 SecondBrain 索引” → audit final-index readiness first; index only final non-PII assets after the user confirms review completion.
• “优化 <目录> 的项目检索质量” → audit weak final repo entries, regenerate only low-signal repo.agent.md files with backups, rebuild the asset index, then run its strict Top-1 benchmark. A ready asset index registers for SecondBrain federated retrieval.

Use the CLI examples below only as implementation details, automation hooks, or a fallback when operating outside an Agent session.

Scripted Pipeline

Use scripts/asset_pipeline.py when the user wants the default pipeline executed or planned through code. The script is an orchestrator: it delegates concrete extraction/review actions to a project adapter, defaulting to /tools/cleanup_convert.py, and delegates final indexing to the second-brain routine.

Common commands:

python3 /scripts/asset_pipeline.py --root  --scope  --pipeline review
python3 /scripts/asset_pipeline.py --root  --scope  --pipeline review --plan-only
python3 /scripts/asset_pipeline.py --root  --scope  --stage workbench --workbench-decisions 
python3 /scripts/asset_pipeline.py --root  --scope  --stage apply-dry-run --decisions 
python3 /scripts/asset_pipeline.py --root  --scope  --stage apply --decisions  --execute-decisions
python3 /scripts/asset_pipeline.py --root  --scope  --stage apply --decisions  --execute-decisions --after-apply-index never
python3 /scripts/asset_pipeline.py --root  --scope  --pipeline maintain --execute-sync
python3 /scripts/asset_pipeline.py --root  --scope  --pipeline maintain --execute-sync --auto-keep
python3 /scripts/auto_sync.py --root  --scope  --install
python3 /scripts/asset_pipeline.py --root  --scope  --stage index --execute-index
python3 /scripts/asset_pipeline.py --root  --scope  --pipeline optimize-retrieval --execute-retrieval-refresh --execute-index

For source-code repositories, use the bundled project-level adapter:

python3 /scripts/asset_pipeline.py \
  --root  \
  --scope  \
  --cleanup-tool /scripts/code_repo_adapter.py \
  --pipeline review

For a mixed historical folder that contains repositories plus ordinary documents, do not require a repo-local workbench. Generate each repo's repo.agent.md and shared manifest row first, then build one parent-scope asset workbench with the folder adapter so the repository appears as one review row beside the non-repo assets.

Default Project Granularity

Fine-grained assetization is the default completion target for mixed historical folders:

• Discover every Git/SVN root as an independent code_project, including nested VCS roots.
• Outside detected VCS roots, use the outermost build/IDE marker (pom.xml, SBT/Gradle, pyproject.toml, package.json, Go/Rust/CMake, Xcode project) as a legacy unversioned project fallback. If none exists, a clearly code-oriented directory (code, src, source, examples/scripts, or equivalent Chinese names) or a non-root parent containing code may be a conservative project fallback; do not let a scope-root loose script swallow an entire mixed collection.
• In directory-based code collections, an existing active /repo.agent.md is a bounded rehydration hint: treat its parent as a known nested project root, then rebuild it from current source evidence rather than leaving a stale semantic entry outside the manifest.
• When the owner designates a directory as a code collection, use directory-projects: every intended child directory is a project-level asset even when it lacks VCS/build markers. Code files, including .ipynb, are project evidence only; never create a standalone .agent.md for a code file.
• Do not treat a parent folder with a README or a few source files as one broad repository. Do not split ordinary modules inside a VCS root unless they are themselves nested Git/SVN roots.
• Generate /repo.agent.md and one shared manifest row for every discovered project. Generate independent document assets for remaining non-PII sources; merge only tiny, clearly related same-directory fragments.
• A parent scope map is optional run state under .cleanup-extracted/; it is not a replacement for project rows and is excluded from independent review/indexing.

Safety gates:

• extract is blocked unless --execute-extraction is present.
• suggest is the CLI stage name for KB Review suggestions. It remains named suggest for adapter compatibility, but its semantics and output text are KB Review.
• apply is blocked unless --execute-decisions is present.
• apply-dry-run and apply write an auditable run-state report under .cleanup-extracted/: decision counts, type counts, unmatched IDs, delete assets, and one path-level effect for each source/semantic target (would_trash, trashed, missing, or an explicit skip reason). The persisted {assets: {...}} ledger and exported {decisions: [...]} file are both accepted as apply inputs.
• sync is blocked unless --execute-sync is present. Without --auto-keep, adapter compatibility mode still returns successful additions/changes to review. With --auto-keep, only validated non_pii assets become/remain final; PII/unknown privacy, failures, empty files, and unresolved moves remain excluded. The index stage is skipped unless the sync result explicitly reports a fully final, failure-free change set.
• index is blocked unless --execute-index is present and .cleanup-extracted/asset-decisions.json exists, unless explicitly bypassed.
• optimize-retrieval is blocked unless both --execute-retrieval-refresh and --execute-index are present. It only rewrites final non-PII project entries that a weak-quality audit flags, stores original semantic entries under .cleanup-extracted/retrieval-refresh-backups/, and preserves lifecycle decisions/source trees.
• workbench-decisions only pre-fills review UI fields; it does not write the durable ledger or move files.
• Project-level suggestions must run KB Review value rules, not emit a blanket review: use bounded README/AGENTS/wiki/docs evidence, classify dependency-only bundles as archive_only when appropriate, and state evidence, confidence, and uncertainty in the suggestion.

For projects that do not have tools/cleanup_convert.py, pass --cleanup-tool where the adapter supports the same stage flags.

For a new mixed historical folder with no local adapter, asset_pipeline.py automatically falls back to scripts/mixed_folder_adapter.py. It performs conservative inventory first, uses agent-readable-doc for materialization/validation, keeps sensitive paths out of body extraction, and archives non-sensitive originals only with --execute-extraction.

Markdown Entry Standard

For full-folder Agent Asset outputs, .agent.md frontmatter should stay lean:

• id
• title
• summary
• tags
• search_terms
• use_when
• skip_when
• source_paths
• source_created_at
• source_modified_at
• agent_modified_at
• version

Keep these fields in the manifest, not in every Markdown file: document type, aliases, asset type, source/semantic formats, privacy, retention, index status, source status, fidelity, extraction policy, chunk strategy, progressive disclosure, and generated provenance.

Markdown body order:

## 摘要
## Insight
## Details
## Source Map

Rules:

• summary must use title, source metadata, and source-content clues. Do not derive it from filename/title alone.
• For long content, build summary clues from approximately the first 1000 characters plus the last 1000 characters, filtering extractor noise such as PPT layout coordinates.
• Insight is for unique, non-obvious, personally valuable, hard-to-reconstruct ideas, project judgment, takeaways, and why the asset is worth retaining.
• Limit .agent.md tags to at most 3.
• Use a PII tag for user-facing Markdown privacy indication. Do not add a separate Markdown privacy field.

File-Type Policy

• Word / Markdown / text / HTML: generate .agent.md, preserving original structure, examples, tables, TODOs, and author judgments with light formatting cleanup.
• Excel / workbook: small sheets may become Markdown tables. Large sheets use metadata, sheet names, dimensions, columns, front/back samples, and data-shape notes. The original workbook remains source of truth.
• PDF / large files: do not read, OCR, or convert the entire file by default. Use metadata and front/back text windows. If estimated content exceeds about 4096 tokens, summarize from about the first 1000 and last 1000 tokens.
• PPT / PPTX: do not generate static Quick Look previews as long-term assets. PPTX may expose slide order, reading-order text, speaker notes, tables, and media maps as on-demand disclosure. The original deck remains source of truth for layout, animation, editing, and sharing.
• XMind / OPLX: extract topic/task trees when safely readable. Keep original mindmap or project bundle as source of truth.
• Standalone images/screenshots: create metadata-first visual assets. Do not write low-quality OCR or weak visual descriptions into .agent.md. Keep path, format, size, dimensions, visual backend status, and Source Map. Add visual descriptions only when a configured high-quality multimodal backend returns useful content.
• Embedded images/screenshots: treat as parent-asset attachments. Do not OCR, describe, or index them independently.
• Drawio / other interactive visual files: default to metadata-first and source linking. Do not create pseudo-high-fidelity HTML unless a real viewer/editor is intentionally integrated.
• Code projects / bundles: use scripts/code_repo_adapter.py or an equivalent adapter. At the default VCS-first granularity, produce one project-level repo.agent.md plus one manifest/workbench row for every Git/SVN or eligible unversioned project root. Do not create per-source-file Agent assets, and do not index build artifacts, caches, jars, classes, vendored libraries, generated outputs, or dependency directories as independent knowledge.
• Data directories / datasets: classify recognized dataset folders and related loose data files as one data_bundle metadata asset at the nearest safe directory boundary. Do not create a .agent.md, review row, or body extraction for each member file. Store counts, formats, sample paths, and a member ledger under .cleanup-extracted/; a delete decision may move only listed members to Trash, never the parent code/course directory.

For code repositories, the default visible outputs should be:

• /repo.agent.md: project-level semantic entry with summary, Insight, key files, commands, directory sketch, and Source Map.
• one shared asset-manifest.jsonl row: the machine ledger entry used by the parent directory workbench and final index readiness checks.

For every project-level semantic entry, bounded safe context must shape visible content rather than merely prove that documents exist: README supplies project purpose/capabilities; AGENTS/CLAUDE supplies concrete development/testing/release constraints; docs/wiki supplies architecture, workflows, and key commands. Strip frontmatter, badges, HTML banners, images, and secret-like assignments from evidence; retain source paths in Details.

When those documents are absent, use only safe root-level entry evidence as a fallback: package/build manifests (package.json, pyproject.toml, pom.xml, Gradle/SBT/Cargo/Go/CMake), root build/control scripts (Makefile, run.sh, build.sh, control.sh), and recognized application entries (main.*, app.*, cli.*). This fallback shapes the semantic entry but is weaker KB Review evidence: it normally remains review rather than automatically becoming keep.

A repo-local /cleanup-asset-review-workbench.html is optional for repo-only review. In mixed directories, prefer the total parent workbench and show the repository as a single row there. The adapter may also write required run-state files under .cleanup-extracted/, especially asset-manifest.jsonl, suggestions, audit reports, and decision ledgers. These are pipeline state, not separate knowledge assets.

Metadata-first means the retrieval entry starts from manifest/source metadata and a short semantic entry. It does not mean discarding reliable structured text such as PPTX slide text, speaker notes, or XMind topic trees.

Review And Decisions

Review at the independent-asset level, not per generated file. A workbench row should combine source paths and semantic paths for the same asset.

Decision values:

• keep: retain source and semantic entry; eligible for final index if non-PII.
• generate_asset: retain and improve semantic quality; eligible for final index if non-PII.
• metadata_only: retain and index only manifest/source metadata; no semantic body required.
• archive_only: retain source but exclude from final index.
• review: unresolved candidate.
• delete: move asset bundle to recoverable system Trash only.

PII labels are safety metadata. They do not authorize reading sensitive bodies. Filename/path hits for secrets, tokens, payroll, banking, resumes, personnel, performance, promotion, self-review, or personal-transfer folders should be registered but not read.

The durable decision ledger should be machine-readable, such as .cleanup-extracted/asset-decisions.json. Dry-run/apply Markdown reports are optional audit outputs, not source of truth.

Apply output is an execution summary, not merely a return code. It must state matched/unmatched decisions, counts grouped by decision and asset type, and every delete asset's source/semantic paths and actual file effect. Keep the complete JSON and Markdown report in run state even when the terminal output is truncated.

After --execute-decisions, apply must rewrite the durable decision ledger, manifest lifecycle fields, and the scope's cleanup-asset-review-workbench.html before returning. A localhost workbench should reload that refreshed HTML after execution. With --after-apply-index auto (the default), the orchestrator audits the same scope and runs SecondBrain asset-manifest indexing only when there are no candidates, review rows, missing required sources/semantic entries, final PII rows, failed deletes, or unmatched decisions. Successfully deleted assets are excluded; their now-missing source paths must not block index readiness. Use --after-apply-index never to opt out.

Every successful audit-ready asset-manifest index may be registered in a user-configured state directory. skills/second-brain/scripts/query_index.py --asset-indexes auto can then federate it for relevant project/capability queries while skipping stale or non-final index entries. Maintain an explicit .cleanup-extracted/retrieval-benchmark.json for strict Top-1 project retrieval. If lexical retrieval fails, the quality report can request bounded optional embedding rerank; provider failure must preserve lexical results and report the gap without exposing credentials.

Workbench Policy

HTML workbenches are review UIs, not knowledge assets and not decision ledgers.

• A workbench row represents one independent asset. Combine original source and semantic file controls in that row so the user reviews the asset once.
• The asset review table exposes 文件类型 (file-type) and 材料原始目录 columns. File type is derived from source format/extension (e.g. PPT, DOC, TXT, XLSX); original directory is the source file's parent directory or the source root for a code bundle. It does not carry a separate Status column; index lifecycle stays in the manifest and the decision/PII controls, not as its own table column.
• Keep the filter toolbar and table header sticky within the review surface. Freeze only compact control columns (编号, Select, Decision, PII) during horizontal scrolling; leave evidence, paths, summaries, actions, and Insights scrollable so controls do not consume the whole viewport.
• Provide independent filters for index status, suggested decision, current Decision, PII, and source file type. Filters must compose with free-text search and update the visible-row count.
• Display material original directories as complete root-relative paths, not truncated basenames. Keep suggestion reasons compact by default and expose full evidence/signals through a disclosure control.
• Prefer explicit selection controls: select all currently visible rows, invert currently visible rows, clear selection, and apply to selected. Label them simply as "全选", "反选", "清空选择", and "应用到已选". In localhost mode, label persistence/execution controls as "保存 decisions.json" and "执行 review 结果"; in static file:// mode, label them as "下载 decisions.json" and "下载并复制命令". Avoid an "apply visible" action because it mutates every filtered row without a clear selection step.
• If the user has already exported or downloaded a decisions JSON, the workbench may be regenerated with those decisions prefilled. This is a rehydration step only: it should update editable decision/PII fields shown in the HTML, not write the durable decision ledger or execute delete/archive.
• Static file:// workbenches should keep native file links but must not promise that browsers can open all local files.
• Static pages cannot execute macOS open. For no-server workflows, display a copyable open "" command beside each source and semantic path.
• A static page may optionally include a shortcuts://run-shortcut?name=OpenAgentAssetFile&input=text&text= link only when the generator detects that the shortcut exists locally. Do not show a broken shortcut link by default.
• Only localhost-served pages may call an /__open endpoint, and that endpoint must be workspace-restricted.
• Direct save/execute buttons are allowed only in localhost mode through workspace-restricted endpoints. In static mode, saving falls back to browser download and executing should copy a short terminal command that reads an exported decisions file; the command must match the actual browser download behavior.
• The bundled localhost server is read-only by default. Enable only the minimum required capability with --enable-file-open, --enable-write, or --enable-apply; every action endpoint requires the ephemeral session token embedded in the server URL.
• Static file:// workbenches must not copy large decision payloads into the terminal command. Keep copied commands short and path-based.
• Finder review bundles are optional convenience artifacts, not required for the Agent Asset model.
• Reports generated from applying decisions should live under a run-state directory such as .cleanup-extracted/, not beside business documents.

Long-Term Sync

For the bundled mixed-folder adapter and the 58 adapter, maintain reconciles active additions with archived sources and stored fingerprints:

• added/modified non-PII source → materialize and validate; --auto-keep records keep/final, otherwise candidate/review;
• missing source → retain the existing semantic entry for audit, mark source missing/excluded, and remove it from final index eligibility;
• move/rename → preserve asset ID, decision, and semantic entry only for an unambiguous SHA-256 + type + size match; otherwise expose missing + added;
• extraction/validation failure → retain the old semantic entry, mark sync_failed/excluded, and alert; never overwrite it;
• unchanged source → preserve its manifest, decision, and index status.

auto_sync.py uses a per-directory macOS LaunchAgent, an advisory lock, 90-second debounce, atomic sync state, and native notifications. It ignores run-state changes semantically, sends no notification for no-op runs, and only runs SecondBrain asset-manifest incremental indexing after a fully final, failure-free change set.

Final Index Readiness

Before SecondBrain final indexing, verify:

• every final independent asset has available source paths;
• final non-metadata_only assets have at least one semantic path;
• PII assets are excluded from final index;
• embedded attachments and generated reports are excluded as independent assets;
• summaries and Insights are present and not just filenames or extractor noise;
• large-file rows state the sampling policy;
• visual rows state whether visual understanding is pending or model-derived.