|
6 | 6 |
|
7 | 7 | English README. For Chinese documentation, see [README.zh-CN.md](./README.zh-CN.md). |
8 | 8 |
|
9 | | -`code2skill` turns a real Python repository into structured repository knowledge, AI-ready Skill documents, and target-specific rule files for Cursor, Claude Code, Codex, GitHub Copilot, and Windsurf. |
| 9 | +`code2skill` is a CLI for real Python repositories. It turns source code into structured project knowledge, Skill documents that AI coding assistants can consume directly, and rule files adapted for tools such as Cursor, Claude Code, Codex, GitHub Copilot, and Windsurf. |
10 | 10 |
|
11 | | -It is built for repositories that need repeatable AI context instead of one-off prompts. The pipeline scans code first, extracts structure and evidence, plans focused skills, and then generates grounded Markdown that can be reused locally or in CI. |
| 11 | +It provides a full chain from repository scanning and structural analysis to Skill generation and rule adaptation, with incremental updates based on diffs and historical state. The generated outputs are written to disk so they can be reviewed, committed, reused, and continuously integrated into local development and CI workflows. |
| 12 | + |
| 13 | +## Why Skills Matter |
| 14 | + |
| 15 | +In traditional software development, the `README` is the standard entry document for a project. It is written for human developers and usually covers project introduction, installation, usage, development setup, and examples. |
| 16 | + |
| 17 | +In the AI IDE era, AI tools also read READMEs, documentation, and source code to understand a project. At that point, a repository needs a form of knowledge that is better suited for direct AI consumption. READMEs still matter, but they often mix user guidance, developer guidance, background context, historical notes, sample snippets, and presentation-oriented material. That structure is natural for human readers. For AI systems, however, project conventions, important patterns, and execution boundaries are more useful when they are presented in a more unified and structured form. |
| 18 | + |
| 19 | +A Skill is that AI-oriented project document form. |
| 20 | + |
| 21 | +In practice, a Skill can be treated as an engineering-grade README for AI. It organizes implementation-relevant knowledge into stable, clear, and maintainable documents so that AI can read consistent project context across different tools, sessions, and stages of work. |
| 22 | + |
| 23 | +Skills let a repository express information such as: |
| 24 | + |
| 25 | +- the core structure of the project and the responsibility boundaries of modules |
| 26 | +- the important roles, call relationships, and behavioral constraints in the code |
| 27 | +- existing patterns, conventions, and preferred extension paths |
| 28 | +- the implementation path and modification style expected for specific tasks |
| 29 | +- a unified source for downstream tool-specific rule files |
| 30 | + |
| 31 | +Once that information is materialized as Skills, it can be consumed directly by AI IDEs, agents, and automation workflows. Developers can also iterate on collaboration practices around those Skills and turn "how this repository should be worked on" into an auditable, commit-friendly, evolvable engineering asset. |
| 32 | + |
| 33 | +## What code2skill Provides |
| 34 | + |
| 35 | +`code2skill` builds project knowledge from real Python repositories and generates a set of outputs that can be written to disk, tracked over time, and integrated into normal engineering workflows. |
| 36 | + |
| 37 | +It covers the full chain from repository scanning, structural analysis, Skill planning, and document generation to tool-specific rule adaptation. It also supports incremental regeneration so Skills can stay aligned as the repository evolves. |
| 38 | + |
| 39 | +For one-off local analysis, `code2skill` can scan an entire repository and generate the full result set. |
| 40 | +For ongoing development workflows, it can combine historical state and code diffs to rebuild only the affected Skills, reducing repeated generation cost and making CI-based updates practical. |
12 | 41 |
|
13 | 42 | ## What It Guarantees |
14 | 43 |
|
@@ -39,6 +68,61 @@ From one Python repository, `code2skill` can produce: |
39 | 68 | - `report.json` for execution metrics, token estimates, and impact summaries |
40 | 69 | - `state/analysis-state.json` for incremental CI reuse |
41 | 70 |
|
| 71 | +## The Role Of Skills In A Repository |
| 72 | + |
| 73 | +Skills are the standardized AI-facing expression layer of repository knowledge. |
| 74 | + |
| 75 | +They connect repository structure, implementation details, team conventions, and tool rules so an AI system can enter the project with one consistent context source instead of repeatedly reconstructing it from README files, scattered docs, previous implementations, and chat history. |
| 76 | + |
| 77 | +In engineering practice, that creates direct value: |
| 78 | + |
| 79 | +- it gives AI IDEs a unified, stable, low-noise project entry point |
| 80 | +- it lets developers turn recurring implementation patterns into reusable guidance |
| 81 | +- it helps future changes follow the same boundaries and extension paths already present in the repository |
| 82 | +- it gives rule-file generation a single consistent source of truth |
| 83 | +- it keeps repository knowledge incrementally maintained as code changes, instead of periodically rewritten by hand |
| 84 | + |
| 85 | +That is why `code2skill` is really about organizing, transmitting, and updating repository knowledge for AI collaboration. |
| 86 | + |
| 87 | +## Incremental Updates And Ongoing Maintenance |
| 88 | + |
| 89 | +Repository knowledge needs to evolve with the code. |
| 90 | + |
| 91 | +`code2skill` supports incremental regeneration based on historical analysis state and the current change scope. After code changes, it can identify the affected areas, rebuild the relevant Skills, and preserve outputs that are still valid. That makes it suitable for local development loops, pull request checks, and continuous CI automation. |
| 92 | + |
| 93 | +This workflow has several practical benefits: |
| 94 | + |
| 95 | +- it reduces the cost of repeated full regeneration on larger repositories |
| 96 | +- it keeps Skills synchronized with the current code state |
| 97 | +- it moves project-knowledge maintenance into the normal development process |
| 98 | +- it makes generated outputs reviewable, comparable, and commit-friendly |
| 99 | + |
| 100 | +Skills therefore become a long-lived engineering asset rather than a temporary prompt artifact. |
| 101 | + |
| 102 | +## Adapting To Multiple AI Tools |
| 103 | + |
| 104 | +Different AI coding tools use different rule file formats, but they all need high-quality project context. |
| 105 | + |
| 106 | +`code2skill` first generates a unified Skill-centered knowledge layer, then uses `adapt` to copy or merge that layer into target-specific formats, including: |
| 107 | + |
| 108 | +- `AGENTS.md` |
| 109 | +- `CLAUDE.md` |
| 110 | +- `.cursor/rules/*` |
| 111 | +- `.github/copilot-instructions.md` |
| 112 | +- `.windsurfrules` |
| 113 | + |
| 114 | +That approach lets a repository maintain one core knowledge representation and distribute consistent context and constraints to multiple AI tools without duplicating maintenance effort. |
| 115 | + |
| 116 | +## When To Use code2skill |
| 117 | + |
| 118 | +`code2skill` is a good fit for: |
| 119 | + |
| 120 | +- Python repositories that want a stable project context for AI IDEs |
| 121 | +- teams that want repository knowledge committed as files instead of kept in chat threads |
| 122 | +- engineering workflows that need CI-based updates for AI rule files |
| 123 | +- projects that want diff-aware control over regeneration scope and cost |
| 124 | +- repositories that need one knowledge source adapted to multiple AI coding tools |
| 125 | + |
42 | 126 | ## Pipeline |
43 | 127 |
|
44 | 128 | ### Phase 1: Structural Scan |
|
0 commit comments