Skip to content

Commit b97acb3

Browse files
oceanusXXDoceanusXXD
committed
Improve README showcase visuals
1 parent 4e0e953 commit b97acb3

7 files changed

Lines changed: 296 additions & 51 deletions

‎README.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,60 @@ Use it when a Python project needs coding assistants to follow the current modul
4141
| Platform automation | A DevEx team runs the workflow across many Python services | Python API returns structured results and readiness status |
4242
| Contributor onboarding | New contributors need project-specific implementation rules | Generated Skills and docs describe the repo's working contracts |
4343

44+
## Pipeline
45+
46+
![code2skill pipeline](docs/assets/code2skill-pipeline.svg)
47+
48+
The final product is a repository-owned Skill layer, not a chat transcript. Structural artifacts stay available for review, cost estimation, CI refresh, and readiness checks.
49+
50+
## Example Generated Skills
51+
52+
Generated Skills are source-cited Markdown files under `.code2skill/skills/*.md`. These shortened examples show the kind of output `code2skill` is designed to produce from repository evidence.
53+
54+
<details>
55+
<summary>Repository analysis pipeline</summary>
56+
57+
```markdown
58+
# Repository Analysis Pipeline
59+
60+
## Overview
61+
Use this Skill when changing how code2skill scans a repository, builds evidence, or writes structural artifacts.
62+
63+
## Core Rules
64+
- Keep `execute_repository(...)` as the orchestration entrypoint. Source: src/code2skill/core.py
65+
- Resolve dependencies through `ImportGraph` before ranking files or computing affected files. Source: src/code2skill/import_graph.py, src/code2skill/impact.py
66+
- Treat `project-summary.md`, `skill-blueprint.json`, `report.json`, and `state/analysis-state.json` as review and CI artifacts. Source: src/code2skill/core.py
67+
68+
## Common Flows
69+
1. Scan candidates and extract source/config summaries.
70+
2. Build import graph, PageRank, evidence coverage, and blueprint.
71+
3. Render summary/reference/report artifacts before optional Skill generation.
72+
```
73+
74+
</details>
75+
76+
<details>
77+
<summary>Assistant target publishing</summary>
78+
79+
```markdown
80+
# Assistant Target Publishing
81+
82+
## Overview
83+
Use this Skill when publishing generated Skills into Codex, Claude Code, Cursor, GitHub Copilot, or Windsurf target files.
84+
85+
## Core Rules
86+
- Use `adapt` for target publishing; generated target content must stay inside managed blocks or manifest-tracked files. Source: src/code2skill/adapt.py, src/code2skill/capabilities/adapt/targets.py
87+
- Run `doctor` after adaptation to verify the bundle, Skill plan, generated Skill files, state, and selected target output. Source: src/code2skill/capabilities/adoption_service.py
88+
- Preserve hand-written target-file content outside the managed block. Source: src/code2skill/capabilities/output_bundle_service.py
89+
90+
## Common Flows
91+
1. Generate or refresh `.code2skill/skills/*.md`.
92+
2. Run `code2skill adapt . --target <tool>`.
93+
3. Run `code2skill doctor . --target <tool>`.
94+
```
95+
96+
</details>
97+
4498
## Benchmark
4599

46100
`code2skill` is evaluated on structural evidence extraction before any LLM call. The benchmark compares two simple baselines against the semantic scanner used by the Skill generation pipeline.

‎README.zh-CN.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,60 @@
4141
| 平台自动化 | DevEx 团队跨多个 Python 服务运行同一流程 | Python API 返回结构化结果和 readiness |
4242
| 开源贡献者 onboarding | 新贡献者改代码前需要项目实现规则 | 生成的 Skills 和 docs 说明仓库的工作契约 |
4343

44+
## 流程图
45+
46+
![code2skill pipeline](docs/assets/code2skill-pipeline.svg)
47+
48+
最终产物是一套可以提交到仓库里的 Skill 层，而不是一段聊天记录。结构化产物会保留下来，用于审阅、成本估算、CI 刷新和 readiness 检查。
49+
50+
## 生成 Skill 示例
51+
52+
生成的 Skill 是 `.code2skill/skills/*.md` 下的 Markdown 文件。下面是基于当前仓库证据整理的缩短示例，展示最终输出应该长什么样。
53+
54+
<details>
55+
<summary>Repository analysis pipeline</summary>
56+
57+
```markdown
58+
# Repository Analysis Pipeline
59+
60+
## Overview
61+
Use this Skill when changing how code2skill scans a repository, builds evidence, or writes structural artifacts.
62+
63+
## Core Rules
64+
- Keep `execute_repository(...)` as the orchestration entrypoint. Source: src/code2skill/core.py
65+
- Resolve dependencies through `ImportGraph` before ranking files or computing affected files. Source: src/code2skill/import_graph.py, src/code2skill/impact.py
66+
- Treat `project-summary.md`, `skill-blueprint.json`, `report.json`, and `state/analysis-state.json` as review and CI artifacts. Source: src/code2skill/core.py
67+
68+
## Common Flows
69+
1. Scan candidates and extract source/config summaries.
70+
2. Build import graph, PageRank, evidence coverage, and blueprint.
71+
3. Render summary/reference/report artifacts before optional Skill generation.
72+
```
73+
74+
</details>
75+
76+
<details>
77+
<summary>Assistant target publishing</summary>
78+
79+
```markdown
80+
# Assistant Target Publishing
81+
82+
## Overview
83+
Use this Skill when publishing generated Skills into Codex, Claude Code, Cursor, GitHub Copilot, or Windsurf target files.
84+
85+
## Core Rules
86+
- Use `adapt` for target publishing; generated target content must stay inside managed blocks or manifest-tracked files. Source: src/code2skill/adapt.py, src/code2skill/capabilities/adapt/targets.py
87+
- Run `doctor` after adaptation to verify the bundle, Skill plan, generated Skill files, state, and selected target output. Source: src/code2skill/capabilities/adoption_service.py
88+
- Preserve hand-written target-file content outside the managed block. Source: src/code2skill/capabilities/output_bundle_service.py
89+
90+
## Common Flows
91+
1. Generate or refresh `.code2skill/skills/*.md`.
92+
2. Run `code2skill adapt . --target <tool>`.
93+
3. Run `code2skill doctor . --target <tool>`.
94+
```
95+
96+
</details>
97+
4498
## 基准测试
4599

46100
`code2skill` 评测的是 LLM 调用前的结构证据抽取能力。这个 benchmark 用两个简单 baseline 对比 Skill 生成流水线使用的语义扫描器。

‎benchmarks/evaluate_structural_evidence.py‎

Lines changed: 53 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -190,56 +190,86 @@ def code2skill_facts(repo_path: Path) -> set[str]:
190190

191191
def render_svg(report: dict[str, object]) -> str:
192192
results = report["results"]
193-
width = 880
194-
height = 330
195-
left = 210
196-
top = 88
197-
chart_width = 610
198-
bar_height = 34
199-
gap = 52
193+
width = 980
194+
height = 430
195+
left = 250
196+
top = 134
197+
chart_width = 680
198+
bar_height = 32
199+
gap = 58
200+
gold_total = int(report["gold_total"])
201+
result_by_method = {result["method"]: result for result in results}
202+
semantic_delta = (
203+
result_by_method["code2skill-semantic"]["recall"]
204+
- result_by_method["ast-symbols"]["recall"]
205+
) * 100
200206
colors = {
201-
"path-only": "#8a8f98",
202-
"ast-symbols": "#3f6d8f",
203-
"code2skill-semantic": "#198754",
207+
"path-only": "#9ca3af",
208+
"ast-symbols": "#4f6f8f",
209+
"code2skill-semantic": "#0f766e",
204210
}
205211
labels = {
206212
"path-only": "Path-only baseline",
207213
"ast-symbols": "AST symbols baseline",
208214
"code2skill-semantic": "code2skill semantic",
209215
}
216+
tick_values = [0.0, 0.25, 0.5, 0.75, 1.0]
210217
lines = [
211-
'<svg xmlns="http://www.w3.org/2000/svg" width="880" height="330" viewBox="0 0 880 330" role="img" aria-labelledby="title desc">',
218+
'<svg xmlns="http://www.w3.org/2000/svg" width="980" height="430" viewBox="0 0 980 430" role="img" aria-labelledby="title desc">',
212219
'<title id="title">Structural evidence extraction benchmark</title>',
213220
'<desc id="desc">Gold evidence recall for path-only, AST-symbols, and code2skill-semantic extraction.</desc>',
214-
'<rect width="880" height="330" fill="#ffffff"/>',
215-
'<text x="36" y="38" font-family="Arial, sans-serif" font-size="24" font-weight="700" fill="#111827">Structural Evidence Extraction</text>',
216-
'<text x="36" y="62" font-family="Arial, sans-serif" font-size="13" fill="#4b5563">Gold evidence recall before any LLM call. Higher is better.</text>',
221+
'<rect width="980" height="430" fill="#ffffff"/>',
222+
'<text x="38" y="44" font-family="Arial, sans-serif" font-size="15" font-weight="700" fill="#111827">A</text>',
223+
'<text x="64" y="44" font-family="Arial, sans-serif" font-size="22" font-weight="700" fill="#111827">Structural Evidence Extraction</text>',
224+
f'<text x="64" y="70" font-family="Arial, sans-serif" font-size="13" fill="#4b5563">Deterministic benchmark before any LLM call; gold structural facts, n={gold_total}.</text>',
225+
f'<text x="64" y="94" font-family="Arial, sans-serif" font-size="12" fill="#0f766e">code2skill recovers all gold facts and improves over the AST-symbol baseline by {semantic_delta:.1f} percentage points.</text>',
217226
]
218-
for tick in range(0, 6):
219-
x = left + tick * chart_width / 5
220-
lines.append(f'<line x1="{x:.1f}" y1="78" x2="{x:.1f}" y2="252" stroke="#eef0f3"/>')
227+
for value in tick_values:
228+
x = left + value * chart_width
229+
lines.append(f'<line x1="{x:.1f}" y1="118" x2="{x:.1f}" y2="320" stroke="#e5e7eb" stroke-width="1"/>')
221230
lines.append(
222-
f'<text x="{x - 8:.1f}" y="276" font-family="Arial, sans-serif" font-size="11" fill="#6b7280">{tick / 5:.1f}</text>'
231+
f'<text x="{x - 10:.1f}" y="342" font-family="Arial, sans-serif" font-size="12" fill="#374151">{value:.2f}</text>'
223232
)
233+
lines.append(
234+
f'<line x1="{left}" y1="118" x2="{left + chart_width}" y2="118" stroke="#111827" stroke-width="1"/>'
235+
)
236+
lines.append(
237+
f'<line x1="{left}" y1="118" x2="{left}" y2="320" stroke="#111827" stroke-width="1"/>'
238+
)
239+
lines.append(
240+
f'<text x="{left + chart_width / 2 - 58:.1f}" y="372" font-family="Arial, sans-serif" font-size="13" fill="#111827">Gold evidence recall</text>'
241+
)
224242
for index, result in enumerate(results):
225243
method = result["method"]
226244
y = top + index * gap
227245
value = result["recall"]
228246
bar_width = value * chart_width
229247
lines.append(
230-
f'<text x="36" y="{y + 23}" font-family="Arial, sans-serif" font-size="14" font-weight="700" fill="#111827">{labels[method]}</text>'
248+
f'<text x="64" y="{y + 22}" font-family="Arial, sans-serif" font-size="14" font-weight="700" fill="#111827">{labels[method]}</text>'
249+
)
250+
lines.append(
251+
f'<rect x="{left}" y="{y}" width="{bar_width:.1f}" height="{bar_height}" fill="{colors[method]}"/>'
231252
)
232253
lines.append(
233-
f'<rect x="{left}" y="{y}" width="{bar_width:.1f}" height="{bar_height}" rx="4" fill="{colors[method]}"/>'
254+
f'<text x="{left + bar_width + 10:.1f}" y="{y + 21}" font-family="Arial, sans-serif" font-size="13" fill="#111827">{value:.3f}</text>'
234255
)
235256
lines.append(
236-
f'<text x="{left + bar_width + 10:.1f}" y="{y + 23}" font-family="Arial, sans-serif" font-size="13" fill="#111827">{value:.3f} ({result["gold_hits"]}/{result["gold_total"]})</text>'
257+
f'<text x="{left - 66}" y="{y + 22}" font-family="Arial, sans-serif" font-size="12" fill="#4b5563">{result["gold_hits"]}/{result["gold_total"]}</text>'
237258
)
238259
lines.append(
239-
'<text x="36" y="314" font-family="Arial, sans-serif" font-size="12" fill="#6b7280">code2skill captures routes, calls, type references, data-flow, dynamic imports, re-exported symbols, exceptions, and dependency edges.</text>'
260+
f'<text x="{left - 80}" y="118" font-family="Arial, sans-serif" font-size="12" font-weight="700" fill="#374151">hits</text>'
261+
)
262+
lines.append(
263+
f'<line x1="{left}" y1="313" x2="{left + chart_width}" y2="313" stroke="#111827" stroke-width="1"/>'
264+
)
265+
lines.append(
266+
'<text x="64" y="404" font-family="Arial, sans-serif" font-size="12" fill="#4b5563">Gold set: roles, imports, routes, calls, type references, models, data-flow, dynamic imports, exceptions, main guards, re-exports, and dependency edges.</text>'
267+
)
268+
lines.append(
269+
'<text x="64" y="388" font-family="Arial, sans-serif" font-size="12" fill="#6b7280">Bars report exact recall on a synthetic fixture repository; higher is better.</text>'
240270
)
241271
lines.append("</svg>")
242-
return "\n".join(lines)
272+
return "\n".join(lines) + "\n"
243273

244274

245275
def gold_facts() -> list[str]:

‎benchmarks/results/structural-evidence-benchmark.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "structural-evidence-extraction",
3-
"generated_at": "2026-06-06T16:13:09.683771+00:00",
3+
"generated_at": "2026-06-06T16:27:56.843435+00:00",
44
"gold_total": 45,
55
"results": [
66
{

‎docs/assets/code2skill-pipeline.svg‎

Lines changed: 87 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)