Skip to content

Commit e7ee66b

Browse files
fswairfswair
committed
fix bare urls
1 parent 17dbe04 commit e7ee66b

5 files changed

Lines changed: 149 additions & 193 deletions

File tree

‎.agents/skills/acpkit-sdk/SKILL.md‎

Lines changed: 32 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -24,22 +24,22 @@ It does not own the detailed runtime semantics of the adapter packages.
2424
If you only need the shortest high-signal path:
2525

2626
1. read `Quick Routing`
27-
2. open `src/acpkit/cli.py` for command-shape questions
28-
3. open `src/acpkit/runtime.py` for execution-path questions
29-
4. open `src/acpkit/adapters.py` for adapter-selection questions
27+
2. open the [CLI module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/cli.py) for command-shape questions
28+
3. open the [runtime module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/runtime.py) for execution-path questions
29+
4. open the [adapter-dispatch module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/adapters.py) for adapter-selection questions
3030

3131
## Quick Routing
3232

3333
| If the task is about... | Use this skill? | Open first |
3434
| --- | --- | --- |
35-
| `acpkit run ...` or `acpkit serve ...` | Yes | `src/acpkit/cli.py`, `src/acpkit/runtime.py` |
36-
| `module` vs `module:attribute` target resolution | Yes | `src/acpkit/cli.py`, `src/acpkit/runtime.py` |
37-
| missing adapter install hints | Yes | `src/acpkit/adapters.py` |
38-
| native ACP passthrough | Yes | `src/acpkit/adapters.py`, `src/acpkit/runtime.py` |
39-
| `acpkit launch ...` or `launch --command ...` | Yes | `src/acpkit/runtime.py`, `src/acpkit/cli.py` |
40-
| `pydantic_ai.Agent` runtime behavior | No, pair with `pydantic-acp` | `packages/adapters/pydantic-acp/...` |
41-
| LangGraph / DeepAgents runtime behavior | No, pair with `langchain-acp` | `packages/adapters/langchain-acp/...` |
42-
| WebSocket transport or remote mirroring | No, pair with `acpremote` | `packages/transports/acpremote/...` |
35+
| `acpkit run ...` or `acpkit serve ...` | Yes | [CLI module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/cli.py), [runtime module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/runtime.py) |
36+
| `module` vs `module:attribute` target resolution | Yes | [CLI module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/cli.py), [runtime module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/runtime.py) |
37+
| missing adapter install hints | Yes | [adapter-dispatch module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/adapters.py) |
38+
| native ACP passthrough | Yes | [adapter-dispatch module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/adapters.py), [runtime module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/runtime.py) |
39+
| `acpkit launch ...` or `launch --command ...` | Yes | [runtime module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/runtime.py), [CLI module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/cli.py) |
40+
| `pydantic_ai.Agent` runtime behavior | No, pair with `pydantic-acp` | [Pydantic adapter package](https://github.com/vcoderun/acpkit/tree/main/packages/adapters/pydantic-acp) |
41+
| LangGraph / DeepAgents runtime behavior | No, pair with `langchain-acp` | [LangChain adapter package](https://github.com/vcoderun/acpkit/tree/main/packages/adapters/langchain-acp) |
42+
| WebSocket transport or remote mirroring | No, pair with `acpremote` | [Remote transport package](https://github.com/vcoderun/acpkit/tree/main/packages/transports/acpremote) |
4343

4444
## Package Boundary
4545

@@ -75,27 +75,18 @@ What it does not own:
7575

7676
Root-package references:
7777

78-
- Raw skill:
79-
`https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/acpkit-sdk/SKILL.md`
80-
- Raw CLI docs:
81-
`https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/cli.md`
82-
- Raw examples index:
83-
`https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/examples/index.md`
84-
- Rendered CLI docs:
85-
`https://vcoderun.github.io/acpkit/cli/`
86-
- Source tree:
87-
`https://github.com/vcoderun/acpkit/tree/main/src/acpkit`
78+
- [Raw skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/acpkit-sdk/SKILL.md)
79+
- [Raw CLI docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/cli.md)
80+
- [Raw examples index](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/examples/index.md)
81+
- [Rendered CLI docs](https://vcoderun.github.io/acpkit/cli/)
82+
- [Source tree](https://github.com/vcoderun/acpkit/tree/main/src/acpkit)
8883

8984
Cross-package references often needed from this skill:
9085

91-
- Pydantic adapter skill:
92-
`https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/pydantic-acp/SKILL.md`
93-
- LangChain adapter skill:
94-
`https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/langchain-acp/SKILL.md`
95-
- Remote transport skill:
96-
`https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/acpremote/SKILL.md`
97-
- Codex helper skill:
98-
`https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/codex-auth-helper/SKILL.md`
86+
- [Pydantic adapter skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/pydantic-acp/SKILL.md)
87+
- [LangChain adapter skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/langchain-acp/SKILL.md)
88+
- [Remote transport skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/acpremote/SKILL.md)
89+
- [Codex helper skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/codex-auth-helper/SKILL.md)
9990

10091
## Public Entry Points
10192

@@ -185,12 +176,12 @@ It should stay intentionally ignorant about:
185176

186177
| Module | Use it for | Notes |
187178
| --- | --- | --- |
188-
| `src/acpkit/cli.py` | Click command definitions, argument validation, help/flag behavior | First stop for CLI UX bugs |
189-
| `src/acpkit/runtime.py` | `run`, `serve`, `launch`, remote mirror runtime paths | First stop for dispatch behavior after parsing |
190-
| `src/acpkit/adapters.py` | target typing, adapter import/load, native ACP detection | First stop for wrong lane selection |
191-
| `src/acpkit/compatibility.py` | compatibility manifest helpers | Not part of normal runtime dispatch |
192-
| `src/acpkit/_compatibility_schema.py` | manifest schema and validation | Use only for compatibility-surface work |
193-
| `src/acpkit/__main__.py` | console entrypoint | Usually not the source of behavior bugs |
179+
| [CLI module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/cli.py) | Click command definitions, argument validation, help/flag behavior | First stop for CLI UX bugs |
180+
| [Runtime module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/runtime.py) | `run`, `serve`, `launch`, remote mirror runtime paths | First stop for dispatch behavior after parsing |
181+
| [Adapter-dispatch module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/adapters.py) | target typing, adapter import/load, native ACP detection | First stop for wrong lane selection |
182+
| [Compatibility helpers](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/compatibility.py) | compatibility manifest helpers | Not part of normal runtime dispatch |
183+
| [Compatibility schema](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/_compatibility_schema.py) | manifest schema and validation | Use only for compatibility-surface work |
184+
| [Console entrypoint](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/__main__.py) | console entrypoint | Usually not the source of behavior bugs |
194185

195186
## Common Workflows
196187

@@ -250,17 +241,17 @@ Typical combinations:
250241

251242
Skill-local recipe index:
252243

253-
- `https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpkit-sdk/examples/README.md`
244+
- [Skill-local recipe index](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpkit-sdk/examples/README.md)
254245

255246
Public adapter examples commonly launched through the root package:
256247

257-
- `https://raw.githubusercontent.com/vcoderun/acpkit/main/examples/pydantic/README.md`
258-
- `https://raw.githubusercontent.com/vcoderun/acpkit/main/examples/langchain/README.md`
248+
- [Pydantic public examples](https://raw.githubusercontent.com/vcoderun/acpkit/main/examples/pydantic/README.md)
249+
- [LangChain public examples](https://raw.githubusercontent.com/vcoderun/acpkit/main/examples/langchain/README.md)
259250

260251
Remote pairing examples:
261252

262-
- `https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/serve_command.py`
263-
- `https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/mirror_remote.py`
253+
- [Remote command exposure recipe](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/serve_command.py)
254+
- [Remote mirror recipe](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/mirror_remote.py)
264255

265256
## Handoff Rules
266257

@@ -283,6 +274,6 @@ Stay in this skill when:
283274
- Do not claim the root package itself adapts framework runtimes. It routes them.
284275
- Do not describe `acpremote` as an adapter.
285276
- Do not describe `codex-auth-helper` as part of target resolution.
286-
- Do not document a root CLI feature that is not present in `src/acpkit/cli.py`.
277+
- Do not document a root CLI feature that is not present in the [CLI module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/cli.py).
287278
- When the question is about adapter truthfulness, plans, approvals, projections, host ownership,
288279
or provider behavior, move to the narrower package skill.

‎.agents/skills/acpremote/SKILL.md‎

Lines changed: 29 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -22,20 +22,20 @@ That distinction matters:
2222
If you only need the shortest high-signal path:
2323

2424
1. read `Quick Routing`
25-
2. open `server.py` for exposure-path questions
26-
3. open `client.py` and `proxy_agent.py` for mirror-path questions
27-
4. open `command.py` only when the upstream runtime is ACP-over-stdio
25+
2. open the [server transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/server.py) for exposure-path questions
26+
3. open the [remote client module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/client.py) and the [proxy agent module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/proxy_agent.py) for mirror-path questions
27+
4. open the [command transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/command.py) only when the upstream runtime is ACP-over-stdio
2828

2929
## Quick Routing
3030

3131
| If the task is about... | Use this skill? | Open first |
3232
| --- | --- | --- |
33-
| expose an existing ACP agent over WebSocket | Yes | `server.py`, `config.py` |
34-
| expose a stdio ACP command over WebSocket | Yes | `command.py`, `server.py` |
35-
| mirror a remote ACP endpoint locally | Yes | `client.py`, `proxy_agent.py` |
36-
| bearer auth or metadata routes | Yes | `auth.py`, `metadata.py`, `server.py` |
37-
| remote host ownership or `remote_cwd` | Yes | `proxy_agent.py`, `client.py`, `metadata.py` |
38-
| line buffering / frame relay issues | Yes | `stream.py` |
33+
| expose an existing ACP agent over WebSocket | Yes | [server transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/server.py), [transport config module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/config.py) |
34+
| expose a stdio ACP command over WebSocket | Yes | [command transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/command.py), [server transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/server.py) |
35+
| mirror a remote ACP endpoint locally | Yes | [remote client module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/client.py), [proxy agent module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/proxy_agent.py) |
36+
| bearer auth or metadata routes | Yes | [auth helpers](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/auth.py), [metadata module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/metadata.py), [server transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/server.py) |
37+
| remote host ownership or `remote_cwd` | Yes | [proxy agent module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/proxy_agent.py), [remote client module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/client.py), [metadata module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/metadata.py) |
38+
| line buffering / frame relay issues | Yes | [stream bridge module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/stream.py) |
3939
| adapting a Pydantic or LangChain runtime to ACP | No, pair with adapter skill | adapter packages |
4040

4141
## Package Boundary
@@ -71,25 +71,17 @@ It does not own:
7171

7272
Package references:
7373

74-
- Raw skill:
75-
`https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/acpremote/SKILL.md`
76-
- Raw transport docs:
77-
`https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/acpremote.md`
78-
- Raw remote-host docs:
79-
`https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/examples/remote-hosting.md`
80-
- Rendered docs:
81-
`https://vcoderun.github.io/acpkit/acpremote/`
82-
- Source tree:
83-
`https://github.com/vcoderun/acpkit/tree/main/packages/transports/acpremote`
74+
- [Raw skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/acpremote/SKILL.md)
75+
- [Raw transport docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/acpremote.md)
76+
- [Raw remote-host docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/examples/remote-hosting.md)
77+
- [Rendered docs](https://vcoderun.github.io/acpkit/acpremote/)
78+
- [Source tree](https://github.com/vcoderun/acpkit/tree/main/packages/transports/acpremote)
8479

8580
Cross-skill references:
8681

87-
- Root package skill:
88-
`https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/acpkit-sdk/SKILL.md`
89-
- Pydantic adapter skill:
90-
`https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/pydantic-acp/SKILL.md`
91-
- LangChain adapter skill:
92-
`https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/langchain-acp/SKILL.md`
82+
- [Root package skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/acpkit-sdk/SKILL.md)
83+
- [Pydantic adapter skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/pydantic-acp/SKILL.md)
84+
- [LangChain adapter skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/langchain-acp/SKILL.md)
9385

9486
## Public Surface
9587

@@ -111,16 +103,16 @@ Support types:
111103

112104
Package entrypoint:
113105

114-
- `https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/__init__.py`
106+
- [Package entrypoint](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/__init__.py)
115107

116108
## Module Guide
117109

118110
| Subsystem | Key files | Use them for |
119111
| --- | --- | --- |
120-
| server and routing | `server.py`, `auth.py`, `metadata.py`, `config.py`, `limits.py` | server startup, mount paths, metadata, health, auth, limits |
121-
| remote client and proxy behavior | `client.py`, `proxy_agent.py` | remote connection setup, metadata fetch, local mirroring, host ownership |
122-
| command-backed transport | `command.py` | stdio ACP commands that need WebSocket exposure |
123-
| stream plumbing | `stream.py` | line buffering, text/binary frame handling, sender/receiver lifecycle |
112+
| server and routing | [server transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/server.py), [auth helpers](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/auth.py), [metadata module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/metadata.py), [transport config module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/config.py), [limit definitions](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/limits.py) | server startup, mount paths, metadata, health, auth, limits |
113+
| remote client and proxy behavior | [remote client module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/client.py), [proxy agent module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/proxy_agent.py) | remote connection setup, metadata fetch, local mirroring, host ownership |
114+
| command-backed transport | [command transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/command.py) | stdio ACP commands that need WebSocket exposure |
115+
| stream plumbing | [stream bridge module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/stream.py) | line buffering, text/binary frame handling, sender/receiver lifecycle |
124116

125117
## Core Transport Shapes
126118

@@ -184,7 +176,7 @@ If a user reports:
184176
- local filesystem used instead of remote filesystem
185177
- remote agent owning the wrong host
186178

187-
inspect `proxy_agent.py` and metadata flow first.
179+
inspect the [proxy agent module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/proxy_agent.py) and metadata flow first.
188180

189181
## Metadata and Health Surface
190182

@@ -218,9 +210,9 @@ Keep the distinction explicit:
218210

219211
Skill-local examples:
220212

221-
- `https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/serve_command.py`
222-
- `https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/mirror_remote.py`
223-
- `https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/README.md`
213+
- [Remote command exposure recipe](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/serve_command.py)
214+
- [Remote mirror recipe](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/mirror_remote.py)
215+
- [Skill-local example notes](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/README.md)
224216

225217
These demonstrate:
226218

@@ -242,12 +234,9 @@ Pair or switch to:
242234

243235
Common end-to-end references:
244236

245-
- root recipe index:
246-
`https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpkit-sdk/examples/README.md`
247-
- public Pydantic example:
248-
`https://github.com/vcoderun/acpkit/blob/main/examples/pydantic/finance_agent.py`
249-
- public LangChain example:
250-
`https://github.com/vcoderun/acpkit/blob/main/examples/langchain/workspace_graph.py`
237+
- [Root recipe index](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpkit-sdk/examples/README.md)
238+
- [Public Pydantic example](https://github.com/vcoderun/acpkit/blob/main/examples/pydantic/finance_agent.py)
239+
- [Public LangChain example](https://github.com/vcoderun/acpkit/blob/main/examples/langchain/workspace_graph.py)
251240

252241
## Guardrails
253242

0 commit comments

Comments
 (0)