code2skill-generate

Files (41)

• SKILL.md
• openai.yaml · agents/
• MCP-SETUP.md · assets/
• MCP-SETUP.zh-CN.md · assets/
• canonical-contract.json · assets/
• core-MCP-SETUP.md · assets/
• core-MCP-SETUP.zh-CN.md · assets/
• core-feature-context.md · assets/
• core-feature-context.zh-CN.md · assets/
• export-profile.json · assets/
• feature-context.md · assets/
• feature-context.zh-CN.md · assets/
• host-profile.json · assets/
• mcp-runtime-entry.mjs · assets/
• portable-agent-result.mjs · assets/
• portable-error-normalizer.mjs · assets/
• portable-workflow-guard.mjs · assets/
• source-topology.json · assets/
• verification-report.md · assets/
• verification-report.schema.json · assets/
• verification-report.zh-CN.md · assets/
• SKILL.zh-CN.md · references/
• artifact-contract.md · references/
• capability-model.md · references/
• documentation-contract.md · references/
• evidence-and-discovery.md · references/
• mcp-tool-design.md · references/
• observed-skill-design.md · references/
• verification.md · references/
• vnext-architecture.md · references/
• vnext-architecture.zh-CN.md · references/
• compile_artifacts.py · scripts/
• contract_model.py · scripts/
• derive_artifacts.py · scripts/
• finalize_export.py · scripts/
• probe_mcp.py · scripts/
• run_pipeline.py · scripts/
• run_vectors.py · scripts/
• validate_artifacts.py · scripts/
• validate_core_export.py · scripts/
• validate_vnext.py · scripts/

SKILL.md (first lines)

# Code2Skill

Complete Chinese version: [SKILL.zh-CN.md](references/SKILL.zh-CN.md).

Use the user's language for the final response, generated Skills, and user-facing documentation. When no language is explicitly requested, follow the language of the user's current request.

Turn the business capabilities of an existing application into Functions, MCP tools, and Skills that other agents can use. The default goal is a small, reliable runtime package, not an audit archive of the source code.

Use the current coding agent to search, understand, and modify user-authorized code; do not build a separate scanner. The Consumer of the generated package may not be the current agent. Do not assume that it can read the original repository, files on the Producer machine, or session state, except for controlled attachment paths or attachment references explicitly passed to a tool by the Consumer Host.

## Default Generated Result

Unless the user explicitly requests a strict audit, generate only:

```text
generated/code2skill/<feature-id>/
├── SKILL.md                    # Used when there is only one primary goal
├── skills/                     # Replaces the root SKILL.md when there are multiple primary goals
│   ├── <goal-a>/SKILL.md
│   └── <goal-b>/SKILL.md
├── MCP-SETUP.md
├── package.json              # Current node-stdio profile example: package metadata, runtime scripts, and dependencies
├── function-core/
│   └── index.mjs             # Current node-stdio profile example
├── mcp-tool/
│   └── index.mjs             # Current node-stdio profile example
├── portable-agent-result.mjs # Generic result projection helper for node-stdio (readHttpResponse/httpResultFromError are HTTP-only)
├── tests/
│   └── *.test.mjs            # Current node-stdio profile example
└── references/
    └── feature-context.md     # Generated only when business context cannot be kept concise in the Skill
```

The default artifact composition remains the same, while extensions, dependencies, and startup methods follow the runtime profile. `core-export-v1` is implemented by `node-stdio`.

Use either a root `SKILL.md` or `skills/*/SKILL.md`, never both. A page or directory specified by the user is only the search scope: first identify the primary user goals within it that can be completed independently. Generate a root Skill for one goal; for multiple goals, generate an independent Skill for each and share the same set of atomic Functions and MCP tools. Do not split Skills by interface count or use one large Skill to cover unrelated goals.

When multiple goals use `skills/<goal-id>/SKILL.md`, place references under the corresponding Skill's `references/` directory. Do not make an installed Skill depend on files in its parent directory. The root `references/feature-context.md` applies only to a single root Skill.

Do not generate Canonical/Goal Contracts, Capability Graphs, Host Profiles, Verification Matrices, manifests, hash receipts, other audit files, long MCP documentation, or live receipts in the default package. Temporary analysis notes and test output do not belong in the delivered package.

Code is the maintenance source of truth: Functions are the truth of business execution, MCP is the standard adapter layer, and Skills are the agent's usage knowledge. Avoid describing the same fact repeatedly in multiple JSON files or long documents.

## Default Workflow

### 1. Define the Scope

- Start from the page, directory, interface, route, symbol, or functional goal specified by the user.
- Search only source roots explicitly authorized by the user; do not scan the entire machine. When the user has not explicitly limited the scope, follow direct imports and aliases within the same repository to close dependencies. Do not cross repository boundaries or a constraint such as “only these roots.” Record the missing symbol or file for unavailable dependencies; do not prematurely declare the capability missing on that basis.
- Treat the specified scope as a discovery boundary. First list the primary user goals within it that can be independently triggered, guided, and completed; this may produce one or more Skills.
- The unit of a Skill is a primary user goal, not a directory, file, interface, or input field.
- Read the target repository's rules and existing tests first.

