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.
Files changed (63) hide show
  1. agent_skillforge-0.3.0/PKG-INFO +294 -0
  2. agent_skillforge-0.3.0/README.md +256 -0
  3. {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/pyproject.toml +29 -8
  4. agent_skillforge-0.3.0/src/agent_skillforge.egg-info/PKG-INFO +294 -0
  5. {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/agent_skillforge.egg-info/SOURCES.txt +15 -0
  6. {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/agent_skillforge.egg-info/requires.txt +2 -0
  7. {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/skillforge/__init__.py +1 -2
  8. agent_skillforge-0.3.0/src/skillforge/adapters.py +330 -0
  9. agent_skillforge-0.3.0/src/skillforge/builtin_skills/agent-observability/SKILL.md +25 -0
  10. agent_skillforge-0.3.0/src/skillforge/builtin_skills/antislop-code/SKILL.md +37 -0
  11. agent_skillforge-0.3.0/src/skillforge/builtin_skills/blast-radius-containment/SKILL.md +33 -0
  12. agent_skillforge-0.3.0/src/skillforge/builtin_skills/caveman/SKILL.md +24 -0
  13. agent_skillforge-0.3.0/src/skillforge/builtin_skills/cognitive-loop-breaker/SKILL.md +44 -0
  14. agent_skillforge-0.3.0/src/skillforge/builtin_skills/context-compactor/SKILL.md +30 -0
  15. agent_skillforge-0.3.0/src/skillforge/builtin_skills/flaky-test-isolation/SKILL.md +44 -0
  16. agent_skillforge-0.3.0/src/skillforge/builtin_skills/human-in-the-loop/SKILL.md +26 -0
  17. agent_skillforge-0.3.0/src/skillforge/builtin_skills/mcp-tool-designer/SKILL.md +28 -0
  18. agent_skillforge-0.3.0/src/skillforge/builtin_skills/performance-profiler/SKILL.md +35 -0
  19. agent_skillforge-0.3.0/src/skillforge/builtin_skills/runtime-api-verification/SKILL.md +45 -0
  20. agent_skillforge-0.3.0/src/skillforge/builtin_skills/security-threat-modeler/SKILL.md +37 -0
  21. agent_skillforge-0.3.0/src/skillforge/builtin_skills/self-improving-agent/SKILL.md +24 -0
  22. agent_skillforge-0.3.0/src/skillforge/builtin_skills/skill-architect/SKILL.md +37 -0
  23. agent_skillforge-0.3.0/src/skillforge/builtin_skills/skill-architect/references/mechanics.md +27 -0
  24. agent_skillforge-0.3.0/src/skillforge/builtin_skills/spec-driven-development/SKILL.md +25 -0
  25. agent_skillforge-0.3.0/src/skillforge/builtin_skills/summarize/SKILL.md +20 -0
  26. agent_skillforge-0.3.0/src/skillforge/builtin_skills/systematic-debugging/SKILL.md +37 -0
  27. agent_skillforge-0.3.0/src/skillforge/builtin_skills/tavily-search/SKILL.md +23 -0
  28. agent_skillforge-0.3.0/src/skillforge/builtin_skills/zero-downtime-migration/SKILL.md +42 -0
  29. agent_skillforge-0.3.0/src/skillforge/cli.py +475 -0
  30. {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/skillforge/errors.py +4 -0
  31. {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/skillforge/mcp_server.py +41 -2
  32. agent_skillforge-0.3.0/src/skillforge/registry.py +304 -0
  33. agent_skillforge-0.3.0/src/skillforge/security.py +367 -0
  34. agent_skillforge-0.3.0/src/skillforge/skill.py +316 -0
  35. agent_skillforge-0.3.0/tests/test_adapters.py +88 -0
  36. {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/tests/test_builtins.py +22 -1
  37. agent_skillforge-0.3.0/tests/test_cli.py +223 -0
  38. {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/tests/test_mcp_server.py +24 -3
  39. {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/tests/test_registry.py +34 -2
  40. agent_skillforge-0.3.0/tests/test_security.py +106 -0
  41. {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/tests/test_skill.py +23 -0
  42. agent_skillforge-0.1.0/PKG-INFO +0 -84
  43. agent_skillforge-0.1.0/README.md +0 -54
  44. agent_skillforge-0.1.0/src/agent_skillforge.egg-info/PKG-INFO +0 -84
  45. agent_skillforge-0.1.0/src/skillforge/adapters.py +0 -80
  46. agent_skillforge-0.1.0/src/skillforge/builtin_skills/agent-observability/SKILL.md +0 -19
  47. agent_skillforge-0.1.0/src/skillforge/builtin_skills/caveman/SKILL.md +0 -22
  48. agent_skillforge-0.1.0/src/skillforge/builtin_skills/human-in-the-loop/SKILL.md +0 -15
  49. agent_skillforge-0.1.0/src/skillforge/builtin_skills/self-improving-agent/SKILL.md +0 -15
  50. agent_skillforge-0.1.0/src/skillforge/builtin_skills/spec-driven-development/SKILL.md +0 -15
  51. agent_skillforge-0.1.0/src/skillforge/builtin_skills/summarize/SKILL.md +0 -17
  52. agent_skillforge-0.1.0/src/skillforge/builtin_skills/tavily-search/SKILL.md +0 -19
  53. agent_skillforge-0.1.0/src/skillforge/cli.py +0 -107
  54. agent_skillforge-0.1.0/src/skillforge/registry.py +0 -151
  55. agent_skillforge-0.1.0/src/skillforge/skill.py +0 -76
  56. agent_skillforge-0.1.0/tests/test_adapters.py +0 -42
  57. agent_skillforge-0.1.0/tests/test_cli.py +0 -79
  58. {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/LICENSE +0 -0
  59. {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/setup.cfg +0 -0
  60. {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/agent_skillforge.egg-info/dependency_links.txt +0 -0
  61. {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/agent_skillforge.egg-info/entry_points.txt +0 -0
  62. {agent_skillforge-0.1.0 → agent_skillforge-0.3.0}/src/agent_skillforge.egg-info/top_level.txt +0 -0
  63. {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.1.0"
8
- description = "Portable SKILL.md registry, adapters, CLI, and MCP server."
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 = ["skills", "mcp", "copilot", "claude", "developer-tools"]
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 :: 3 - Alpha",
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 = ["builtin_skills/*/SKILL.md"]
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