mirror of
https://github.com/personamanagmentlayer/pcl.git
synced 2026-09-14 15:40:22 +08:00
ANGX
4e07a6a874
* chore(stdlib): add conformance tooling for the skills library
The library had no gate that could express what a valid skill is, so
malformed frontmatter, over-budget files and credential literals went
unnoticed. These scripts define and enforce that contract.
- validate-skills.py: extend with Agent Skills v1.0 conformance -
naming rules and directory agreement, an explicit activation trigger
in the description, canonical layout, the 500-line SKILL.md budget,
relative-link integrity, and two security rules (no unrestricted
Bash(*) grant, no credential literals). Structural checks now read a
skill as a whole so material moved into references/ still counts.
- split-skill-references.py: move the heaviest sections of an oversized
SKILL.md into references/. Verifies line by line that every source
line lands in exactly one output and refuses to write otherwise.
- generate-skill-inventory.py: derive SKILLS_INVENTORY.md and
DIRECTORY_STRUCTURE.md from the tree so they cannot drift.
- generate-skill-catalog.py: index the canonical layout only, count
references/ toward a skill's size, and stop truncating descriptions
at 200 characters - the catalog is the discovery surface and must
carry the activation trigger.
- .gitignore: Python bytecode from these scripts, and local .pcl state.
Reviewed-by: Security Analyst, Compiler Engineer, DevX Engineer
* fix(stdlib): bring all 174 skills to Agent Skills v1.0 conformance
No skill in the library was conformant. 41 of 175 failed the existing
validator outright, and none satisfied the spec. This pass fixes the
tree and records the result. See stdlib/CHANGELOG.md for the per-skill
versioning and migration notes.
BREAKING CHANGE: one skill removed, five moved, seven with a capability
withdrawn. Library version 2.0.0 -> 3.0.0.
Structure
- Convert 71 skills stored as flat files to <category>/<name>/SKILL.md,
the layout the spec requires and the only one able to carry companion
resources.
- Rename 5 directories that disagreed with their declared name:, so
resolution by path and by name stop giving different answers. The
repository docs already referenced the corrected paths.
- Merge the duplicate legal-technology skills into legaltech-expert and
delete legal-tech-expert, carrying over everything the survivor
lacked.
Metadata
- Repair 20 unparseable frontmatters: an H1 preceded the --- block and
the key was skill_id: instead of name:, so any parser reading
frontmatter at offset 0 saw no metadata at all. The objectives,
prerequisites and outcome they carried become real body sections.
- Add the missing version: to 21 skills, fold keywords into tags, move
expertise_level under metadata, and align 10 category: values with
their directory.
Discoverability
- Give all 174 descriptions an explicit "Use when ..." trigger, built
from each skill's own tags and section headings. 152 previously said
only what the skill was about, leaving an agent nothing to match on.
Progressive disclosure
- Split 127 oversized skills, moving bulk material into references/ read
on demand and leaving an index behind. A SKILL.md now averages 277
lines instead of 644 and none exceeds 500. Verified lossless line by
line against the previous revision.
Security
- Withdraw the unrestricted Bash(*) grant from 7 skills; none of the six
non-financial ones contained a single shell command. finance-expert
documents code that charges cards and reads bank accounts, so it now
grants no shell at all.
- Remove credential literals: Stripe keys, two JWT signing keys, an
Express session secret, a Redis password and WiFi credentials, all
inlined in examples. They load from the environment now.
- finance-expert: idempotency keys were documented but absent, so a
retry double-charged; webhook signature failures were not caught, so a
forged event raised uncaught instead of being rejected;
int(amount * 100) truncated fractions of a cent. All fixed, plus a
money-movement guardrails section.
- trading-expert: place_order routed without any pre-trade risk check
although a RiskManager sat unused in the next section. Risk validation
now runs before routing and raises rather than returning a boolean a
caller can ignore; live routing is opt-in.
- Correct an Ansible Vault example that showed plaintext under an
"encrypted" label.
Also fixes 8 broken documentation links and a prematurely closed code
fence in skill-creator-expert that leaked template content into prose.
Per the repository file-organization policy, four stale progress reports
(SKILLS_MANIFEST, COMPLETE_SKILLS_LIBRARY, COMPLETE_LIBRARY_MANIFEST,
PHASE_3_DATA_ANALYTICS) move out of stdlib/ into the gitignored
.roadmap/status/stdlib/; they claimed 31 of 100 skills complete. They
appear here as deletions because .roadmap/ is not tracked.
Reviewed-by: Security Analyst, Language Designer, DevX Engineer,
Documentation Specialist
* fix(skills): resolve standard library skills from their real layout
No stdlib skill was resolvable. SkillResolver looked for
`<stdlibDir>/<name>.md` with stdlibDir defaulting to `stdlib/skills`, a
directory that does not exist, and the path ignored the category level
the library actually uses. The two LSP providers had the same wrong
directory and scanned only one level deep, so neither completion nor
go-to-definition could see a skill either.
- skill-discovery.ts: enumerate skill entry points across the shapes in
use - a flat `<name>.md`, `<name>/SKILL.md`, and
`<category>/<name>/SKILL.md` - while skipping references/, scripts/
and assets/, which hold supporting material rather than entry points.
- skill-resolver.ts: point stdlibDir at `stdlib`, and look the name up
as a directory under any category as well as the two legacy shapes, so
existing custom stdlib directories keep working. The name is used as a
single path segment and rejected if it contains a separator or
traversal, so a reference cannot escape the stdlib root.
- Rewire both LSP providers onto the shared discovery helper.
Tests: 13 new cases covering the layouts, ordering, the references/
exclusion, path-traversal rejection, and an integration test that
resolves real shipped skills by bare name.
Reviewed-by: Compiler Engineer, Runtime Architect, Security Analyst
* feat(stdlib): add 17 skills covering the library's largest gaps
Selection was driven by cross-referencing coverage against observed usage
rather than by intuition: Stack Overflow and GitHub Octoverse data for
which technologies matter, and install rankings on public agent-skill
registries for the shape of skills people actually use.
That comparison found a mismatch of form, not only of coverage. The
most-installed skills in the ecosystem are procedures - tdd, refactoring,
frontend design, browser automation - while all 174 existing skills were
domain knowledge shaped as <domain>-expert. The new workflows/ category
closes that gap and introduces the <activity>-workflow convention.
New category workflows/ (4)
- tdd-workflow, refactoring-workflow, debugging-workflow,
code-review-workflow. code-review-workflow complements rather than
replaces code-review-expert: procedure versus judgement. Merge them if
the split proves confusing in use.
Applied AI (3) - the largest coverage gap
- llm-engineering-expert, rag-expert, agent-engineering-expert.
The library referenced LLMs in tags but covered none of it: pgvector
appeared zero times across 174 skills, LangChain once, MCP twice
despite the repository shipping an MCP integration guide.
Capabilities (2)
- document-processing-expert (PDF, DOCX, XLSX, PPTX in one skill),
browser-automation-expert (a client against third-party sites,
distinct from playwright-expert which tests your own application).
Data (3)
- mysql-expert, the second most used database and previously absent
while rarer stores had skills; analytical-databases-expert;
stream-processing-expert.
Security (3)
- secrets-management-expert, supply-chain-security-expert (OWASP A03
2025), identity-access-expert (OWASP A01).
Interface and meta (2)
- accessibility-expert: design/ held only design-expert, which despite
its name covers software architecture, so WCAG had no home.
- skill-router: find and compose skills across 191, with a
disambiguation table for overlapping pairs.
Grouping by decision context rather than by technology keeps the growth
to 17 skills for roughly 50 topics. Five vector stores live inside
rag-expert; four document formats inside document-processing-expert.
Per-tool depth sits in references/, which the progressive-disclosure work
in 3.0.0 made cheap.
Four further gaps are better served by extending existing skills -
PyTorch and TensorFlow in ml-expert, OpenTelemetry in monitoring-expert,
Pulumi and Crossplane in terraform-expert - and are not in this change.
Library 3.0.0 -> 3.1.0, additive only. Adds the workflows label to the
inventory generator; catalogue, inventory, structure and CHANGELOG
regenerated.
Reviewed-by: Product Strategist, Security Analyst, DevX Engineer,
Documentation Specialist
* fix(test): create test directories with mkdtempSync
CodeQL flagged js/insecure-temporary-file (CWE-377) on both suites.
`join(tmpdir(), <predictable name>)` followed by mkdirSync creates a
world-readable directory at a guessable path, so another local user can
pre-create it or plant a symlink between the name being computed and the
directory being created.
mkdtempSync creates the directory atomically with a random suffix and
0700 permissions, which closes both the disclosure and the race.
One occurrence is new in this branch (skill-discovery); the other
pre-dates it in skill-resolver and is fixed in the same pass rather than
left as a known finding in a file this branch already touches.
215 lines
11 KiB
Markdown
215 lines
11 KiB
Markdown
# PCL Standard Library — Changelog
|
|
|
|
Versions follow [semantic versioning](https://semver.org/) per skill. A skill's
|
|
version is declared in the `version:` field of its `SKILL.md`.
|
|
|
|
- **MAJOR** — a consumer that worked before can break: a capability removed from
|
|
`allowed-tools`, a change of resolvable name, or a change of path.
|
|
- **MINOR** — content or metadata added or corrected, compatible either way.
|
|
- **PATCH** — typo or formatting only.
|
|
|
|
---
|
|
|
|
## Library 3.1.0 — 2026-09-05
|
|
|
|
Seventeen new skills, 174 → 191, and a fifteenth category. No breaking changes:
|
|
everything here is additive.
|
|
|
|
Selection was driven by cross-referencing the library's coverage against
|
|
observed usage — Stack Overflow and GitHub Octoverse survey data for
|
|
technologies, and install rankings on public agent-skill registries for the
|
|
_shape_ of skills people actually use.
|
|
|
|
### Added — `workflows/` (new category)
|
|
|
|
The registries' most-installed skills are procedures, not domain knowledge. The
|
|
library had 174 skills of the form `<domain>-expert` and none of the form
|
|
"what do I do, in what order". These four close that gap and introduce the
|
|
`<activity>-workflow` naming convention:
|
|
|
|
| Skill | Covers |
|
|
| ---------------------- | ----------------------------------------------------------- |
|
|
| `tdd-workflow` | Red-green-refactor, characterisation tests, legacy seams |
|
|
| `refactoring-workflow` | Transformation catalogue, parallel change, strangler fig |
|
|
| `debugging-workflow` | Hypothesis and bisection, flaky tests, production debugging |
|
|
| `code-review-workflow` | Review order, severity, per-change-type checklists |
|
|
|
|
`code-review-workflow` complements the existing `code-review-expert` rather than
|
|
replacing it: the workflow is the procedure, the expert is the judgement inside
|
|
it. Consider merging them if the split proves confusing in use.
|
|
|
|
### Added — applied AI
|
|
|
|
The library referenced LLMs in tags but had no skill covering them. `pgvector`
|
|
appeared zero times across 174 skills; `LangChain` once; `MCP` twice, despite
|
|
the repository shipping an MCP integration guide.
|
|
|
|
- `llm-engineering-expert` — prompt design, structured output, evaluation
|
|
harnesses, guardrails, cost and latency
|
|
- `rag-expert` — chunking, hybrid retrieval, reranking, grounding, with five
|
|
vector stores as references rather than as five skills
|
|
- `agent-engineering-expert` — tool design, the bounded loop, memory, MCP,
|
|
multi-agent orchestration, and prompt-injection defence by capability
|
|
separation
|
|
|
|
### Added — capabilities, data, security, interface, meta
|
|
|
|
- `document-processing-expert` — PDF, DOCX, XLSX and PPTX in one skill with four
|
|
references; the most standardised skill category in the ecosystem and entirely
|
|
absent here
|
|
- `browser-automation-expert` — driving a browser as a client against third-party
|
|
sites, including the legal and ethical checks. Distinct from `playwright-expert`,
|
|
which covers browsers as a testing tool against your own application
|
|
- `mysql-expert` — the second most widely used database, previously absent while
|
|
several far rarer stores had skills
|
|
- `analytical-databases-expert` — DuckDB, ClickHouse, Parquet, warehouse cost control
|
|
- `stream-processing-expert` — Flink, Spark Structured Streaming, CDC, watermarks
|
|
- `secrets-management-expert` — vaults, KMS envelope encryption, rotation,
|
|
leak response, post-quantum migration planning
|
|
- `supply-chain-security-expert` — SBOM, SCA, SLSA provenance, signing (OWASP A03)
|
|
- `identity-access-expert` — OAuth 2.1/OIDC, sessions, RBAC/ABAC, multi-tenancy
|
|
(OWASP A01)
|
|
- `accessibility-expert` — WCAG 2.2, ARIA, keyboard, screen readers. The
|
|
`design/` category previously held only `design-expert`, which despite its name
|
|
covers software architecture, leaving accessibility with no home
|
|
- `skill-router` — finding and composing skills across 191, and the disambiguation
|
|
table for overlapping pairs
|
|
|
|
### Grouping
|
|
|
|
Skills were grouped by _decision context_ rather than by technology, so the
|
|
library grows by 17 rather than by roughly 50. Five vector stores share one
|
|
mental model and live inside `rag-expert`; four document formats live inside
|
|
`document-processing-expert`. Per-tool detail sits in `references/`, read on
|
|
demand, which the progressive-disclosure work in 3.0.0 made cheap.
|
|
|
|
Four gaps were addressed by extending existing skills instead of adding new
|
|
ones: PyTorch and TensorFlow belong in `ml-expert`, OpenTelemetry in
|
|
`monitoring-expert`, Pulumi and Crossplane in `terraform-expert`. Those
|
|
extensions are not in this release.
|
|
|
|
### Known limitation
|
|
|
|
Unchanged from 3.0.0: skill versions are still not read at runtime.
|
|
|
|
---
|
|
|
|
## Library 3.0.0 — 2026-09-04
|
|
|
|
Agent Skills v1.0 conformance pass across all 174 skills. **This release
|
|
contains breaking changes**: one skill was removed, five moved, and seven had
|
|
capabilities withdrawn.
|
|
|
|
### Breaking
|
|
|
|
**One skill removed**
|
|
|
|
`domains/legal-tech-expert` covered the same ground as `domains/legaltech-expert`
|
|
with different content. The two were merged into `legaltech-expert` (which keeps
|
|
the naming of the `agtech` / `biotech` / `fintech` / `healthtech` / `proptech` /
|
|
`regtech` family), and `legal-tech-expert` was deleted. Everything the removed
|
|
skill covered that the survivor lacked — learning objectives, prerequisites,
|
|
case-management and compliance practices, practical anti-patterns, platform and
|
|
framework resources — was carried over.
|
|
|
|
_Migration:_ replace references to `legal-tech-expert` with `legaltech-expert`.
|
|
|
|
**Five skills moved** — the directory did not match the declared `name:`, so
|
|
resolution by path and resolution by name disagreed. The directory was corrected
|
|
(`2.0.0`):
|
|
|
|
| Skill | Old path | New path |
|
|
| --------------------- | ----------------------- | ------------------------------ |
|
|
| `education-expert` | `domains/education/` | `domains/education-expert/` |
|
|
| `farming-expert` | `domains/farming/` | `domains/farming-expert/` |
|
|
| `healthcare-expert` | `domains/healthcare/` | `domains/healthcare-expert/` |
|
|
| `logistics-expert` | `domains/logistics/` | `domains/logistics-expert/` |
|
|
| `stockbreeder-expert` | `domains/stockbreeder/` | `domains/stockbreeder-expert/` |
|
|
|
|
_Migration:_ references by skill name are unaffected — they already used the
|
|
`-expert` form. References by path must be updated.
|
|
|
|
**Seven skills lost the unrestricted shell** — `allowed-tools` declared
|
|
`Bash(*)`, granting an unbounded shell. None of the six non-financial skills
|
|
contained a single shell command; all their examples are Python or YAML. The
|
|
grant was narrowed to the commands actually used (`2.0.0`):
|
|
|
|
| Skill | Before | After |
|
|
| ---------------------- | --------- | -------------------------------------------- |
|
|
| `devops-expert` | `Bash(*)` | `Bash(python:*, python3:*, pip:*, pytest:*)` |
|
|
| `elasticsearch-expert` | `Bash(*)` | `Bash(python:*, python3:*, pip:*, pytest:*)` |
|
|
| `finops-expert` | `Bash(*)` | `Bash(python:*, python3:*, pip:*, pytest:*)` |
|
|
| `performance-expert` | `Bash(*)` | `Bash(python:*, python3:*, pip:*, pytest:*)` |
|
|
| `qa-expert` | `Bash(*)` | `Bash(python:*, python3:*, pip:*, pytest:*)` |
|
|
| `sre-expert` | `Bash(*)` | `Bash(python:*, python3:*, pip:*, pytest:*)` |
|
|
| `finance-expert` | `Bash(*)` | _(no shell)_ |
|
|
|
|
`finance-expert` documents code that charges cards and reads bank accounts. It
|
|
is an advisory skill, so it now grants no shell at all: running payment code
|
|
should be a separate, deliberately authorised act.
|
|
|
|
_Migration:_ a workflow that relied on one of these skills to run arbitrary
|
|
commands must declare that capability itself, or use a skill scoped to it.
|
|
|
|
### Added
|
|
|
|
- **Activation triggers.** Every description now states an explicit
|
|
`Use when ...` clause naming the keywords and tasks that should select the
|
|
skill. Previously 152 of 174 descriptions said only what the skill was about,
|
|
giving an agent nothing to match on.
|
|
- **Progressive disclosure.** 127 oversized skills were split: bulk material
|
|
moved into `references/`, read on demand, leaving an index in `SKILL.md`. A
|
|
`SKILL.md` now averages 277 lines instead of 644, and none exceeds 500.
|
|
- **Money-movement and execution guardrails** in `finance-expert` and
|
|
`trading-expert`: test mode by default, human approval before money moves,
|
|
amount and position limits, idempotency, kill switch, audit trail, and the
|
|
regulatory perimeter.
|
|
|
|
### Fixed
|
|
|
|
- **Unparseable metadata in 20 skills.** An H1 preceded the `---` block and the
|
|
key was `skill_id:` instead of `name:`, so any parser reading frontmatter at
|
|
offset 0 saw no metadata at all. Rebuilt; the objectives, prerequisites and
|
|
outcome they carried are now real body sections.
|
|
- **Missing `version:` in 21 skills**; `keywords` folded into `tags`,
|
|
`expertise_level` moved under `metadata`.
|
|
- **Ten skills declared `category: industry-specializations`** while living
|
|
under `domains/`. Aligned, with the original kept as
|
|
`metadata.legacy-category`.
|
|
- **Seventy-one skills stored as flat files** rather than their own directory,
|
|
which prevented them from carrying companion resources. Converted.
|
|
- **Credential literals.** Stripe keys, JWT signing keys, an Express session
|
|
secret, a Redis password and WiFi credentials were inlined in examples, in
|
|
`api-design-expert`, `finance-expert`, `fintech-expert`, `iot-expert`,
|
|
`redis-expert` and `zero-trust-expert`. All load from the environment now. An
|
|
Ansible Vault example that showed plaintext under an "encrypted" label was
|
|
corrected.
|
|
- **Payment correctness in `finance-expert`:** idempotency keys were documented
|
|
but absent (double-charge on retry); webhook signature failures were not
|
|
caught, so a forged event raised uncaught instead of being rejected;
|
|
`int(amount * 100)` truncated fractions of a cent.
|
|
- **Order safety in `trading-expert`:** `place_order` routed without any
|
|
pre-trade risk check although a `RiskManager` sat unused in the next section.
|
|
Risk validation now runs before routing and raises rather than returning a
|
|
boolean a caller can ignore; live routing is opt-in.
|
|
- **Eight broken documentation links** pointing at `docs/reference/*` files that
|
|
do not exist, or written at the wrong directory depth.
|
|
- **A prematurely closed code fence** in `skill-creator-expert` that leaked
|
|
template content into prose.
|
|
|
|
### Known limitation
|
|
|
|
A skill's `version` is **not read at runtime**. `parseSkillMd` ignores both
|
|
`version` and `category`, and `toSkillMd` writes the version into an HTML
|
|
comment rather than the frontmatter, so a load/save round trip loses it.
|
|
Version constraints are not resolvable either: `python-expert@1.0.0` is treated
|
|
as a literal skill name, and the registry passes the version into a free-text
|
|
search then takes the first result. The versions recorded here are therefore
|
|
accurate documentation, but nothing enforces them yet.
|
|
|
|
---
|
|
|
|
## Library 2.0.0 — 2026-01-19
|
|
|
|
Expansion from 100 to 173 skills. All skills at `1.0.0`.
|