### 2. Identify Goal Decision Boundaries

For each goal, the Producer first forms a minimal temporary graph in **working memory**: user goal → known/missing information → query/selection/validation → branches and stopping conditions → pre-write presentation/confirmation → write → result query/reconciliation when present in source. A purely read-only goal has no write node. Do not invent anything without source evidence.

Each node has exactly one primary role: agent judgment/question/selection | user interaction/confirmation | an independently nameable, callable, reusable, or stoppable MCP tool | a deterministic step inside a Function | a result boundary of completed/stopped/unconfirmed. Constraint owners, which may overlap, are: backend authority | Consumer Host policy | a deterministic Guard proven by source to be non-bypassable. A write tool may carry both Host confirmation and a Guard; do not choose only one. See “Design Capabilities” for the Guard evidence threshold. Keep this graph only in working memory; do not generate an intermediate file or include it in the delivered package.

### 3. Determine the Capability Surface from Real Invocation Points

Business invocation points that actually exist in source code define the Function/MCP candidate surface. When a client or Consumer exists, follow its call chain. Without a client, start from a user-specified public API, RPC, Service, message, or task entry point that source code proves callable. Include only logic that affects those entry points:

- Invocation target and operation (HTTP: method/URL/query/header/body/multipart; RPC: service/method/arguments; message/task: destination/key/payload; in-process Service: method and runtime context).
- Response fields, return values, receipts, or task IDs that the caller actually uses.
- Defaults, transformations, dynamic options, conditional inputs, and error handling.
- User goals, primary branches, stopping points, and information presented before submission.
- How attachment upload results bind to later calls.

Do not automatically expose a tool merely because the backend contains an internal method, arbitrary public method, Repository, message consumer, or scheduled task. Do not mechanically turn a page, request, control, or input field into a tool.

Prefer putting hard-coded page menus, copy, and configuration into the Skill or optional Feature Context. Generate a tool for local data only when that data can independently satisfy a user goal, must be reused by multiple capabilities, or must be read at runtime.

### 4. Perform a Bounded Transport-Contract Check

By default, use backend, protocol, or test source only to complete the public transport contract: the structure and nullability of Request/Response types, interface definitions, Service method signatures, and message/task contracts; authentication, identity boundaries, and runtime-context injection points; common response envelopes and public fields such as `code`, `message`, and `data`; explicitly public enums and attachment upload interfaces. Stop when the contract is sufficient for generation. Do not trace Service, persistence, messages, approvals, downstream RPC, the complete side-effect graph, or every business validation by default.

Continue deeper only when public contracts contradict one another; the operation has clear financial, deletion, publication, or other high-risk effects; source code explicitly contains a non-bypassable security credential or ordering constraint; or the user explicitly requests a deep audit.

The real backend invocation point is authoritative for whether an ordinary business call is accepted. Do not copy the entire backend rule set into a Function or predict success from HTTP status or business fields. Pass the backend response or invocation result to the Consumer Agent so it can judge the result, correct the call, ask for missing information, or explain the outcome.

### 5. Design Capabilities

A tool should express a business capability that can be independently named, called, reused, or stopped. Split by business meaning, input/output stability, and side effects—not by source file or HTTP call count.

Positive conditions for an additional tool, any one of which is sufficient: an intermediate result changes a later call, branch, or parameter; the capability can independently complete part of the goal or be reused; the steps before and after it have different permission, side-effect, or confirmation requirements; the intermediate stage may stop or wait for user input; or source proves an asynchronous status query or reconciliation after a write. Negative conditions against splitting: only to make the model reason more often; deterministic implementation such as request assembly, field formatting, or RAG; the next step is always the same regardless of the intermediate result; splitting exposes meaningless intermediate state; or multiple calls form an indivisible transaction.

One tool may call multiple internal APIs, and one API may support multiple business tools. Do not map mechanically by interface count. Split only nodes whose primary role is MCP tool. Do not rename agent judgment/questions, user confirmation, or deterministic Function-internal steps merely to force a split.

For each capability, define only the minimal contract: a stable operation identity (tool name, title, invocation target, operation identifier, version/routing key); mapping from public inputs to real invocation fields; known parameter names, provenance, purpose, type/order/serialization; response fields, receipts, or task IDs required for downstream handoff and the next decision; binding (HTTP: method/URL/query/header/body/multipart; RPC: service/method/arguments; message/task: destination/key/payload; in-process Service: method and runtime context); read/create/update/delete side effects; and authentication, runtime-context, and attachment requirements. Routing/version/context and result/error/timeout/retry boundaries must be proven by source and reproduced consistently by the Function.

In HTTP scenarios, the business API base URL is deployment configuration, not user business input. In other scenarios, refer to the equivalent concept as “business service connection configuration.” Declare environment variables per independent service, for example `CODE2SKILL_<FEATURE>_<SERVICE>_BASE_URL` in HTTP scenarios. Do not expose a base URL or any connection configuration as a tool parameter, and do not use source test, staging, production, or fixed addresses as defaults. Source-proven environment addresses may appear in `MCP-SETUP.md` as deployment references; the Consumer Host must inject the actual runtime value explicitly. Object-storage, callback, or presigned URLs dynamically returned by an invocation result or backend response are not static base URLs.

