agent-skillforge 0.1.0__tar.gz → 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agent_skillforge-0.3.0/PKG-INFO +294 -0
- agent_skillforge-0.3.0/README.md +256 -0
- {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/pyproject.toml +29 -8
- agent_skillforge-0.3.0/src/agent_skillforge.egg-info/PKG-INFO +294 -0
- {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/agent_skillforge.egg-info/SOURCES.txt +15 -0
- {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/agent_skillforge.egg-info/requires.txt +2 -0
- {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/skillforge/__init__.py +1 -2
- agent_skillforge-0.3.0/src/skillforge/adapters.py +330 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/agent-observability/SKILL.md +25 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/antislop-code/SKILL.md +37 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/blast-radius-containment/SKILL.md +33 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/caveman/SKILL.md +24 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/cognitive-loop-breaker/SKILL.md +44 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/context-compactor/SKILL.md +30 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/flaky-test-isolation/SKILL.md +44 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/human-in-the-loop/SKILL.md +26 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/mcp-tool-designer/SKILL.md +28 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/performance-profiler/SKILL.md +35 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/runtime-api-verification/SKILL.md +45 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/security-threat-modeler/SKILL.md +37 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/self-improving-agent/SKILL.md +24 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/skill-architect/SKILL.md +37 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/skill-architect/references/mechanics.md +27 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/spec-driven-development/SKILL.md +25 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/summarize/SKILL.md +20 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/systematic-debugging/SKILL.md +37 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/tavily-search/SKILL.md +23 -0
- agent_skillforge-0.3.0/src/skillforge/builtin_skills/zero-downtime-migration/SKILL.md +42 -0
- agent_skillforge-0.3.0/src/skillforge/cli.py +475 -0
- {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/skillforge/errors.py +4 -0
- {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/skillforge/mcp_server.py +41 -2
- agent_skillforge-0.3.0/src/skillforge/registry.py +304 -0
- agent_skillforge-0.3.0/src/skillforge/security.py +367 -0
- agent_skillforge-0.3.0/src/skillforge/skill.py +316 -0
- agent_skillforge-0.3.0/tests/test_adapters.py +88 -0
- {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/tests/test_builtins.py +22 -1
- agent_skillforge-0.3.0/tests/test_cli.py +223 -0
- {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/tests/test_mcp_server.py +24 -3
- {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/tests/test_registry.py +34 -2
- agent_skillforge-0.3.0/tests/test_security.py +106 -0
- {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/tests/test_skill.py +23 -0
- agent_skillforge-0.1.0/PKG-INFO +0 -84
- agent_skillforge-0.1.0/README.md +0 -54
- agent_skillforge-0.1.0/src/agent_skillforge.egg-info/PKG-INFO +0 -84
- agent_skillforge-0.1.0/src/skillforge/adapters.py +0 -80
- agent_skillforge-0.1.0/src/skillforge/builtin_skills/agent-observability/SKILL.md +0 -19
- agent_skillforge-0.1.0/src/skillforge/builtin_skills/caveman/SKILL.md +0 -22
- agent_skillforge-0.1.0/src/skillforge/builtin_skills/human-in-the-loop/SKILL.md +0 -15
- agent_skillforge-0.1.0/src/skillforge/builtin_skills/self-improving-agent/SKILL.md +0 -15
- agent_skillforge-0.1.0/src/skillforge/builtin_skills/spec-driven-development/SKILL.md +0 -15
- agent_skillforge-0.1.0/src/skillforge/builtin_skills/summarize/SKILL.md +0 -17
- agent_skillforge-0.1.0/src/skillforge/builtin_skills/tavily-search/SKILL.md +0 -19
- agent_skillforge-0.1.0/src/skillforge/cli.py +0 -107
- agent_skillforge-0.1.0/src/skillforge/registry.py +0 -151
- agent_skillforge-0.1.0/src/skillforge/skill.py +0 -76
- agent_skillforge-0.1.0/tests/test_adapters.py +0 -42
- agent_skillforge-0.1.0/tests/test_cli.py +0 -79
- {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/LICENSE +0 -0
- {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/setup.cfg +0 -0
- {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/agent_skillforge.egg-info/dependency_links.txt +0 -0
- {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/agent_skillforge.egg-info/entry_points.txt +0 -0
- {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/agent_skillforge.egg-info/top_level.txt +0 -0
- {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/skillforge/__main__.py +0 -0
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agent-skillforge
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Universal package manager, security auditor, and MCP server for portable agent skills (SKILL.md).
|
|
5
|
+
Author-email: gintingism <gintingism@users.noreply.github.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/gintingism/skillforge
|
|
8
|
+
Project-URL: Repository, https://github.com/gintingism/skillforge
|
|
9
|
+
Project-URL: Issues, https://github.com/gintingism/skillforge/issues
|
|
10
|
+
Project-URL: Documentation, https://gintingism.github.io/skillforge/
|
|
11
|
+
Keywords: agent-skills,skills,agentskills,mcp,claude-code,cursor,antigravity,windsurf,security-audit,prompt-injection,developer-tools
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Topic :: Security
|
|
20
|
+
Classifier: Topic :: Software Development :: Build Tools
|
|
21
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Requires-Dist: mcp>=2.3.0
|
|
26
|
+
Requires-Dist: PyYAML>=6.0
|
|
27
|
+
Requires-Dist: typer>=0.12
|
|
28
|
+
Provides-Extra: dev
|
|
29
|
+
Requires-Dist: build>=1.0; extra == "dev"
|
|
30
|
+
Requires-Dist: mypy>=1.10; extra == "dev"
|
|
31
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
32
|
+
Requires-Dist: pytest-cov>=5.0; extra == "dev"
|
|
33
|
+
Requires-Dist: twine>=5.0; extra == "dev"
|
|
34
|
+
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
|
|
35
|
+
Provides-Extra: docs
|
|
36
|
+
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
|
|
37
|
+
Dynamic: license-file
|
|
38
|
+
|
|
39
|
+
# SkillForge
|
|
40
|
+
|
|
41
|
+
A package manager and security linter for portable agent skills (`SKILL.md`).
|
|
42
|
+
|
|
43
|
+
If you use Claude Code, Cursor, Google Antigravity, Windsurf, or Copilot, you've probably noticed two problems with agent instructions:
|
|
44
|
+
|
|
45
|
+
1. **System prompt bloat:** Dumping every coding guideline, style guide, and workflow directly into your global system prompt burns tokens on every turn and muddles model reasoning.
|
|
46
|
+
2. **Third-party skill safety:** Community skills are executable instructions. Loading unverified `SKILL.md` files or running their bundled scripts without checking for prompt injection or data exfiltration is an open invite for supply-chain attacks.
|
|
47
|
+
|
|
48
|
+
SkillForge follows the open `SKILL.md` standard (established under the Agentic AI Foundation / AAIF). It gives you a clean way to find, security-audit, install, and bundle skills across whatever coding assistant you or your team use.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Installation
|
|
53
|
+
|
|
54
|
+
From PyPI:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pip install agent-skillforge
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
To run directly as a module if preferred: `python -m skillforge`
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## Core Workflows
|
|
65
|
+
|
|
66
|
+
### 1. Grab a skill directly from GitHub (`add`)
|
|
67
|
+
|
|
68
|
+
Instead of cloning a repo, finding the skill folder, and copying files manually:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
# Pull a specific skill from a GitHub repo
|
|
72
|
+
skillforge add anthropics/skills:pdf
|
|
73
|
+
|
|
74
|
+
# Or from your own team's repository
|
|
75
|
+
skillforge add gintingism/skillforge:systematic-debugging
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
SkillForge fetches the skill, runs a security check against it, installs it into your project's active assistant folders, and pins its SHA-256 package digest in `skillforge.lock`.
|
|
79
|
+
|
|
80
|
+
To install and verify all locked skills across a team checkout or CI environment:
|
|
81
|
+
```bash
|
|
82
|
+
skillforge sync
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### 2. Audit a skill before running it (`audit`)
|
|
86
|
+
|
|
87
|
+
Before letting an agent read and execute a skill, inspect it for hidden payloads, broken progressive disclosure links, and prompt injection:
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
skillforge audit ./skills/my-new-skill
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Example output:
|
|
94
|
+
```text
|
|
95
|
+
Audit Report: my-new-skill
|
|
96
|
+
Status: PASSED (Score: 100/100)
|
|
97
|
+
Context Load: 24 pointer tokens | 280 body tokens (42 lines)
|
|
98
|
+
Total Findings: 0
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
What the auditor scans for:
|
|
102
|
+
- **Invisible Unicode (SEC-001):** Zero-width spaces (`\u200B`, `\uFEFF`), homoglyphs, and directional overrides used to hide prompt instructions from human code review.
|
|
103
|
+
- **Prompt Injections & Jailbreaks (SEC-002):** Directives like `"ignore previous instructions"`, `"system override"`, or attempts to disable safety guardrails.
|
|
104
|
+
- **Dangerous Shell Commands (SEC-003):** Script patterns like `curl ... | bash`, base64-decoded execution, and outbound data exfiltration.
|
|
105
|
+
- **Credential Path Access (SEC-004):** Unsanctioned attempts to access `~/.ssh`, `~/.aws/credentials`, or local environment secrets.
|
|
106
|
+
- **Trigger Quality (QUAL-001):** Checks whether model-invoked descriptions contain explicit activation conditions (skipped when `disable-model-invocation: true`).
|
|
107
|
+
- **Directory Alignment (QUAL-002):** Verifies the package folder name matches the skill `name` in YAML frontmatter.
|
|
108
|
+
- **Progressive Disclosure Budget (QUAL-003):** Flags `SKILL.md` bodies exceeding 500 lines or ~5,000 tokens so heavy reference docs are moved into `references/`.
|
|
109
|
+
- **Broken Disclosure Pointers (QUAL-004):** Verifies every `references/...` or `scripts/...` file cited in `SKILL.md` actually exists in the package.
|
|
110
|
+
|
|
111
|
+
For CI pipelines, pass `--strict` to fail on any warning, or `--json` for automation:
|
|
112
|
+
```bash
|
|
113
|
+
skillforge audit ./skills/my-new-skill --strict --json
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### 3. Profile your project's context token budget (`budget`)
|
|
117
|
+
|
|
118
|
+
Every model-invoked skill keeps its `name` and `description` in the startup context window on every turn. Measure how much context your skills consume before they even trigger:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
skillforge budget
|
|
122
|
+
# Or inspect the built-in catalog:
|
|
123
|
+
skillforge budget --builtin
|
|
124
|
+
```
|
|
125
|
+
```text
|
|
126
|
+
Context Budget Profile (19 skills)
|
|
127
|
+
Always-Loaded Startup Pointer Cost: ~912 tokens
|
|
128
|
+
On-Demand SKILL.md Body Cost: ~5420 tokens
|
|
129
|
+
Disclosed Resources Cost: ~245 tokens
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### 4. Check what's installed in your project (`list` & `remove`)
|
|
133
|
+
|
|
134
|
+
See which skills are active across your editor targets:
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
skillforge list
|
|
138
|
+
```
|
|
139
|
+
```text
|
|
140
|
+
Installed Skills:
|
|
141
|
+
[ClaudeCode]:
|
|
142
|
+
- antislop-code
|
|
143
|
+
- systematic-debugging
|
|
144
|
+
[Cursor]:
|
|
145
|
+
- antislop-code
|
|
146
|
+
- systematic-debugging
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
To remove a skill from all detected assistants and update your lockfile:
|
|
150
|
+
```bash
|
|
151
|
+
skillforge remove antislop-code
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### 5. Create and package your own skills (`create` & `pack`)
|
|
155
|
+
|
|
156
|
+
Scaffold a single skill file or a full directory package with scripts and reference docs:
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
# Standard skill file
|
|
160
|
+
skillforge create api-design -d "Design REST/gRPC APIs. Use when creating new backend endpoints."
|
|
161
|
+
|
|
162
|
+
# Full package with scripts/ and references/
|
|
163
|
+
skillforge create db-migrator -d "Run Postgres migrations safely. Use when writing SQL schema updates." --full
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Pack it into a shareable zip archive (or unpack one safely with path traversal protection):
|
|
167
|
+
```bash
|
|
168
|
+
skillforge pack ./db-migrator --output ./db-migrator.zip
|
|
169
|
+
skillforge unpack ./db-migrator.zip --output ./skills
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## Supported Assistants
|
|
175
|
+
|
|
176
|
+
SkillForge automatically detects which assistants your repository uses and places the skill files in the right folder:
|
|
177
|
+
|
|
178
|
+
| Assistant | Detected by | Installed location |
|
|
179
|
+
| :--- | :--- | :--- |
|
|
180
|
+
| **Google Antigravity / Gemini CLI** | `.gemini/` | `.gemini/config/skills/<name>/SKILL.md` |
|
|
181
|
+
| **Claude Code & Claude Desktop** | `.claude/` | `.claude/skills/<name>/SKILL.md` |
|
|
182
|
+
| **Cursor** | `.cursor/` | `.cursor/skills/<name>/SKILL.md` |
|
|
183
|
+
| **Windsurf** | `.windsurf/`, `.windsurfrules` | `.windsurf/skills/<name>/SKILL.md` |
|
|
184
|
+
| **Cline / Roo-Code** | `.cline/`, `.roomodes` | `.cline/skills/<name>/SKILL.md` |
|
|
185
|
+
| **Codex / Universal Agents** | `AGENTS.md`, `.agents/` | Appended to `AGENTS.md` catalog |
|
|
186
|
+
| **GitHub Copilot** | `.github/` | `.github/copilot-instructions.md` |
|
|
187
|
+
|
|
188
|
+
To install a skill to your user home directory instead of the current project, add `--global` (`-g`):
|
|
189
|
+
```bash
|
|
190
|
+
skillforge install systematic-debugging --global
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## Shipped Built-in Skills
|
|
196
|
+
|
|
197
|
+
SkillForge ships with 19 practical engineering skills designed to counteract common agent failure modes identified in benchmark research (SWE-bench):
|
|
198
|
+
|
|
199
|
+
### Code Quality, Security & Performance
|
|
200
|
+
- `blast-radius-containment`: Upstream reference tracing and a strict "file touch budget" before modifying shared code or public APIs.
|
|
201
|
+
- `security-threat-modeler`: Trust-boundary mapping, IDOR/BOLA object-level authorization checks, SSRF validation, and injection sink verification.
|
|
202
|
+
- `performance-profiler`: Baseline-first latency (`p50`/`p95`/`p99`), N+1 query detection, and algorithmic complexity verification before optimizing.
|
|
203
|
+
- `antislop-code`: Comment hygiene and anti-overengineering filters (removes trivial narrative comments, stops speculative generality).
|
|
204
|
+
- `spec-driven-development`: Schema-first API design and red-green verification loops before writing application logic.
|
|
205
|
+
- `zero-downtime-migration`: Four-phase Expand-Contract pattern for non-breaking database schema and API payload evolutions.
|
|
206
|
+
|
|
207
|
+
### Autonomous Loop Stability & Debugging
|
|
208
|
+
- `systematic-debugging`: Disciplined four-phase diagnosis protocol (Reproduce, Isolate, Hypothesize, Surgical Patch) before touching code.
|
|
209
|
+
- `cognitive-loop-breaker`: Three-strikes circuit breaker that forces a hard `git restore` and hypothesis invalidation when stuck in repetitive edit-fail loops.
|
|
210
|
+
- `flaky-test-isolation`: Stress-reproduction loop (50x iterations) and diagnosis protocol for race conditions, clock skew, and state leakage.
|
|
211
|
+
- `runtime-api-verification`: Interactive signature introspection (`inspect`, `dir()`, compiler definitions) to prevent hallucinated kwargs.
|
|
212
|
+
|
|
213
|
+
### Context Efficiency & Multi-Agent Operations
|
|
214
|
+
- `skill-architect`: Multi-file progressive disclosure guide (bundled with `references/mechanics.md`) for authoring low-token `SKILL.md`, `AGENTS.md`, and `CLAUDE.md` files.
|
|
215
|
+
- `caveman`: Terse, high-density technical communication mode that reduces token spend while preserving exact paths, commands, and errors.
|
|
216
|
+
- `context-compactor`: Structured state distillation and active hypothesis ledgers for long-running agent threads nearing context limits.
|
|
217
|
+
- `mcp-tool-designer`: Type-safe schema design, idempotent hints, token boundaries, and stderr error separation for MCP servers.
|
|
218
|
+
- `agent-observability`: OpenTelemetry tracing standards, step timing, and 16KB payload truncation boundaries.
|
|
219
|
+
- `human-in-the-loop`: Three-tier permission model separating read-only queries from irreversible actions.
|
|
220
|
+
- `summarize`: Executive engineering summaries with exact file and line citations.
|
|
221
|
+
- `tavily-search`: Authoritative primary-source technical research with cross-verification.
|
|
222
|
+
- `self-improving-agent`: Error recording loop that turns recurring bugs into durable project rules.
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## Model Context Protocol (MCP) Integration
|
|
227
|
+
|
|
228
|
+
SkillForge can run as an MCP server so your agent can search, read, and audit skills during its workflow:
|
|
229
|
+
|
|
230
|
+
```json
|
|
231
|
+
{
|
|
232
|
+
"mcpServers": {
|
|
233
|
+
"skillforge": {
|
|
234
|
+
"command": "skillforge",
|
|
235
|
+
"args": ["serve-mcp"],
|
|
236
|
+
"env": {
|
|
237
|
+
"SKILLFORGE_REGISTRY_PATH": ".skillforge"
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
Exposed MCP tools:
|
|
245
|
+
- `search_skills(query, limit)`: Search local and built-in skill catalogs.
|
|
246
|
+
- `get_skill(name)`: Read the full `SKILL.md` instructions.
|
|
247
|
+
- `get_skill_resource(name, resource_path)`: Read disclosed `references/*` or `scripts/*` files from a skill package on demand.
|
|
248
|
+
- `validate_skill(content)`: Test frontmatter syntax.
|
|
249
|
+
- `audit_skill(content)`: Audit a raw skill document for prompt injections and malicious patterns.
|
|
250
|
+
- `skill://{name}`: Resource URI for direct document retrieval.
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## Publishing to PyPI
|
|
255
|
+
|
|
256
|
+
SkillForge is published to PyPI under the package name `agent-skillforge`.
|
|
257
|
+
|
|
258
|
+
### Prerequisites for GitHub Actions Deployment
|
|
259
|
+
1. Ensure your repository has Trusted Publishing configured on [PyPI](https://pypi.org/manage/account/publishing/):
|
|
260
|
+
- **PyPI Project Name:** `agent-skillforge`
|
|
261
|
+
- **Owner:** `gintingism`
|
|
262
|
+
- **Repository:** `skillforge`
|
|
263
|
+
- **Workflow name:** `publish.yml`
|
|
264
|
+
- **Environment:** `pypi`
|
|
265
|
+
2. Bump the version in `pyproject.toml` (e.g. `0.2.0`).
|
|
266
|
+
|
|
267
|
+
### Triggering a Release
|
|
268
|
+
You can publish through any of these three methods:
|
|
269
|
+
- **Git tag:** `git tag v0.2.0 && git push origin v0.2.0`
|
|
270
|
+
- **GitHub Release:** Publish a new release in the GitHub UI.
|
|
271
|
+
- **Manual dispatch:** Go to the GitHub Actions tab → "Publish package" → click "Run workflow".
|
|
272
|
+
|
|
273
|
+
### Local build check
|
|
274
|
+
To test building distributions locally before releasing:
|
|
275
|
+
```bash
|
|
276
|
+
python -m pip install --upgrade build twine
|
|
277
|
+
python -m build
|
|
278
|
+
python -m twine check dist/*
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
---
|
|
282
|
+
|
|
283
|
+
## Contributing & Development
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
git clone https://github.com/gintingism/skillforge.git
|
|
287
|
+
cd skillforge
|
|
288
|
+
|
|
289
|
+
python -m pip install -e ".[dev]"
|
|
290
|
+
pytest
|
|
291
|
+
mypy src
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
License: [MIT](LICENSE)
|
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
# SkillForge
|
|
2
|
+
|
|
3
|
+
A package manager and security linter for portable agent skills (`SKILL.md`).
|
|
4
|
+
|
|
5
|
+
If you use Claude Code, Cursor, Google Antigravity, Windsurf, or Copilot, you've probably noticed two problems with agent instructions:
|
|
6
|
+
|
|
7
|
+
1. **System prompt bloat:** Dumping every coding guideline, style guide, and workflow directly into your global system prompt burns tokens on every turn and muddles model reasoning.
|
|
8
|
+
2. **Third-party skill safety:** Community skills are executable instructions. Loading unverified `SKILL.md` files or running their bundled scripts without checking for prompt injection or data exfiltration is an open invite for supply-chain attacks.
|
|
9
|
+
|
|
10
|
+
SkillForge follows the open `SKILL.md` standard (established under the Agentic AI Foundation / AAIF). It gives you a clean way to find, security-audit, install, and bundle skills across whatever coding assistant you or your team use.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## Installation
|
|
15
|
+
|
|
16
|
+
From PyPI:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
pip install agent-skillforge
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
To run directly as a module if preferred: `python -m skillforge`
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Core Workflows
|
|
27
|
+
|
|
28
|
+
### 1. Grab a skill directly from GitHub (`add`)
|
|
29
|
+
|
|
30
|
+
Instead of cloning a repo, finding the skill folder, and copying files manually:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
# Pull a specific skill from a GitHub repo
|
|
34
|
+
skillforge add anthropics/skills:pdf
|
|
35
|
+
|
|
36
|
+
# Or from your own team's repository
|
|
37
|
+
skillforge add gintingism/skillforge:systematic-debugging
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
SkillForge fetches the skill, runs a security check against it, installs it into your project's active assistant folders, and pins its SHA-256 package digest in `skillforge.lock`.
|
|
41
|
+
|
|
42
|
+
To install and verify all locked skills across a team checkout or CI environment:
|
|
43
|
+
```bash
|
|
44
|
+
skillforge sync
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### 2. Audit a skill before running it (`audit`)
|
|
48
|
+
|
|
49
|
+
Before letting an agent read and execute a skill, inspect it for hidden payloads, broken progressive disclosure links, and prompt injection:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
skillforge audit ./skills/my-new-skill
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Example output:
|
|
56
|
+
```text
|
|
57
|
+
Audit Report: my-new-skill
|
|
58
|
+
Status: PASSED (Score: 100/100)
|
|
59
|
+
Context Load: 24 pointer tokens | 280 body tokens (42 lines)
|
|
60
|
+
Total Findings: 0
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
What the auditor scans for:
|
|
64
|
+
- **Invisible Unicode (SEC-001):** Zero-width spaces (`\u200B`, `\uFEFF`), homoglyphs, and directional overrides used to hide prompt instructions from human code review.
|
|
65
|
+
- **Prompt Injections & Jailbreaks (SEC-002):** Directives like `"ignore previous instructions"`, `"system override"`, or attempts to disable safety guardrails.
|
|
66
|
+
- **Dangerous Shell Commands (SEC-003):** Script patterns like `curl ... | bash`, base64-decoded execution, and outbound data exfiltration.
|
|
67
|
+
- **Credential Path Access (SEC-004):** Unsanctioned attempts to access `~/.ssh`, `~/.aws/credentials`, or local environment secrets.
|
|
68
|
+
- **Trigger Quality (QUAL-001):** Checks whether model-invoked descriptions contain explicit activation conditions (skipped when `disable-model-invocation: true`).
|
|
69
|
+
- **Directory Alignment (QUAL-002):** Verifies the package folder name matches the skill `name` in YAML frontmatter.
|
|
70
|
+
- **Progressive Disclosure Budget (QUAL-003):** Flags `SKILL.md` bodies exceeding 500 lines or ~5,000 tokens so heavy reference docs are moved into `references/`.
|
|
71
|
+
- **Broken Disclosure Pointers (QUAL-004):** Verifies every `references/...` or `scripts/...` file cited in `SKILL.md` actually exists in the package.
|
|
72
|
+
|
|
73
|
+
For CI pipelines, pass `--strict` to fail on any warning, or `--json` for automation:
|
|
74
|
+
```bash
|
|
75
|
+
skillforge audit ./skills/my-new-skill --strict --json
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### 3. Profile your project's context token budget (`budget`)
|
|
79
|
+
|
|
80
|
+
Every model-invoked skill keeps its `name` and `description` in the startup context window on every turn. Measure how much context your skills consume before they even trigger:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
skillforge budget
|
|
84
|
+
# Or inspect the built-in catalog:
|
|
85
|
+
skillforge budget --builtin
|
|
86
|
+
```
|
|
87
|
+
```text
|
|
88
|
+
Context Budget Profile (19 skills)
|
|
89
|
+
Always-Loaded Startup Pointer Cost: ~912 tokens
|
|
90
|
+
On-Demand SKILL.md Body Cost: ~5420 tokens
|
|
91
|
+
Disclosed Resources Cost: ~245 tokens
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### 4. Check what's installed in your project (`list` & `remove`)
|
|
95
|
+
|
|
96
|
+
See which skills are active across your editor targets:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
skillforge list
|
|
100
|
+
```
|
|
101
|
+
```text
|
|
102
|
+
Installed Skills:
|
|
103
|
+
[ClaudeCode]:
|
|
104
|
+
- antislop-code
|
|
105
|
+
- systematic-debugging
|
|
106
|
+
[Cursor]:
|
|
107
|
+
- antislop-code
|
|
108
|
+
- systematic-debugging
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
To remove a skill from all detected assistants and update your lockfile:
|
|
112
|
+
```bash
|
|
113
|
+
skillforge remove antislop-code
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### 5. Create and package your own skills (`create` & `pack`)
|
|
117
|
+
|
|
118
|
+
Scaffold a single skill file or a full directory package with scripts and reference docs:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
# Standard skill file
|
|
122
|
+
skillforge create api-design -d "Design REST/gRPC APIs. Use when creating new backend endpoints."
|
|
123
|
+
|
|
124
|
+
# Full package with scripts/ and references/
|
|
125
|
+
skillforge create db-migrator -d "Run Postgres migrations safely. Use when writing SQL schema updates." --full
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Pack it into a shareable zip archive (or unpack one safely with path traversal protection):
|
|
129
|
+
```bash
|
|
130
|
+
skillforge pack ./db-migrator --output ./db-migrator.zip
|
|
131
|
+
skillforge unpack ./db-migrator.zip --output ./skills
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## Supported Assistants
|
|
137
|
+
|
|
138
|
+
SkillForge automatically detects which assistants your repository uses and places the skill files in the right folder:
|
|
139
|
+
|
|
140
|
+
| Assistant | Detected by | Installed location |
|
|
141
|
+
| :--- | :--- | :--- |
|
|
142
|
+
| **Google Antigravity / Gemini CLI** | `.gemini/` | `.gemini/config/skills/<name>/SKILL.md` |
|
|
143
|
+
| **Claude Code & Claude Desktop** | `.claude/` | `.claude/skills/<name>/SKILL.md` |
|
|
144
|
+
| **Cursor** | `.cursor/` | `.cursor/skills/<name>/SKILL.md` |
|
|
145
|
+
| **Windsurf** | `.windsurf/`, `.windsurfrules` | `.windsurf/skills/<name>/SKILL.md` |
|
|
146
|
+
| **Cline / Roo-Code** | `.cline/`, `.roomodes` | `.cline/skills/<name>/SKILL.md` |
|
|
147
|
+
| **Codex / Universal Agents** | `AGENTS.md`, `.agents/` | Appended to `AGENTS.md` catalog |
|
|
148
|
+
| **GitHub Copilot** | `.github/` | `.github/copilot-instructions.md` |
|
|
149
|
+
|
|
150
|
+
To install a skill to your user home directory instead of the current project, add `--global` (`-g`):
|
|
151
|
+
```bash
|
|
152
|
+
skillforge install systematic-debugging --global
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## Shipped Built-in Skills
|
|
158
|
+
|
|
159
|
+
SkillForge ships with 19 practical engineering skills designed to counteract common agent failure modes identified in benchmark research (SWE-bench):
|
|
160
|
+
|
|
161
|
+
### Code Quality, Security & Performance
|
|
162
|
+
- `blast-radius-containment`: Upstream reference tracing and a strict "file touch budget" before modifying shared code or public APIs.
|
|
163
|
+
- `security-threat-modeler`: Trust-boundary mapping, IDOR/BOLA object-level authorization checks, SSRF validation, and injection sink verification.
|
|
164
|
+
- `performance-profiler`: Baseline-first latency (`p50`/`p95`/`p99`), N+1 query detection, and algorithmic complexity verification before optimizing.
|
|
165
|
+
- `antislop-code`: Comment hygiene and anti-overengineering filters (removes trivial narrative comments, stops speculative generality).
|
|
166
|
+
- `spec-driven-development`: Schema-first API design and red-green verification loops before writing application logic.
|
|
167
|
+
- `zero-downtime-migration`: Four-phase Expand-Contract pattern for non-breaking database schema and API payload evolutions.
|
|
168
|
+
|
|
169
|
+
### Autonomous Loop Stability & Debugging
|
|
170
|
+
- `systematic-debugging`: Disciplined four-phase diagnosis protocol (Reproduce, Isolate, Hypothesize, Surgical Patch) before touching code.
|
|
171
|
+
- `cognitive-loop-breaker`: Three-strikes circuit breaker that forces a hard `git restore` and hypothesis invalidation when stuck in repetitive edit-fail loops.
|
|
172
|
+
- `flaky-test-isolation`: Stress-reproduction loop (50x iterations) and diagnosis protocol for race conditions, clock skew, and state leakage.
|
|
173
|
+
- `runtime-api-verification`: Interactive signature introspection (`inspect`, `dir()`, compiler definitions) to prevent hallucinated kwargs.
|
|
174
|
+
|
|
175
|
+
### Context Efficiency & Multi-Agent Operations
|
|
176
|
+
- `skill-architect`: Multi-file progressive disclosure guide (bundled with `references/mechanics.md`) for authoring low-token `SKILL.md`, `AGENTS.md`, and `CLAUDE.md` files.
|
|
177
|
+
- `caveman`: Terse, high-density technical communication mode that reduces token spend while preserving exact paths, commands, and errors.
|
|
178
|
+
- `context-compactor`: Structured state distillation and active hypothesis ledgers for long-running agent threads nearing context limits.
|
|
179
|
+
- `mcp-tool-designer`: Type-safe schema design, idempotent hints, token boundaries, and stderr error separation for MCP servers.
|
|
180
|
+
- `agent-observability`: OpenTelemetry tracing standards, step timing, and 16KB payload truncation boundaries.
|
|
181
|
+
- `human-in-the-loop`: Three-tier permission model separating read-only queries from irreversible actions.
|
|
182
|
+
- `summarize`: Executive engineering summaries with exact file and line citations.
|
|
183
|
+
- `tavily-search`: Authoritative primary-source technical research with cross-verification.
|
|
184
|
+
- `self-improving-agent`: Error recording loop that turns recurring bugs into durable project rules.
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## Model Context Protocol (MCP) Integration
|
|
189
|
+
|
|
190
|
+
SkillForge can run as an MCP server so your agent can search, read, and audit skills during its workflow:
|
|
191
|
+
|
|
192
|
+
```json
|
|
193
|
+
{
|
|
194
|
+
"mcpServers": {
|
|
195
|
+
"skillforge": {
|
|
196
|
+
"command": "skillforge",
|
|
197
|
+
"args": ["serve-mcp"],
|
|
198
|
+
"env": {
|
|
199
|
+
"SKILLFORGE_REGISTRY_PATH": ".skillforge"
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Exposed MCP tools:
|
|
207
|
+
- `search_skills(query, limit)`: Search local and built-in skill catalogs.
|
|
208
|
+
- `get_skill(name)`: Read the full `SKILL.md` instructions.
|
|
209
|
+
- `get_skill_resource(name, resource_path)`: Read disclosed `references/*` or `scripts/*` files from a skill package on demand.
|
|
210
|
+
- `validate_skill(content)`: Test frontmatter syntax.
|
|
211
|
+
- `audit_skill(content)`: Audit a raw skill document for prompt injections and malicious patterns.
|
|
212
|
+
- `skill://{name}`: Resource URI for direct document retrieval.
|
|
213
|
+
|
|
214
|
+
---
|
|
215
|
+
|
|
216
|
+
## Publishing to PyPI
|
|
217
|
+
|
|
218
|
+
SkillForge is published to PyPI under the package name `agent-skillforge`.
|
|
219
|
+
|
|
220
|
+
### Prerequisites for GitHub Actions Deployment
|
|
221
|
+
1. Ensure your repository has Trusted Publishing configured on [PyPI](https://pypi.org/manage/account/publishing/):
|
|
222
|
+
- **PyPI Project Name:** `agent-skillforge`
|
|
223
|
+
- **Owner:** `gintingism`
|
|
224
|
+
- **Repository:** `skillforge`
|
|
225
|
+
- **Workflow name:** `publish.yml`
|
|
226
|
+
- **Environment:** `pypi`
|
|
227
|
+
2. Bump the version in `pyproject.toml` (e.g. `0.2.0`).
|
|
228
|
+
|
|
229
|
+
### Triggering a Release
|
|
230
|
+
You can publish through any of these three methods:
|
|
231
|
+
- **Git tag:** `git tag v0.2.0 && git push origin v0.2.0`
|
|
232
|
+
- **GitHub Release:** Publish a new release in the GitHub UI.
|
|
233
|
+
- **Manual dispatch:** Go to the GitHub Actions tab → "Publish package" → click "Run workflow".
|
|
234
|
+
|
|
235
|
+
### Local build check
|
|
236
|
+
To test building distributions locally before releasing:
|
|
237
|
+
```bash
|
|
238
|
+
python -m pip install --upgrade build twine
|
|
239
|
+
python -m build
|
|
240
|
+
python -m twine check dist/*
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
## Contributing & Development
|
|
246
|
+
|
|
247
|
+
```bash
|
|
248
|
+
git clone https://github.com/gintingism/skillforge.git
|
|
249
|
+
cd skillforge
|
|
250
|
+
|
|
251
|
+
python -m pip install -e ".[dev]"
|
|
252
|
+
pytest
|
|
253
|
+
mypy src
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
License: [MIT](LICENSE)
|
|
@@ -4,18 +4,36 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "agent-skillforge"
|
|
7
|
-
version = "0.
|
|
8
|
-
description = "
|
|
7
|
+
version = "0.3.0"
|
|
8
|
+
description = "Universal package manager, security auditor, and MCP server for portable agent skills (SKILL.md)."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = "MIT"
|
|
11
11
|
authors = [
|
|
12
12
|
{ name = "gintingism", email = "gintingism@users.noreply.github.com" },
|
|
13
13
|
]
|
|
14
|
-
keywords = [
|
|
14
|
+
keywords = [
|
|
15
|
+
"agent-skills",
|
|
16
|
+
"skills",
|
|
17
|
+
"agentskills",
|
|
18
|
+
"mcp",
|
|
19
|
+
"claude-code",
|
|
20
|
+
"cursor",
|
|
21
|
+
"antigravity",
|
|
22
|
+
"windsurf",
|
|
23
|
+
"security-audit",
|
|
24
|
+
"prompt-injection",
|
|
25
|
+
"developer-tools",
|
|
26
|
+
]
|
|
15
27
|
classifiers = [
|
|
16
|
-
"Development Status ::
|
|
28
|
+
"Development Status :: 4 - Beta",
|
|
29
|
+
"Environment :: Console",
|
|
30
|
+
"Intended Audience :: Developers",
|
|
17
31
|
"Programming Language :: Python :: 3",
|
|
18
32
|
"Programming Language :: Python :: 3 :: Only",
|
|
33
|
+
"Programming Language :: Python :: 3.11",
|
|
34
|
+
"Programming Language :: Python :: 3.12",
|
|
35
|
+
"Topic :: Security",
|
|
36
|
+
"Topic :: Software Development :: Build Tools",
|
|
19
37
|
"Topic :: Software Development :: Libraries",
|
|
20
38
|
]
|
|
21
39
|
requires-python = ">=3.11"
|
|
@@ -27,9 +45,11 @@ dependencies = [
|
|
|
27
45
|
|
|
28
46
|
[project.optional-dependencies]
|
|
29
47
|
dev = [
|
|
48
|
+
"build>=1.0",
|
|
30
49
|
"mypy>=1.10",
|
|
31
50
|
"pytest>=8.0",
|
|
32
51
|
"pytest-cov>=5.0",
|
|
52
|
+
"twine>=5.0",
|
|
33
53
|
"types-PyYAML>=6.0",
|
|
34
54
|
]
|
|
35
55
|
docs = [
|
|
@@ -49,7 +69,11 @@ Documentation = "https://gintingism.github.io/skillforge/"
|
|
|
49
69
|
where = ["src"]
|
|
50
70
|
|
|
51
71
|
[tool.setuptools.package-data]
|
|
52
|
-
skillforge = [
|
|
72
|
+
skillforge = [
|
|
73
|
+
"builtin_skills/*/SKILL.md",
|
|
74
|
+
"builtin_skills/*/*",
|
|
75
|
+
"builtin_skills/*/*/*",
|
|
76
|
+
]
|
|
53
77
|
|
|
54
78
|
[tool.pytest.ini_options]
|
|
55
79
|
testpaths = ["tests"]
|
|
@@ -58,6 +82,3 @@ addopts = "-q"
|
|
|
58
82
|
[tool.mypy]
|
|
59
83
|
strict = true
|
|
60
84
|
packages = ["skillforge"]
|
|
61
|
-
|
|
62
|
-
[tool.coverage.report]
|
|
63
|
-
fail_under = 80
|