Skip to content

Commit 14cf497

Browse files
hyunhee-joclaude
hyunhee-jo
and
claude
committed
Add: built-in agent skill for AI coding assistants (agentskills.io)
Objective: AI coding assistants (Claude Code, Codex, Cursor, etc.) have no way to know how to use opendataloader-pdf optimally. Users must manually figure out which of 26 options, 7 formats, and 3 install methods to use for their specific PDF type and downstream pipeline. Approach: Ship a built-in agent skill at skills/odl-pdf/ following the agentskills.io spec. The skill acts as a Document Intelligence Engineer persona that detects the user's environment, recommends optimal options via decision trees, executes conversions directly, and diagnoses quality issues with metric-driven escalation (local → cluster → hybrid → hybrid-mode full). Key design decisions: - Dual-path option reference (built-in summary + dynamic options.json) so pip-install users without source code also get full guidance - Progressive disclosure (L1 description → L2 SKILL.md → L3 references) to minimize token usage - CI drift check (skill-drift-check.yml) catches option/skill mismatch when CLI options change in Java New files: - skills/odl-pdf/ — SKILL.md, 5 references, 3 scripts, evals - skills/README.md — skill creation and maintenance guide - .claude-plugin/marketplace.json — plugin registry - .github/workflows/skill-drift-check.yml — CI drift detection Updated: README.md (Agent Skills section), CLAUDE.md (skill dev notes), CONTRIBUTING.md (skill maintenance guide) Evidence: Ran 5 eval scenarios via independent AI agents with zero prior knowledge of opendataloader-pdf. Each agent loaded only SKILL.md and responded to user queries. All 5 passed must_mention/must_not_mention checks covering RAG pipelines, Korean OCR, table diagnostics, Windows Node.js hybrid setup, and formula+chart enrichment. Drift check (sync-skill-refs.py) confirmed 26/26 options in sync. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent e134531 commit 14cf497

File tree

18 files changed

+2595
-0
lines changed

18 files changed

+2595
-0
lines changed

‎.claude-plugin/marketplace.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"name": "opendataloader-pdf",
3+
"owner": {
4+
"name": "OpenDataLoader Project"
5+
},
6+
"metadata": {
7+
"description": "AI-powered PDF extraction guidance and automation",
8+
"version": "1.0.0"
9+
},
10+
"plugins": [
11+
{
12+
"name": "odl-pdf-skills",
13+
"description": "Expert guidance for opendataloader-pdf — environment detection, option recommendations, hybrid mode setup, quality diagnostics, and direct conversion execution",
14+
"source": "./",
15+
"skills": [
16+
"./skills/odl-pdf"
17+
]
18+
}
19+
]
20+
}

‎.github/workflows/skill-drift-check.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# skill-drift-check.yml
2+
# Ensures skill references stay in sync with options.json when CLI options change.
3+
# Runs sync-skill-refs.py and fails the check if drift is detected (exit code 1).
4+
5+
name: Skill Drift Check
6+
7+
on:
8+
push:
9+
paths:
10+
- 'options.json'
11+
pull_request:
12+
paths:
13+
- 'options.json'
14+
workflow_dispatch:
15+
16+
jobs:
17+
check-drift:
18+
runs-on: ubuntu-latest
19+
steps:
20+
- uses: actions/checkout@v4
21+
22+
- uses: actions/setup-python@v5
23+
with:
24+
python-version: '3.12'
25+
26+
- name: Check skill drift
27+
run: |
28+
python skills/odl-pdf/scripts/sync-skill-refs.py
29+
if [ $? -ne 0 ]; then
30+
echo ""
31+
echo "Drift detected: skill references are out of sync with options.json."
32+
echo "Run 'python skills/odl-pdf/scripts/sync-skill-refs.py --fix' locally to update them."
33+
exit 1
34+
fi

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,3 +76,4 @@ logs/
7676
.claude/settings.local.json
7777
.claude/plans/
7878

79+
skills/odl-pdf/scripts/__pycache__/

