chore: trim redundant skill docs and sample artifacts
This commit is contained in:
yaojingang
@@ -341,7 +341,6 @@ This project is best for:
|
||||
- Evolution example: [examples/evolution-frontend-review/README.md](examples/evolution-frontend-review/README.md)
|
||||
- Governed example: [examples/governed-incident-command/design-summary.md](examples/governed-incident-command/design-summary.md)
|
||||
- Governed example score: [examples/governed-incident-command/generated-skill/reports/governance_score.json](examples/governed-incident-command/generated-skill/reports/governance_score.json)
|
||||
- World-class roadmap: [WORLD_CLASS_PLAN.md](WORLD_CLASS_PLAN.md)
|
||||
|
||||
## License
|
||||
|
||||
|
||||
@@ -1,106 +0,0 @@
|
||||
# World-Class Plan
|
||||
|
||||
`yao-meta-skill` should not compete by becoming the largest meta-skill. It should compete by becoming the most rigorous lightweight system for creating, evaluating, packaging, and governing reusable agent skills.
|
||||
|
||||
## Positioning
|
||||
|
||||
The intended advantage is:
|
||||
|
||||
- lighter than heavyweight skill-creation systems
|
||||
- more evaluation-aware than purely structural systems
|
||||
- more trustworthy than ambition-heavy skill factories
|
||||
- stronger at lifecycle governance than typical skill creators
|
||||
|
||||
## Scoring Targets
|
||||
|
||||
- Trigger design: `9.4+`
|
||||
- Methodology depth: `9.5+`
|
||||
- Executability: `9.3+`
|
||||
- Evaluation and iteration: `9.5+`
|
||||
- Engineering support: `9.4+`
|
||||
- Cross-platform packaging: `9.2+`
|
||||
- Simplicity: `9.0+`
|
||||
|
||||
## Strategic Pillars
|
||||
|
||||
### 1. Lightweight By Default
|
||||
|
||||
Protect `SKILL.md` from bloat and push detail into the right place.
|
||||
|
||||
### 2. Eval Before Expansion
|
||||
|
||||
Validate routing and boundaries before making the skill bigger.
|
||||
|
||||
### 3. Explicit Boundary Design
|
||||
|
||||
Make scope, exclusions, and near-neighbor behavior legible.
|
||||
|
||||
### 4. Evidence Over Claims
|
||||
|
||||
Expose regressions, family results, failure modes, and change history.
|
||||
|
||||
### 5. Governance As Product
|
||||
|
||||
Treat important skills as maintained assets with owners, cadence, and lifecycle state.
|
||||
|
||||
## Implementation Sequence
|
||||
|
||||
### Phase 1
|
||||
|
||||
- resource boundary spec
|
||||
- governance spec
|
||||
- quality checks wired into validation
|
||||
- visible regression reporting
|
||||
|
||||
### Phase 2
|
||||
|
||||
- thicker benchmark suites
|
||||
- heavier production examples
|
||||
- versioned regression history
|
||||
- maturity scoring and certification ideas
|
||||
|
||||
### Phase 3
|
||||
|
||||
- stronger adapter conformance
|
||||
- broader external benchmark evidence
|
||||
- deeper library governance workflows
|
||||
|
||||
## Four-Dimension Sprint
|
||||
|
||||
The current sprint is aimed at the four dimensions that most directly determine whether this project can challenge first-tier skill-creation systems.
|
||||
|
||||
### Trigger
|
||||
|
||||
- route confusion matrix
|
||||
- contrastive route testing across sibling skills
|
||||
- mutation-based and adversarial route families
|
||||
- judge-backed blind eval so blind acceptance does not depend on one scorer
|
||||
|
||||
### Method
|
||||
|
||||
- promotion policy
|
||||
- explicit gate-selection doctrine
|
||||
- non-skill decision rules for when packaging should not happen
|
||||
- formal skill engineering method and archetype taxonomy
|
||||
|
||||
### Execution
|
||||
|
||||
- one-command route scorecard generation
|
||||
- iteration ledger that shows current route quality and optimization evidence
|
||||
- validation hooks that fail on route ambiguity or route theft
|
||||
|
||||
### Iteration
|
||||
|
||||
- blind and adversarial drift history
|
||||
- promotion rules for visible holdout, blind holdout, adversarial holdout, and route confusion
|
||||
- versioned scorecards that show why a route should or should not be promoted
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
The project is only world-class if it remains:
|
||||
|
||||
- compact at the entrypoint
|
||||
- reproducible in evaluation
|
||||
- explicit in packaging limits
|
||||
- auditable in governance
|
||||
- credible through public evidence
|
||||
@@ -13,7 +13,6 @@ Contents:
|
||||
- `promotion_policy.md`: formal rules for when a route is promotable
|
||||
- `baseline_description.txt`: intentionally weaker trigger description
|
||||
- `improved_description.txt`: current stronger trigger description
|
||||
- `sample_trigger_report.json`: example comparison output using the current recommended threshold
|
||||
- `../reports/description_optimization*.{json,md}`: generated route-optimization reports for the root skill
|
||||
- `failure-cases.md`: current weak spots and regression targets
|
||||
- `packaging_expectations.json`: required packaging behaviors for supported targets
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,46 +0,0 @@
|
||||
# Client Compatibility
|
||||
|
||||
This skill package uses a neutral source-of-truth file:
|
||||
|
||||
- `agents/interface.yaml`
|
||||
|
||||
That file is the canonical metadata source for:
|
||||
|
||||
- display metadata
|
||||
- adapter targets
|
||||
- activation mode
|
||||
- execution context
|
||||
- shell expectations
|
||||
- trust boundaries
|
||||
- degradation rules
|
||||
|
||||
## Compatibility Strategy
|
||||
|
||||
Use a two-layer model:
|
||||
|
||||
1. **Canonical source**
|
||||
- Keep brand-neutral metadata in `agents/interface.yaml`.
|
||||
- Keep behavior in `SKILL.md`, `references/`, and `scripts/`.
|
||||
- Keep activation, execution, and trust declarations in neutral metadata rather than target-specific files.
|
||||
|
||||
2. **Adapter outputs**
|
||||
- Generate client-specific metadata only when exporting or packaging.
|
||||
- Do not keep vendor-specific metadata files in the source tree unless a client strictly requires them.
|
||||
- Preserve neutral execution and trust semantics inside generated adapters.
|
||||
|
||||
## Supported Targets
|
||||
|
||||
The current adapter flow is designed for:
|
||||
|
||||
- OpenAI-compatible clients
|
||||
- Claude-compatible clients
|
||||
- generic Agent Skills clients
|
||||
|
||||
## Compatibility Rules
|
||||
|
||||
- Keep `SKILL.md` as the primary behavior definition.
|
||||
- Keep client metadata minimal but semantically meaningful.
|
||||
- Avoid putting client-specific logic in the main workflow.
|
||||
- Prefer packaging-time conversion over source-tree duplication.
|
||||
- Prefer one neutral portability profile over multiple divergent vendor trees.
|
||||
- Declare how remote or untrusted environments should behave before exporting adapters.
|
||||
@@ -1,113 +0,0 @@
|
||||
# Comparative Analysis
|
||||
|
||||
This reference distills four meta-skill archetypes into one design system.
|
||||
|
||||
## Shared Logic
|
||||
|
||||
All four approaches converge on the same model:
|
||||
|
||||
1. A skill is a folderized capability package, not a prompt snippet.
|
||||
2. Frontmatter description is the trigger surface.
|
||||
3. Long instructions should be split by progressive disclosure.
|
||||
4. Skills are most valuable for repeated, multi-step, tool-using workflows.
|
||||
5. Skills become more valuable when they are portable, maintainable, and shareable.
|
||||
|
||||
## Structure-First Creator
|
||||
|
||||
Primary strengths:
|
||||
|
||||
- clear structure and boundary discipline
|
||||
- strong context-efficiency mindset
|
||||
- good guidance on progressive disclosure
|
||||
- pragmatic skeleton for authoring without overbuilding
|
||||
|
||||
Primary gaps:
|
||||
|
||||
- lighter on trigger benchmarking than the eval-first archetype
|
||||
- lighter on distribution and registry than the factory archetype
|
||||
- less opinionated on organizational operations beyond good authoring practice
|
||||
|
||||
Use it for:
|
||||
|
||||
- canonical package structure
|
||||
- concise writing standard
|
||||
- deciding what belongs in `SKILL.md` vs `references/`
|
||||
|
||||
## Eval-First Creator
|
||||
|
||||
Primary strengths:
|
||||
|
||||
- eval-first mindset
|
||||
- explicit trigger optimization
|
||||
- positive and negative prompt testing
|
||||
- iterative improvement loop with benchmark thinking
|
||||
|
||||
Primary gaps:
|
||||
|
||||
- heavier process cost
|
||||
- more suitable for high-value skills than quick one-offs
|
||||
- some workflow assumptions are tied to a specific runtime style
|
||||
|
||||
Use it for:
|
||||
|
||||
- trigger eval design
|
||||
- benchmark loops
|
||||
- systematic improvement of important skills
|
||||
|
||||
## Template-First Scaffold
|
||||
|
||||
Primary strengths:
|
||||
|
||||
- fast onboarding
|
||||
- clean scaffold
|
||||
- easy explanation of required fields
|
||||
- good for normalizing team authoring habits
|
||||
|
||||
Primary gaps:
|
||||
|
||||
- shallow evaluation model
|
||||
- limited operations guidance after scaffolding
|
||||
- more a template than a full skill engineering system
|
||||
|
||||
Use it for:
|
||||
|
||||
- starter layout
|
||||
- contributor onboarding
|
||||
- low-friction authoring workflow
|
||||
|
||||
## Factory-First Builder
|
||||
|
||||
Primary strengths:
|
||||
|
||||
- strongest productization instinct
|
||||
- cross-platform packaging and export thinking
|
||||
- validation, security, staleness, and registry mindset
|
||||
- closest to a skill factory instead of a skill template
|
||||
|
||||
Primary gaps:
|
||||
|
||||
- heavier system and maintenance cost
|
||||
- portability requires adaptation layers in practice
|
||||
- may be excessive for small personal skills
|
||||
|
||||
Use it for:
|
||||
|
||||
- distribution and registry model
|
||||
- packaging lifecycle
|
||||
- maintenance and governance thinking
|
||||
|
||||
## Yao Synthesis
|
||||
|
||||
The right synthesis is:
|
||||
|
||||
- **structure-first for clarity**
|
||||
- **eval-first for reliability**
|
||||
- **template-first for onboarding**
|
||||
- **factory-first for operations and scale**
|
||||
|
||||
That combination yields a meta-skill that is:
|
||||
|
||||
- lightweight enough to use often
|
||||
- rigorous enough for important skills
|
||||
- structured enough for team adoption
|
||||
- operational enough for long-term reuse
|
||||
@@ -1,68 +0,0 @@
|
||||
# Meta-Skill Rubric
|
||||
|
||||
Score each generated skill from 1 to 5 on each dimension.
|
||||
|
||||
## 1. Trigger Clarity
|
||||
|
||||
Questions:
|
||||
|
||||
- Does the description say what the skill does?
|
||||
- Does it say when to use it?
|
||||
- Does it include realistic trigger phrases and adjacent cases?
|
||||
- Is it likely to reduce under-triggering?
|
||||
|
||||
## 2. Boundary Clarity
|
||||
|
||||
Questions:
|
||||
|
||||
- Is the skill solving one coherent capability family?
|
||||
- Are unrelated tasks excluded?
|
||||
- Are variants separated cleanly into references or sibling skills?
|
||||
|
||||
## 3. Context Efficiency
|
||||
|
||||
Questions:
|
||||
|
||||
- Is `SKILL.md` lean?
|
||||
- Are details pushed into `references/`?
|
||||
- Are scripts used where prose would be brittle or repetitive?
|
||||
|
||||
## 4. Execution Reliability
|
||||
|
||||
Questions:
|
||||
|
||||
- Are the workflow steps actionable?
|
||||
- Are critical constraints explicit?
|
||||
- Are deterministic steps captured in scripts or templates?
|
||||
- Is there a clear failure-handling path?
|
||||
|
||||
## 5. Evaluation Quality
|
||||
|
||||
Questions:
|
||||
|
||||
- Are there realistic usage prompts?
|
||||
- Are there trigger positives and negatives for important skills?
|
||||
- Is there a way to compare revisions?
|
||||
|
||||
## 6. Reuse And Maintenance
|
||||
|
||||
Questions:
|
||||
|
||||
- Can another teammate discover and reuse the skill?
|
||||
- Is `agents/interface.yaml` aligned with the package?
|
||||
- Are ownership and future iteration obvious?
|
||||
|
||||
## 7. Portability
|
||||
|
||||
Questions:
|
||||
|
||||
- Does the package stay close to the open format?
|
||||
- Are tool-specific assumptions minimized or isolated?
|
||||
- Can the skill be adapted to another compatible client without rewrite?
|
||||
|
||||
## Interpretation
|
||||
|
||||
- `30+`: production-ready
|
||||
- `24-29`: solid but improve weak dimensions
|
||||
- `18-23`: usable draft, not yet robust
|
||||
- `<18`: redesign the boundary or trigger strategy
|
||||
@@ -1,88 +0,0 @@
|
||||
# Skill Template
|
||||
|
||||
Use this skeleton when generating a new skill.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: Describe what the skill does and when to use it. Include realistic trigger phrases, task types, artifacts, or adjacent scenarios that should activate it.
|
||||
metadata:
|
||||
author: Your team
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
One-sentence summary of the capability.
|
||||
|
||||
## When To Use This Skill
|
||||
|
||||
- Trigger scenario 1
|
||||
- Trigger scenario 2
|
||||
- Trigger scenario 3
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Understand the request
|
||||
|
||||
- Identify the actual job to be done
|
||||
- Check assumptions and inputs
|
||||
|
||||
### 2. Choose the path
|
||||
|
||||
- Use path A when ...
|
||||
- Use path B when ...
|
||||
|
||||
### 3. Execute
|
||||
|
||||
- Step 1
|
||||
- Step 2
|
||||
- Step 3
|
||||
|
||||
### 4. Validate
|
||||
|
||||
- Minimum acceptance checks
|
||||
|
||||
## Reference Map
|
||||
|
||||
- Read `[topic-a](references/topic-a.md)` when ...
|
||||
- Read `[topic-b](references/topic-b.md)` when ...
|
||||
```
|
||||
|
||||
## Optional Folders
|
||||
|
||||
Create only when justified:
|
||||
|
||||
- `agents/interface.yaml`
|
||||
- `references/`
|
||||
- `scripts/`
|
||||
- `assets/`
|
||||
- `evals/`
|
||||
|
||||
## agents/interface.yaml Template
|
||||
|
||||
```yaml
|
||||
interface:
|
||||
display_name: "Human Friendly Name"
|
||||
short_description: "Short capability summary"
|
||||
default_prompt: "Use $skill-name to ..."
|
||||
compatibility:
|
||||
canonical_format: "agent-skills"
|
||||
adapter_targets:
|
||||
- "openai"
|
||||
- "claude"
|
||||
- "generic"
|
||||
activation:
|
||||
mode: "manual"
|
||||
paths: []
|
||||
execution:
|
||||
context: "inline"
|
||||
shell: "bash"
|
||||
trust:
|
||||
source_tier: "local"
|
||||
remote_inline_execution: "forbid"
|
||||
remote_metadata_policy: "allow-metadata-only"
|
||||
degradation:
|
||||
openai: "metadata-adapter"
|
||||
claude: "neutral-source-plus-adapter"
|
||||
generic: "neutral-source"
|
||||
```
|
||||
@@ -1,67 +0,0 @@
|
||||
# Skill Design Guidelines
|
||||
|
||||
This document captures the operating rules for `yao-meta-skill`.
|
||||
|
||||
## 1. Treat Skill Creation As Product Design
|
||||
|
||||
A generated skill should answer these questions clearly:
|
||||
|
||||
- What exact recurring job does this package improve?
|
||||
- Who is the intended user or agent?
|
||||
- What is in scope and out of scope?
|
||||
- What should be stable across runs?
|
||||
- What is expected to evolve over time?
|
||||
|
||||
## 2. Separate Three Kinds Of Content
|
||||
|
||||
Put each kind of content in the right place:
|
||||
|
||||
- `SKILL.md`: core workflow, trigger surface, decision rules
|
||||
- `references/`: detailed domain material, examples, schemas, policy docs
|
||||
- `scripts/`: deterministic or brittle operations
|
||||
|
||||
If you mix all three into `SKILL.md`, quality and maintainability drop fast.
|
||||
|
||||
## 3. Use A Trigger Matrix
|
||||
|
||||
Every important skill should have a trigger matrix:
|
||||
|
||||
- positive prompts
|
||||
- clear negatives
|
||||
- near neighbors
|
||||
|
||||
The goal is not just "can it trigger", but "does it trigger at the right boundary".
|
||||
|
||||
## 4. Keep The Body Small On Purpose
|
||||
|
||||
Do not optimize only for completeness.
|
||||
|
||||
Optimize for:
|
||||
|
||||
- low context cost
|
||||
- clear branch selection
|
||||
- discoverable references
|
||||
- safe defaults
|
||||
|
||||
## 5. Add Lifecycle Metadata Only When It Helps
|
||||
|
||||
For personal or disposable skills, extra metadata can be noise.
|
||||
|
||||
For shared skills, a `manifest.json` is useful for:
|
||||
|
||||
- owner
|
||||
- version
|
||||
- updated_at
|
||||
- target platforms
|
||||
- review cadence
|
||||
|
||||
## 6. Prefer Progressive Industrialization
|
||||
|
||||
Move through these stages:
|
||||
|
||||
1. Working draft
|
||||
2. Trigger-hardened draft
|
||||
3. Reusable team skill
|
||||
4. Governed skill asset
|
||||
|
||||
Do not start every skill at stage 4.
|
||||
@@ -6,10 +6,10 @@
|
||||
"context_budget_tier": "production",
|
||||
"context_budget_limit": 1000,
|
||||
"skill_body_tokens": 795,
|
||||
"other_text_tokens": 263995,
|
||||
"other_text_tokens": 233598,
|
||||
"estimated_initial_load_tokens": 971,
|
||||
"estimated_total_text_tokens": 264790,
|
||||
"relevant_file_count": 136,
|
||||
"estimated_total_text_tokens": 234393,
|
||||
"relevant_file_count": 129,
|
||||
"unused_resource_dirs": [],
|
||||
"quality_signal_points": 130,
|
||||
"quality_density": 133.9
|
||||
|
||||
Reference in New Issue
Block a user