Do not infer semantics from field names alone. For same-name fields, trace provenance, assignment, and purpose. When their meanings differ, use public names that reflect the real purpose and map them internally to the actual invocation fields. Perform source binding for every write capability and every “query → selection → later invocation” chain: trace upstream response → caller normalization → each downstream wire representation. When one upstream value enters multiple downstream calls, independently trace “raw value → normalized value → each downstream wire” at every use site. Do not reuse one representation merely because semantics appear similar or a tool is shared. When source rewrites an upstream value, trace the normalization itself and the normalized result at every downstream use; do not treat the raw representation as usable downstream.

When the client expands or merges multiple fields—or an entire row object—from a selected result into a later request, model it as selected-record handoff. If the downstream call reads only a few fields, expose them individually. If it forwards the entire row, use a business-named open object such as `selectedOrder`. The Function must merge in source order and preserve explicit override relationships. Unless evidence proves that passing only an identifier is equivalent, the Skill's standard example must pass the record; whether omitting it is accepted remains for the backend to decide.

MCP must declare an input Schema, but by default it is parameter guidance for the agent, not a business gatekeeper. Use open objects. Prefer `unknown().optional()` with descriptions for known business fields; do not generate enums, formats, ranges, conditional requirements, or strict types by default. Preserve only the minimum transport constraint when a URL, attachment, or other transport structure cannot be formed without a value. Accept additional parameters; do not set `additionalProperties: false` or use strict objects. The Function must assemble invocations only from source-proven bindings and must not block a call with narrower schemas, types, or local rules. Preserve additional parameters for the callback and agent. When no destination for them is proven, do not guess or claim that they were sent.

Do not declare `outputSchema` by default. Tool descriptions and Skills may describe known response fields, but real variations such as HTTP status, `null`, missing fields, numeric strings, and additional fields must reach the agent first. Add an optional, open `outputSchema` that does not block known variants only when the user explicitly requires machine-typed output and the public contract is sufficiently stable.

Ordinary write interfaces are validated by the backend by default. Implement a deterministic Guard only when source explicitly proves a non-bypassable identity, provenance, transaction, one-time credential, or ordering constraint. A page confirmation dialog, ordinary POST, ordinary backend rejection, or shared query does not by itself prove the need for a custom Host Guard.

### 6. Implement Functions and MCP

The Producer chooses an approach based on the target repository's existing implementation. Do not prebuild framework-specific generators inside Code2Skill:

- **Approach A: Directly runnable thin wrapper.** Reuse an existing HTTP, RPC, gRPC, SDK, or command client. Wrap only parameter mapping, deterministic transformations, authentication integration, and result forwarding.
- **Approach B: Wrapper inside the original runtime.** For dependency injection, transactions, interceptors, thread context, or in-process Service scenarios, generate a thin wrapper in the original project's technology stack. Do not move business methods into a new Node package and pretend the semantics are equivalent. If the target runtime is not the currently verifiable `node-stdio` profile—for example an in-process Java or Python Service—this version handles it as Approach C.
- **Approach C: Host integration required.** When no safely callable client or runtime context is available, preserve the Skill, tool contract, and integration instructions, and set `code2skill.requiresHostIntegration` in `package.json`. Do not generate a universal `call_rpc`, `invoke_method`, or `publish_message` tool or claim that the capability is deployed.

For asynchronous publication or task enqueueing, state only “accepted” or “enqueued.” Generate a separate status capability only when status-query source exists. Do not present a receipt or task ID as business completion.

General rules: each tool has a same-named independent Function export; Function Core exports a Zod Schema; public field names express business meaning and map internally to real fields; authentication, invocation construction, and deterministic transformations must be owned by the Function (date/time, formatting, defaults, renaming, arrays/URLs, ordering, serialization, and context); concatenation, formatting, and normalization must not be pushed to the agent or evaded through open Schema or backend authority; construct the wire representation of the same value independently at different call sites; MCP uses SDK/Zod (the current `node-stdio` profile example); every tool provides a name, `title`, `description`, open `inputSchema`, and annotations; omit `outputSchema` by default; after a result is obtained, use `toAgentResult` to pass it to the agent unchanged; only project low-level exceptions that produced no response through `toAgentError`; dry-run sends no network traffic or writes; module initialization must not make business requests; inject business service connection configuration through the environment (the API base URL in HTTP scenarios), return a configuration error before invocation when it is missing, and never fall back to test, staging, or production.

#### HTTP-Specific Rules

A `fetch`-based implementation returns `httpStatus` and complete `bodyText` for every HTTP status. When an HTTP client throws for 4xx or 5xx, recover its status and response as an ordinary tool result. Only low-level exceptions that produced no response go through `toAgentError`. Do not derive success, failure, unknown-result, or retry conclusions from a response envelope or business `code`. Under the `node-stdio` profile, copy `portable-agent-result.mjs`; HTTP targets use its `readHttpResponse` and `httpResultFromError`.

From leechen298/Code2Skill, MIT.

More from leechen298/Code2Skill