‎CLAUDE.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,15 @@ Hidden text detection (`--filter-hidden-text`) is **off by default** — it requ
2121
- `./scripts/bench.sh --check-regression` — CI mode with threshold check
2222
- Benchmark code lives in [opendataloader-bench](https://github.com/opendataloader-project/opendataloader-bench)
2323
- Metrics: **NID** (reading order), **TEDS** (table structure), **MHS** (heading structure), **Table Detection F1**, **Speed**
24+
25+
## Agent Skills
26+
27+
`skills/odl-pdf/` contains the public agent skill shipped with this project.
28+
29+
When adding or changing CLI options in Java:
30+
1. Run `npm run sync` (regenerates options.json + Python/Node bindings)
31+
2. Update `skills/odl-pdf/references/options-matrix.md` with the new option
32+
3. CI (`skill-drift-check.yml`) will warn if step 2 is missed
33+
34+
The skill is written in English for external users. Do not include internal
35+
team terminology or company-specific policies.

‎CONTRIBUTING.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,5 +134,19 @@ git commit -s -m "your message"
134134

135135
Make sure your Git config contains your real name and email.
136136

137+
## Agent Skills Maintenance
138+
139+
This project ships a built-in agent skill at `skills/odl-pdf/`. When you add
140+
or modify CLI options:
141+
142+
1. Run `npm run sync` as usual
143+
2. Update `skills/odl-pdf/references/options-matrix.md` — add the new option
144+
to the appropriate category with its type, default, and description
145+
3. If the new option has interaction rules with existing options (e.g., requires
146+
another option to be set), document the rule in the "Interaction Rules" section
147+
148+
The CI workflow `skill-drift-check.yml` will flag any mismatch between
149+
`options.json` and `options-matrix.md`.
150+
137151
Thank you again for helping us improve this project! 🙌
138152
If you have any questions, open an issue or join the discussion.

‎README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -451,6 +451,31 @@ Existing PDFs (untagged)
451451

452452
[PDF Accessibility Guide](https://opendataloader.org/docs/accessibility-compliance)
453453

454+
## Agent Skills
455+
456+
Your AI coding agent knows how to use opendataloader-pdf — optimal options,
457+
hybrid mode setup, and quality diagnostics, all handled automatically.
458+
459+
Works with **Claude Code**, **Codex**, **Gemini CLI**, **Cursor**, **VS Code**, and 26+ platforms via [agentskills.io](https://agentskills.io) spec.
460+
461+
### What the Skill Does
462+
463+
| Phase | Description |
464+
|-------|-------------|
465+
| **Discover** | Detects your OS, Java, Python, Node.js, and ODL installation |
466+
| **Prescribe** | Recommends optimal install method, options, format, and mode |
467+
| **Execute** | Generates ready-to-run commands or runs conversions directly |
468+
| **Diagnose** | Identifies quality issues and escalates (local → cluster → hybrid) |
469+
| **Optimize** | Tunes batch processing, RAG integration, and performance |
470+
471+
### Install
472+
473+
```bash
474+
npx skills add opendataloader-project/opendataloader-pdf --skill odl-pdf
475+
```
476+
477+
Or use the `/odl-pdf` slash command in Claude Code after installing the plugin.
478+
454479
## Roadmap
455480

456481
| Feature | Timeline | Tier |

‎skills/README.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# Agent Skills
2+
3+
opendataloader-pdf ships built-in agent skills that help AI coding assistants use this project effectively. Skills follow the [agentskills.io](https://agentskills.io) specification and work with Claude Code, Codex, Gemini CLI, Cursor, VS Code, and 26+ platforms.
4+
5+
## Directory Structure
6+
7+
```
8+
skills/
9+
├── README.md ← You are here
10+
└── odl-pdf/ ← One skill per directory
11+
├── SKILL.md ← Main skill file (loaded when activated)
12+
├── references/ ← Deep-dive docs (loaded on demand)
13+
│ ├── options-matrix.md
14+
│ ├── hybrid-guide.md
15+
│ ├── format-guide.md
16+
│ ├── installation-matrix.md
17+
│ └── eval-metrics.md
18+
├── scripts/ ← Executable helpers
19+
│ ├── detect-env.sh
20+
│ ├── hybrid-health.sh
21+
│ ├── quick-eval.py
22+
│ └── sync-skill-refs.py
23+
└── evals/ ← Quality test cases
24+
└── evals.json
25+
```
26+
27+
## How Skills Work
28+
29+
### Progressive Disclosure (3 Levels)
30+
31+
| Level | Content | When Loaded |
32+
|-------|---------|-------------|
33+
| **L1** | `description` field in SKILL.md frontmatter (~100 words) | Always visible to skill router |
34+
| **L2** | SKILL.md body (~400 lines) — persona, workflows, decision trees, gotchas | When skill is activated |
35+
| **L3** | `references/*` files — detailed option matrices, guides, metrics | When the user enters that topic |
36+
37+
This design minimizes token usage. The AI agent only loads what it needs for the current task.
38+
39+
### Dual-Path Option Reference
40+
41+
Skills must work for **both** source-code users and pip-install users:
42+
43+
- **Built-in summaries** (`references/options-matrix.md`): Always available, even without source code
44+
- **Dynamic reference** (`options.json`): Authoritative source when the source repo is available
45+
46+
SKILL.md instructs the AI: "If `options.json` exists in this project, it is the source of truth. Options in `options.json` not found in `options-matrix.md` are newly added."
47+
48+
## Creating a New Skill
49+
50+
### 1. Create the Directory
51+
52+
```
53+
skills/my-skill/
54+
├── SKILL.md
55+
├── references/ (optional)
56+
├── scripts/ (optional)
57+
└── evals/ (optional)
58+
```
59+
60+
### 2. Write SKILL.md
61+
62+
The SKILL.md file has two parts:
63+
64+
**Frontmatter** (YAML between `---` markers):
65+
66+
```yaml
67+
---
68+
name: my-skill
69+
description: >
70+
One paragraph (~100 words) explaining what this skill does.
71+
Include trigger keywords so the skill router knows when to activate.
72+
Include "Do NOT use for:" to prevent false activations.
73+
---
74+
```
75+
76+
**Body** (Markdown):
77+
78+
- Define a persona (who the AI becomes when this skill is active)
79+
- Define a workflow (numbered phases the AI follows)
80+
- Include decision trees for common choices
81+
- List critical gotchas the AI must always warn about
82+
- Reference deeper docs with: "See `references/filename.md` for details"
83+
84+
### 3. Write Evals
85+
86+
Create `evals/evals.json` with test scenarios:
87+
88+
```json
89+
{
90+
"version": "1.0",
91+
"skill": "my-skill",
92+
"evals": [
93+
{
94+
"id": "eval-001",
95+
"scenario": "Description of the user's situation",
96+
"user_input": "What the user says",
97+
"expected_recommendations": ["What the AI should recommend"],
98+
"must_mention": ["Required terms in the response"],
99+
"must_not_mention": ["Forbidden terms"]
100+
}
101+
]
102+
}
103+
```
104+
105+
### 4. Register in marketplace.json
106+
107+
Add your skill to `.claude-plugin/marketplace.json`:
108+
109+
```json
110+
{
111+
"plugins": [{
112+
"skills": ["./skills/odl-pdf", "./skills/my-skill"]
113+
}]
114+
}
115+
```
116+
117+
### 5. Test
118+
119+
Test by spawning an AI agent that knows nothing about the project, loading only your SKILL.md, and asking it the eval scenarios. All `must_mention` terms should appear; no `must_not_mention` terms should appear.
120+
121+
## Modifying the Existing Skill
122+
123+
### When CLI Options Change
124+
125+
1. Run `npm run sync` (regenerates `options.json`)
126+
2. Update `skills/odl-pdf/references/options-matrix.md` — add the new option to the appropriate category
127+
3. If the option has interaction rules, document them in the "Interaction Rules" section
128+
4. CI (`skill-drift-check.yml`) will catch any mismatch you miss
129+
130+
### When Adding a New Hybrid Backend
131+
132+
1. Update `skills/odl-pdf/references/hybrid-guide.md` — add to the Backend Registry table
133+
2. SKILL.md's decision tree says "check `options.json` for allowed hybrid values" — new backends are auto-discovered
134+
135+
### When Adding a New Output Format
136+
137+
1. Update `skills/odl-pdf/references/format-guide.md` — add to the format table with downstream use mapping
138+
2. The format list in `options.json` is auto-discovered by the skill
139+
140+
## CI Integration
141+
142+
### Drift Check (`skill-drift-check.yml`)
143+
144+
Runs automatically when `options.json` changes. Compares option names in `options.json` against `options-matrix.md` and fails if they diverge.
145+
146+
Run manually:
147+
148+
```bash
149+
python skills/odl-pdf/scripts/sync-skill-refs.py
150+
```
151+
152+
## Writing Guidelines
153+
154+
- **Language**: English only (external open-source users)
155+
- **No internal terminology**: No company names, team names, or internal tool references
156+
- **Tone**: Senior engineer pair-programming — diagnose first, prescribe later
157+
- **Java guidance**: Always mention Java 11+ requirement. Never recommend specific JDK distributions or download links.
158+
- **Gotchas**: Only include gotchas that affect external users. Internal development gotchas belong in CLAUDE.md.
159+
160+
## References
161+
162+
- [agentskills.io specification](https://agentskills.io) — Multi-agent skill format standard
163+
- [Claude Code Skills](https://docs.anthropic.com/en/docs/claude-code) — Claude Code skill documentation
164+
- `.claude-plugin/marketplace.json` — Plugin registration for this project
165+
- `CLAUDE.md` — Internal development notes (not for the skill)
166+
- `CONTRIBUTING.md` — Contributor guidelines including skill maintenance

0 commit comments

Comments
 (0)